From 092bc4965378840479e0250ae679e1d8e86577ee Mon Sep 17 00:00:00 2001
From: Heikki Linnakangas
Date: Fri, 31 Oct 2008 08:39:22 +0000
Subject: Add support for user-defined I/O conversion casts.

---
 doc/src/sgml/catalogs.sgml        | 23 +++++++++++++++++------
 doc/src/sgml/ref/create_cast.sgml | 38 +++++++++++++++++++++++++++++---------
 2 files changed, 46 insertions(+), 15 deletions(-)

(limited to 'doc/src')

diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
index a68799334a..faee42ba10 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.179 2008/10/17 22:10:29 tgl Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/catalogs.sgml,v 2.180 2008/10/31 08:39:19 heikki Exp $ -->
 <!--
  Documentation of the system catalogs, directed toward PostgreSQL developers
  -->
@@ -1415,9 +1415,10 @@
    cannot be deduced from some generic rule.  For example, casting between a
    domain and its base type is not explicitly represented in
    <structname>pg_cast</structname>.  Another important exception is that
-   <quote>I/O conversion casts</>, those performed using a data type's own
-   I/O functions to convert to or from <type>text</> or other string types,
-   are not explicitly represented in <structname>pg_cast</structname>.
+   <quote>automatic I/O conversion casts</>, those performed using a data
+   type's own I/O functions to convert to or from <type>text</> or other
+   string types, are not explicitly represented in
+   <structname>pg_cast</structname>.
   </para>
 
   <table>
@@ -1454,8 +1455,7 @@
       <entry><literal><link linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.oid</literal></entry>
       <entry>
        The OID of the function to use to perform this cast.  Zero is
-       stored if the data types are binary coercible (that is, no
-       run-time operation is needed to perform the cast)
+       stored if the cast method doesn't require a function.
       </entry>
      </row>
 
@@ -1473,6 +1473,17 @@
        other cases
       </entry>
      </row>
+     <row>
+      <entry><structfield>castmethod</structfield></entry>
+      <entry><type>char</type></entry>
+      <entry></entry>
+      <entry>
+       Indicates how the cast is performed.
+       <literal>f</> means that the function specified in the <structfield>castfunc</> field is used.
+       <literal>i</> means that the input/output functions are used.
+       <literal>b</> means that the types are binary-coercible, thus no conversion is required
+      </entry>
+     </row>
     </tbody>
    </tgroup>
   </table>
diff --git a/doc/src/sgml/ref/create_cast.sgml b/doc/src/sgml/ref/create_cast.sgml
index 080f31832d..c771d22ad9 100644
--- a/doc/src/sgml/ref/create_cast.sgml
+++ b/doc/src/sgml/ref/create_cast.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/create_cast.sgml,v 1.29 2008/07/30 21:23:17 tgl Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/create_cast.sgml,v 1.30 2008/10/31 08:39:20 heikki Exp $ -->
 
 <refentry id="SQL-CREATECAST">
  <refmeta>
@@ -24,6 +24,10 @@ CREATE CAST (<replaceable>sourcetype</replaceable> AS <replaceable>targettype</r
 CREATE CAST (<replaceable>sourcetype</replaceable> AS <replaceable>targettype</replaceable>)
     WITHOUT FUNCTION
     [ AS ASSIGNMENT | AS IMPLICIT ]
+
+CREATE CAST (<replaceable>sourcetype</replaceable> AS <replaceable>targettype</replaceable>)
+    WITH INOUT
+    [ AS ASSIGNMENT | AS IMPLICIT ]
 </synopsis>
  </refsynopsisdiv>
 
@@ -58,6 +62,13 @@ SELECT CAST(42 AS float8);
    binary compatible.)
   </para>
 
+  <para>
+   You can define a cast as an <firstterm>I/O conversion cast</> using
+   the <literal>WITH INOUT</literal> syntax. An I/O conversion cast is
+   performed by invoking the output function of the source data type, and
+   passing the result to the input function of the target data type.
+  </para>
+
   <para>
    By default, a cast can be invoked only by an explicit cast request,
    that is an explicit <literal>CAST(<replaceable>x</> AS
@@ -199,6 +210,18 @@ SELECT CAST ( 2 AS numeric ) + 4.0;
      </listitem>
     </varlistentry>
 
+    <varlistentry>
+     <term><literal>WITH INOUT</literal></term>
+
+     <listitem>
+      <para>
+       Indicates that the cast is an I/O conversion cast, performed by
+       invoking the output function of the source data type, and passing the
+       result to the input function of the target data type.
+      </para>
+     </listitem>
+    </varlistentry>
+
     <varlistentry>
      <term><literal>AS ASSIGNMENT</literal></term>
 
@@ -284,15 +307,12 @@ SELECT CAST ( 2 AS numeric ) + 4.0;
    It is normally not necessary to create casts between user-defined types
    and the standard string types (<type>text</>, <type>varchar</>, and
    <type>char(<replaceable>n</>)</type>, as well as user-defined types that
-   are defined to be in the string category).  <productname>PostgreSQL</> will
-   automatically handle a cast to a string type by invoking the other
-   type's output function, or conversely handle a cast from a string type
-   by invoking the other type's input function.  These
-   automatically-provided casts are known as <firstterm>I/O conversion
-   casts</>.  I/O conversion casts to string types are treated as
-   assignment casts, while I/O conversion casts from string types are
+   are defined to be in the string category).  <productname>PostgreSQL</>
+   provides automatic I/O conversion casts for that. The automatic casts to
+   string types are treated as assignment casts, while the automatic casts
+   from string types are
    explicit-only.  You can override this behavior by declaring your own
-   cast to replace an I/O conversion cast, but usually the only reason to
+   cast to replace an automatic cast, but usually the only reason to
    do so is if you want the conversion to be more easily invokable than the
    standard assignment-only or explicit-only setting.  Another possible
    reason is that you want the conversion to behave differently from the
-- 
cgit v1.2.3