Support type modifiers for user-defined types, and pull most knowledge

about typmod representation for standard types out into type-specific
typmod I/O functions.  Teodor Sigaev, with some editorialization by
Tom Lane.

3 files changed, 101 insertions, 34 deletions

diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
index a906623ac9a..2d42280f50e 100644
--- a/doc/src/sgml/catalogs.sgml
+++ b/doc/src/sgml/catalogs.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/catalogs.sgml,v 2.139 2006/12/23 00:43:08 tgl Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/catalogs.sgml,v 2.140 2006/12/30 21:21:52 tgl Exp $ -->
 <!--
  Documentation of the system catalogs, directed toward PostgreSQL developers
  -->
@@ -4394,6 +4394,20 @@
      </row>
 
      <row>
+      <entry><structfield>typmodin</structfield></entry>
+      <entry><type>regproc</type></entry>
+      <entry><literal><link linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.oid</literal></entry>
+      <entry>Type modifier input function, or 0 if type does not support modifiers</entry>
+     </row>
+
+     <row>
+      <entry><structfield>typmodout</structfield></entry>
+      <entry><type>regproc</type></entry>
+      <entry><literal><link linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.oid</literal></entry>
+      <entry>Type modifier output function, or 0 to use the standard format</entry>
+     </row>
+
+     <row>
       <entry><structfield>typanalyze</structfield></entry>
       <entry><type>regproc</type></entry>
       <entry><literal><link linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.oid</literal></entry>
diff --git a/doc/src/sgml/keywords.sgml b/doc/src/sgml/keywords.sgml
index c82b3b6f1b9..b9565b3283c 100644
--- a/doc/src/sgml/keywords.sgml
+++ b/doc/src/sgml/keywords.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/keywords.sgml,v 2.18 2006/10/08 20:51:52 petere Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/keywords.sgml,v 2.19 2006/12/30 21:21:52 tgl Exp $ -->
 
 <appendix id="sql-keywords-appendix">
  <title><acronym>SQL</acronym> Key Words</title>
@@ -45,16 +45,17 @@
   In <xref linkend="keywords-table"> in the column for
   <productname>PostgreSQL</productname> we classify as
   <quote>non-reserved</quote> those key words that are explicitly
-  known to the parser but are allowed in most or all contexts where an
-  identifier is expected.  Some key words that are otherwise
+  known to the parser but are allowed as column or table names.
+  Some key words that are otherwise
   non-reserved cannot be used as function or data type names and are
   marked accordingly.  (Most of these words represent built-in
   functions or data types with special syntax.  The function or type
   is still available but it cannot be redefined by the user.)  Labeled
-  <quote>reserved</quote> are those tokens that are only allowed as
-  <quote>AS</quote> column label names (and perhaps in very few other
-  contexts).  Some reserved key words are allowable as names for
-  functions; this is also shown in the table.
+  <quote>reserved</quote> are those tokens that are not allowed as
+  column or table names.  Some reserved key words are
+  allowable as names for functions or data types; this is also shown in the
+  table.  If not so marked, a reserved key word is only allowed as an
+  <quote>AS</quote> column label name.
  </para>
 
  <para>
@@ -326,7 +327,7 @@
    </row>
    <row>
     <entry><token>AUTHORIZATION</token></entry>
-    <entry>reserved (can be function)</entry>
+    <entry>reserved (can be function or type)</entry>
     <entry>reserved</entry>
     <entry>reserved</entry>
     <entry>reserved</entry>
@@ -368,7 +369,7 @@
    </row>
    <row>
     <entry><token>BETWEEN</token></entry>
-    <entry>reserved (can be function)</entry>
+    <entry>reserved (can be function or type)</entry>
     <entry>reserved</entry>
     <entry>non-reserved</entry>
     <entry>reserved</entry>
@@ -382,7 +383,7 @@
    </row>
    <row>
     <entry><token>BINARY</token></entry>
-    <entry>reserved (can be function)</entry>
+    <entry>reserved (can be function or type)</entry>
     <entry>reserved</entry>
     <entry>reserved</entry>
     <entry></entry>
@@ -956,7 +957,7 @@
    </row>
    <row>
     <entry><token>CROSS</token></entry>
-    <entry>reserved (can be function)</entry>
+    <entry>reserved (can be function or type)</entry>
     <entry>reserved</entry>
     <entry>reserved</entry>
     <entry>reserved</entry>
@@ -1642,7 +1643,7 @@
    </row>
    <row>
     <entry><token>FREEZE</token></entry>
-    <entry>reserved (can be function)</entry>
+    <entry>reserved (can be function or type)</entry>
     <entry></entry>
     <entry></entry>
     <entry></entry>
@@ -1656,7 +1657,7 @@
    </row>
    <row>
     <entry><token>FULL</token></entry>
-    <entry>reserved (can be function)</entry>
+    <entry>reserved (can be function or type)</entry>
     <entry>reserved</entry>
     <entry>reserved</entry>
     <entry>reserved</entry>
