Home • Explore • Blog • CI
☰



postgresql
6th chunk of `doc/src/sgml/ref/create_cast.sgml`
b3e74fedf18b2a3905a5a3b9b03c1c23a960f1d56dfe6aee0000000100000d65
 old
   convention of naming cast implementation functions after the target data
   type.  Many users are used to being able to cast data types using a
   function-style notation, that is
   <replaceable>typename</replaceable>(<replaceable>x</replaceable>).  This notation is in fact
   nothing more nor less than a call of the cast implementation function; it
   is not specially treated as a cast.  If your conversion functions are not
   named to support this convention then you will have surprised users.
   Since <productname>PostgreSQL</productname> allows overloading of the same function
   name with different argument types, there is no difficulty in having
   multiple conversion functions from different types that all use the
   target type's name.
  </para>

  <note>
   <para>
    Actually the preceding paragraph is an oversimplification: there are
    two cases in which a function-call construct will be treated as a cast
    request without having matched it to an actual function.
    If a function call <replaceable>name</replaceable>(<replaceable>x</replaceable>) does not
    exactly match any existing function, but <replaceable>name</replaceable> is the name
    of a data type and <structname>pg_cast</structname> provides a binary-coercible cast
    to this type from the type of <replaceable>x</replaceable>, then the call will be
    construed as a binary-coercible cast.  This exception is made so that
    binary-coercible casts can be invoked using functional syntax, even
    though they lack any function.  Likewise, if there is no
    <structname>pg_cast</structname> entry but the cast would be to or from a string
    type, the call will be construed as an I/O conversion cast.  This
    exception allows I/O conversion casts to be invoked using functional
    syntax.
   </para>
  </note>

  <note>
   <para>
    There is also an exception to the exception: I/O conversion casts from
    composite types to string types cannot be invoked using functional
    syntax, but must be written in explicit cast syntax (either
    <literal>CAST</literal> or <literal>::</literal> notation).  This exception was added
    because after the introduction of automatically-provided I/O conversion
    casts, it was found too easy to accidentally invoke such a cast when
    a function or column reference was intended.
   </para>
  </note>
 </refsect1>


 <refsect1 id="sql-createcast-examples">
  <title>Examples</title>

  <para>
   To create an assignment cast from type <type>bigint</type> to type
   <type>int4</type> using the function <literal>int4(bigint)</literal>:
<programlisting>
CREATE CAST (bigint AS int4) WITH FUNCTION int4(bigint) AS ASSIGNMENT;
</programlisting>
   (This cast is already predefined in the system.)
  </para>
 </refsect1>

 <refsect1 id="sql-createcast-compat">
  <title>Compatibility</title>

  <para>
   The <command>CREATE CAST</command> command conforms to the
   <acronym>SQL</acronym> standard,
   except that SQL does not make provisions for binary-coercible
   types or extra arguments to implementation functions.
   <literal>AS IMPLICIT</literal> is a <productname>PostgreSQL</productname>
   extension, too.
  </para>
 </refsect1>


 <refsect1 id="sql-createcast-seealso">
  <title>See Also</title>

  <para>
   <xref linkend="sql-createfunction"/>,
   <xref linkend="sql-createtype"/>,
   <xref linkend="sql-dropcast"/>
  </para>
 </refsect1>

</refentry>
Title: Function-Style Casting, Exceptions, and Examples of CREATE CAST
Summary
This section clarifies that the `typename(x)` function-style notation for casting is simply a function call to the cast implementation function. It also notes exceptions: if a function call matches a datatype name and there's a binary-coercible cast, it's treated as a binary-coercible cast even without a function. Similarly, if there's no pg_cast entry but the cast involves a string type, it's treated as an I/O conversion cast. The section then shows an example of how to create a cast and mentions that CREATE CAST largely conforms to the SQL standard, except for binary-coercible types and extra implementation function arguments. It also notes that `AS IMPLICIT` is a PostgreSQL extension.