postgresql/doc/src/sgml/xtypes.sgml

 <chapter id="xtypes">
  <title>Extending <acronym>SQL</acronym>: Types</title>
  <para>
   As previously mentioned, there are two kinds  of  types
   in  <productname>Postgres</productname>: base types (defined in a programming language) 
   and composite types (instances).
   Examples in this section up to interfacing indices  can
   be  found in <filename>complex.sql</filename> and <filename>complex.c</filename>.  Composite examples 
   are in <filename>funcs.sql</filename>.
  </para>

  <sect1>
   <title>User-Defined Types</title>

   <sect2>
    <title>Functions Needed for a User-Defined Type</title>
    <para>
     A  user-defined  type must always have input and output
     functions.  These  functions  determine  how  the  type
     appears in strings (for input by the user and output to
     the user) and how the type is organized in memory.  The
     input  function takes a null-delimited character string
     as its input and returns the internal (in memory)  
     representation of the type.  The output function takes the
     internal representation of the type and returns a null
     delimited character string.
     Suppose  we  want to define a complex type which represents 
     complex numbers. Naturally, we choose  to  represent a 
     complex in memory as the following <acronym>C</acronym> structure:

     <programlisting>
typedef struct Complex {
    double      x;
    double      y;
} Complex;
     </programlisting>

     and  a  string of the form (x,y) as the external string
     representation.
     These functions are usually not hard  to  write,  especially  
     the output function.  However, there are a number of points 
     to remember:

     <itemizedlist>
      <listitem>
       <para>  When defining your external (string) representation,  
	remember that you must eventually write a
	complete and robust parser for that  representation 
	as your input function!

	<programlisting>
Complex *
complex_in(char *str)
{
    double x, y;
    Complex *result;
    if (sscanf(str, " ( %lf , %lf )", &amp;x, &amp;y) != 2) {
        elog(NOTICE, "complex_in: error in parsing
        return NULL;
    }
    result = (Complex *)palloc(sizeof(Complex));
    result-&gt;x = x;
    result-&gt;y = y;
    return (result);
}
	</programlisting>

	The output function can simply be:

	<programlisting>
char *
complex_out(Complex *complex)
{
    char *result;
    if (complex == NULL)
        return(NULL);
    result = (char *) palloc(60);
    sprintf(result, "(%g,%g)", complex-&gt;x, complex-&gt;y);
    return(result);
}
	</programlisting>

       </para>
      </listitem>
      <listitem>
       <para>
	You  should  try  to  make  the input and output
	functions inverses of each  other.   If  you  do
	not, you will have severe problems when you need
	to dump your data into a file and then  read  it
	back  in  (say,  into someone else's database on
	another computer).  This is a particularly  common  
	problem  when  floating-point  numbers  are
	involved.
       </para>
      </listitem>
     </itemizedlist>
    </para>
    <para>
     To define the <acronym>complex</acronym> type, we need to create  the  two
     user-defined   functions   complex_in  and  complex_out
     before creating the type:

     <programlisting>
CREATE FUNCTION complex_in(opaque)
    RETURNS complex
    AS 'PGROOT/tutorial/obj/complex.so'
    LANGUAGE 'c';

CREATE FUNCTION complex_out(opaque)
    RETURNS opaque
    AS 'PGROOT/tutorial/obj/complex.so'
    LANGUAGE 'c';

CREATE TYPE complex (
    internallength = 16,
    input = complex_in,
    output = complex_out
);
     </programlisting>
    </para>

    <para>
     As discussed earlier, <productname>Postgres</productname> fully supports arrays of
     base  types.  Additionally, <productname>Postgres</productname> supports arrays of
     user-defined types as well.  When you  define  a  type,
     <productname>Postgres</productname>  automatically  provides support for arrays of
     that type.  For historical reasons, the array type  has
     the  same name as the user-defined type with the 
     underscore character _ prepended.
     Composite types do not need  any  function  defined  on
     them,  since  the  system already understands what they
     look like inside.
    </para>
   </sect2>

   <sect2>
    <title>Large Objects</title>

    <para>
     The types discussed  to  this  point  are  all  "small"
     objects -- that is, they are smaller than 8KB in size.
     <note>
      <para>
       1024 longwords == 8192 bytes.  In fact, the type must be considerably smaller than 8192 bytes,
       since the <productname>Postgres</productname>  tuple
       and  page  overhead  must also fit into this 8KB limitation.
       The actual value that fits depends on the machine  architecture.
      </para>
     </note>
     If you require a larger type for something like a document  
     retrieval system or for storing bitmaps, you will
     need to use the <productname>Postgres</productname> large object
     interface, or will need to recompile the
     <productname>Postgres</productname> backend to use internal
     storage blocks greater than 8kbytes..
    </para>
   </sect2>
  </sect1>
 </chapter>

<!-- Keep this comment at the end of the file
Local variables:
mode:sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"./reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:("/usr/lib/sgml/catalog")
sgml-local-ecat-files:nil
End:
-->