@@ -1831,7 +1832,7 @@
    </row>
    <row>
     <entry><token>ILIKE</token></entry>
-    <entry>reserved (can be function)</entry>
+    <entry>reserved (can be function or type)</entry>
     <entry></entry>
     <entry></entry>
     <entry></entry>
@@ -1943,7 +1944,7 @@
    </row>
    <row>
     <entry><token>INNER</token></entry>
-    <entry>reserved (can be function)</entry>
+    <entry>reserved (can be function or type)</entry>
     <entry>reserved</entry>
     <entry>reserved</entry>
     <entry>reserved</entry>
@@ -2048,14 +2049,14 @@
    </row>
    <row>
     <entry><token>IS</token></entry>
-    <entry>reserved (can be function)</entry>
+    <entry>reserved (can be function or type)</entry>
     <entry>reserved</entry>
     <entry>reserved</entry>
     <entry>reserved</entry>
    </row>
    <row>
     <entry><token>ISNULL</token></entry>
-    <entry>reserved (can be function)</entry>
+    <entry>reserved (can be function or type)</entry>
     <entry></entry>
     <entry></entry>
     <entry></entry>
@@ -2076,7 +2077,7 @@
    </row>
    <row>
     <entry><token>JOIN</token></entry>
-    <entry>reserved (can be function)</entry>
+    <entry>reserved (can be function or type)</entry>
     <entry>reserved</entry>
     <entry>reserved</entry>
     <entry>reserved</entry>
@@ -2160,7 +2161,7 @@
    </row>
    <row>
     <entry><token>LEFT</token></entry>
-    <entry>reserved (can be function)</entry>
+    <entry>reserved (can be function or type)</entry>
     <entry>reserved</entry>
     <entry>reserved</entry>
     <entry>reserved</entry>
@@ -2188,7 +2189,7 @@
    </row>
    <row>
     <entry><token>LIKE</token></entry>
-    <entry>reserved (can be function)</entry>
+    <entry>reserved (can be function or type)</entry>
     <entry>reserved</entry>
     <entry>reserved</entry>
     <entry>reserved</entry>
@@ -2475,7 +2476,7 @@
    </row>
    <row>
     <entry><token>NATURAL</token></entry>
-    <entry>reserved (can be function)</entry>
+    <entry>reserved (can be function or type)</entry>
     <entry>reserved</entry>
     <entry>reserved</entry>
     <entry>reserved</entry>
@@ -2608,7 +2609,7 @@
    </row>
    <row>
     <entry><token>NOTNULL</token></entry>
-    <entry>reserved (can be function)</entry>
+    <entry>reserved (can be function or type)</entry>
     <entry></entry>
     <entry></entry>
     <entry></entry>
@@ -2811,7 +2812,7 @@
    </row>
    <row>
     <entry><token>OUTER</token></entry>
-    <entry>reserved (can be function)</entry>
+    <entry>reserved (can be function or type)</entry>
     <entry>reserved</entry>
     <entry>reserved</entry>
     <entry>reserved</entry>
@@ -2832,7 +2833,7 @@
    </row>
    <row>
     <entry><token>OVERLAPS</token></entry>
-    <entry>reserved (can be function)</entry>
+    <entry>reserved (can be function or type)</entry>
     <entry>reserved</entry>
     <entry>non-reserved</entry>
     <entry>reserved</entry>
@@ -3385,7 +3386,7 @@
    </row>
    <row>
     <entry><token>RIGHT</token></entry>
-    <entry>reserved (can be function)</entry>
+    <entry>reserved (can be function or type)</entry>
     <entry>reserved</entry>
     <entry>reserved</entry>
     <entry>reserved</entry>
@@ -3658,7 +3659,7 @@
    </row>
    <row>
     <entry><token>SIMILAR</token></entry>
-    <entry>reserved (can be function)</entry>
+    <entry>reserved (can be function or type)</entry>
     <entry>reserved</entry>
     <entry>non-reserved</entry>
     <entry></entry>
@@ -4414,7 +4415,7 @@
    </row>
    <row>
     <entry><token>VERBOSE</token></entry>
-    <entry>reserved (can be function)</entry>
+    <entry>reserved (can be function or type)</entry>
     <entry></entry>
     <entry></entry>
     <entry></entry>
