diff options
Diffstat (limited to 'doc/src/sgml/ref/create_cast.sgml')
| -rw-r--r-- | doc/src/sgml/ref/create_cast.sgml | 232 |
1 files changed, 232 insertions, 0 deletions
diff --git a/doc/src/sgml/ref/create_cast.sgml b/doc/src/sgml/ref/create_cast.sgml new file mode 100644 index 0000000000..81259949f1 --- /dev/null +++ b/doc/src/sgml/ref/create_cast.sgml @@ -0,0 +1,232 @@ +<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/create_cast.sgml,v 1.1 2002/07/18 23:11:27 petere Exp $ --> + +<refentry id="SQL-CREATECAST"> + <refmeta> + <refentrytitle id="SQL-CREATECAST-TITLE">CREATE CAST</refentrytitle> + <refmiscinfo>SQL - Language Statements</refmiscinfo> + </refmeta> + + <refnamediv> + <refname>CREATE CAST</refname> + <refpurpose>define a user-defined cast</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +CREATE CAST (<replaceable>sourcetype</replaceable> AS <replaceable>targettype</replaceable>) + WITH FUNCTION <replaceable>funcname</replaceable> (<replaceable>argtype</replaceable>) + [AS ASSIGNMENT] + +CREATE CAST (<replaceable>sourcetype</replaceable> AS <replaceable>targettype</replaceable>) + WITHOUT FUNCTION + [AS ASSIGNMENT] +</synopsis> + </refsynopsisdiv> + + <refsect1 id="sql-createcast-description"> + <title>Description</title> + + <para> + <command>CREATE CAST</command> defines a new cast. A cast + specifies which function can be invoked when a conversion between + two data types is requested. For example, +<programlisting> +SELECT CAST(42 AS text); +</programlisting> + converts the integer constant 42 to type <type>text</type> by + invoking a previously specified function, in this case + <literal>text(int4)</>. (If no suitable cast has been defined, the + conversion fails.) + </para> + + <para> + Two types may be <firstterm>binary compatible</firstterm>, which + means that they can be converted into one another <quote>for + free</quote> without invoking any function. This requires that + corresponding values use the same internal representation. For + instance, the types <type>text</type> and <type>varchar</type> are + binary compatible. + </para> + + <para> + A cast can marked <literal>AS ASSIGNMENT</>, which means that it + can be invoked implicitly in any context where the conversion it + defines is required. Cast functions not so marked can be invoked + only by explicit <literal>CAST</>, + <replaceable>x</><literal>::</><replaceable>typename</>, or + <replaceable>typename</>(<replaceable>x</>) constructs. For + example, supposing that <literal>foo.f1</literal> is a column of + type <type>text</type>, then +<programlisting> +INSERT INTO foo(f1) VALUES(42); +</programlisting> + will be allowed if the cast from type <type>integer</type> to type + <type>text</type> is marked <literal>AS ASSIGNMENT</>, otherwise + not. (We generally use the term <firstterm>implicit + cast</firstterm> to describe this kind of cast.) + </para> + + <para> + It is wise to be conservative about marking casts as implicit. An + overabundance of implicit casting paths can cause + <productname>PostgreSQL</productname> to choose surprising + interpretations of commands, or to be unable to resolve commands at + all because there are multiple possible interpretations. A good + rule of thumb is to make cast implicitly invokable only for + information-preserving transformations between types in the same + general type category. For example, <type>int2</type> to + <type>int4</type> casts can reasonably be implicit, but be wary of + marking <type>int4</type> to <type>text</type> or + <type>float8</type> to <type>int4</type> as implicit casts. + </para> + + <para> + To be able to create a cast, you must own the underlying function. + To be able to create a binary compatible cast, you must own both + the source and the target data type. + </para> + + <variablelist> + <title>Parameters</title> + + <varlistentry> + <term><replaceable>sourcetype</replaceable></term> + + <listitem> + <para> + The name of the source data type of the cast. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable>targettype</replaceable></term> + + <listitem> + <para> + The name of the target data type of the cast. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable>funcname</replaceable>(<replaceable>argtype</replaceable>)</term> + + <listitem> + <para> + The function used to perform the cast. The function name may + be schema-qualified. If it is not, the function will be looked + up in the path. The argument type must be identical to the + source type, the result data type must match the target type of + the cast. Cast functions must be marked immutable. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>WITHOUT FUNCTION</literal></term> + + <listitem> + <para> + Indicates that the source type and the target type are binary + compatible, so no function is required to perform the cast. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>AS ASSIGNMENT</literal></term> + + <listitem> + <para> + Indicates that the cast may be invoked implicitly. + </para> + </listitem> + </varlistentry> + </variablelist> + + </refsect1> + + <refsect1 id="sql-createcast-notes"> + <title>Notes</title> + + <para> + Use <command>DROP CAST</command> to remove user-defined casts. + </para> + + <para> + The privileges required to create a cast may be changed in a future + release. + </para> + + <para> + Remember that if you want to be able to convert types both ways you + need to declare casts both ways explicitly. + </para> + + <para> + Prior to PostgreSQL 7.3, every function that had the same name as a + data type, returned that data type, and took one argument of a + different type was automatically a cast function. This system has + been abandoned in face of the introduction of schemas and to be + able to store binary compatible casts. The built-in cast functions + still follow this naming scheme, but they have to be declared as + casts explicitly now. + </para> + </refsect1> + + + <refsect1 id="sql-createcast-examples"> + <title>Examples</title> + + <para> + To create a cast from type <type>text</type> to type + <type>int</type> using the function <literal>int4(text)</literal>: +<programlisting> +CREATE CAST (text AS int4) WITH FUNCTION int4(text); +</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 SQL99, + except that SQL99 does not make provisions for binary compatible + types. + </para> + </refsect1> + + + <refsect1 id="sql-createcast-seealso"> + <title>See Also</title> + + <para> + <xref linkend="sql-createfunction" endterm="sql-createfunction-title">, + <xref linkend="sql-createtype" endterm="sql-createtype-title">, + <xref linkend="sql-dropcast" endterm="sql-dropcast-title">, + <citetitle>PostgreSQL Programmer's Guide</citetitle> + </para> + </refsect1> + +</refentry> + +<!-- 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: +--> |