diff --git a/doc/src/sgml/ref/create_type.sgml b/doc/src/sgml/ref/create_type.sgml
index e85c94dbe74..2f1f6eab3c4 100644
--- a/doc/src/sgml/ref/create_type.sgml
+++ b/doc/src/sgml/ref/create_type.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/create_type.sgml,v 1.65 2006/12/23 01:28:09 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/create_type.sgml,v 1.66 2006/12/30 21:21:52 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -28,6 +28,8 @@ CREATE TYPE <replaceable class="parameter">name</replaceable> (
     OUTPUT = <replaceable class="parameter">output_function</replaceable>
     [ , RECEIVE = <replaceable class="parameter">receive_function</replaceable> ]
     [ , SEND = <replaceable class="parameter">send_function</replaceable> ]
+    [ , TYPMOD_IN = <replaceable class="parameter">type_modifier_input_function</replaceable> ]
+    [ , TYPMOD_OUT = <replaceable class="parameter">type_modifier_output_function</replaceable> ]
     [ , ANALYZE = <replaceable class="parameter">analyze_function</replaceable> ]
     [ , INTERNALLENGTH = { <replaceable class="parameter">internallength</replaceable> | VARIABLE } ]
     [ , PASSEDBYVALUE ]
@@ -83,12 +85,14 @@ CREATE TYPE <replaceable class="parameter">name</replaceable>
    (scalar type).  The parameters may appear in any order, not only that
    illustrated above, and most are optional.  You must register
    two or more functions (using <command>CREATE FUNCTION</command>) before
-   defining the type.  The support functions 
+   defining the type.  The support functions
    <replaceable class="parameter">input_function</replaceable> and
    <replaceable class="parameter">output_function</replaceable>
    are required, while the functions
    <replaceable class="parameter">receive_function</replaceable>,
-   <replaceable class="parameter">send_function</replaceable> and
+   <replaceable class="parameter">send_function</replaceable>,
+   <replaceable class="parameter">type_modifier_input_function</replaceable>,
+   <replaceable class="parameter">type_modifier_output_function</replaceable> and
    <replaceable class="parameter">analyze_function</replaceable>
    are optional.  Generally these functions have to be coded in C
    or another low-level language.
@@ -170,6 +174,34 @@ CREATE TYPE <replaceable class="parameter">name</replaceable>
   </para>
 
   <para>
+   The optional
+   <replaceable class="parameter">type_modifier_input_function</replaceable>
+   and <replaceable class="parameter">type_modifier_output_function</replaceable>
+   are needed if the type supports modifiers, that is optional constraints
+   attached to a type declaration, such as <literal>char(5)</> or
+   <literal>numeric(30,2)</>.  <productname>PostgreSQL</productname> allows
+   user-defined types to take one or more integer constants as modifiers;
+   however, this information must be capable of being packed into a single
+   non-negative integer value for storage in the system catalogs.  The
+   <replaceable class="parameter">type_modifier_input_function</replaceable>
+   is passed the declared modifier(s) in the form of an <type>integer</>
+   array.  It must check the values for validity (throwing an error if they
+   are wrong), and if they are correct, return a single non-negative
+   <type>integer</> value that will be stored as the column <quote>typmod</>.
+   Type modifiers will be rejected if the type does not have a
+   <replaceable class="parameter">type_modifier_input_function</replaceable>.
+   The <replaceable class="parameter">type_modifier_output_function</replaceable>
+   converts the internal integer typmod value back to the correct form for
+   user display.  It must return a <type>cstring</> value that is the exact
+   string to append to the type name; for example <type>numeric</>'s
+   function might return <literal>(30,2)</>.
+   It is allowed to omit the
+   <replaceable class="parameter">type_modifier_output_function</replaceable>,
+   in which case the default display format is just the stored typmod value
+   enclosed in parentheses.
+  </para>
+
+  <para>
    The optional <replaceable class="parameter">analyze_function</replaceable>
    performs type-specific statistics collection for columns of the data type.
    By default, <command>ANALYZE</> will attempt to gather statistics using
@@ -265,7 +297,7 @@ CREATE TYPE <replaceable class="parameter">name</replaceable>
    <title>Array Types</title>
 
    <para>
-    Whenever a user-defined base data type is created, 
+    Whenever a user-defined base data type is created,
     <productname>PostgreSQL</productname> automatically creates an
     associated array type, whose name consists of the base type's
     name prepended with an underscore.  The parser understands this
@@ -298,7 +330,7 @@ CREATE TYPE <replaceable class="parameter">name</replaceable>
    </para>
   </refsect2>
  </refsect1>
-  
+
  <refsect1>
   <title>Parameters</title>
 
@@ -372,6 +404,26 @@ CREATE TYPE <replaceable class="parameter">name</replaceable>
    </varlistentry>
 
    <varlistentry>
+    <term><replaceable class="parameter">type_modifier_input_function</replaceable></term>
+    <listitem>
+     <para>
+      The name of a function that converts numeric modifier(s) for the type
+      into internal form.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><replaceable class="parameter">type_modifier_output_function</replaceable></term>
+    <listitem>
+     <para>
+      The name of a function that converts the internal form of the type's
+      modifier(s) to external textual form.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
     <term><replaceable class="parameter">analyze_function</replaceable></term>
     <listitem>
      <para>
@@ -499,7 +551,7 @@ CREATE TYPE <replaceable class="parameter">name</replaceable>
   </para>
 
  </refsect1>
- 
+
  <refsect1>
   <title>Examples</title>