266 lines
8.2 KiB
Plaintext
266 lines
8.2 KiB
Plaintext
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/create_cast.sgml,v 1.9 2003/02/01 22:09:25 tgl 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 | AS IMPLICIT ]
|
|
|
|
CREATE CAST (<replaceable>sourcetype</replaceable> AS <replaceable>targettype</replaceable>)
|
|
WITHOUT FUNCTION
|
|
[ AS ASSIGNMENT | AS IMPLICIT ]
|
|
</synopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1 id="sql-createcast-description">
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
<command>CREATE CAST</command> defines a new cast. A cast
|
|
specifies how to perform a conversion between
|
|
two data types. 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>
|
|
By default, a cast can be invoked only by an explicit cast request,
|
|
that is an explicit <literal>CAST(<replaceable>x</> AS
|
|
<replaceable>typename</>)</literal>,
|
|
<replaceable>x</><literal>::</><replaceable>typename</>, or
|
|
<replaceable>typename</>(<replaceable>x</>) construct.
|
|
</para>
|
|
|
|
<para>
|
|
If the cast is marked <literal>AS ASSIGNMENT</> then it can be invoked
|
|
implicitly when assigning to a column of the target data type.
|
|
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>assignment
|
|
cast</firstterm> to describe this kind of cast.)
|
|
</para>
|
|
|
|
<para>
|
|
If the cast is marked <literal>AS IMPLICIT</> then it can be invoked
|
|
implicitly in any context, whether assignment or internally in an
|
|
expression. For example, since <literal>||</> takes <type>text</>
|
|
arguments,
|
|
<programlisting>
|
|
SELECT 'The time is ' || now();
|
|
</programlisting>
|
|
will be allowed only if the cast from type <type>timestamp</> to
|
|
<type>text</type> is marked <literal>AS IMPLICIT</>. Otherwise it
|
|
will be necessary to write the cast explicitly, for example
|
|
<programlisting>
|
|
SELECT 'The time is ' || CAST(now() AS text);
|
|
</programlisting>
|
|
(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 a cast implicitly invokable only for
|
|
information-preserving transformations between types in the same
|
|
general type category. For example, the cast from <type>int2</type> to
|
|
<type>int4</type> can reasonably be implicit, but the cast from
|
|
<type>float8</type> to <type>int4</type> should probably be
|
|
assignment-only. Cross-type-category casts, such as <type>text</>
|
|
to <type>int4</>, are best made explicit-only.
|
|
</para>
|
|
|
|
<para>
|
|
To be able to create a cast, you must own the source or the target
|
|
data type. To create a binary-compatible cast, you must be superuser
|
|
(this restriction is made because an erroneous binary-compatible cast
|
|
conversion can easily crash the server).
|
|
</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.
|
|
</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 in assignment
|
|
contexts.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>AS IMPLICIT</literal></term>
|
|
|
|
<listitem>
|
|
<para>
|
|
Indicates that the cast may be invoked implicitly in any context.
|
|
</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>
|
|
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 <productname>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 convention has been abandoned in face of the introduction of
|
|
schemas and to be able to represent binary compatible casts in the
|
|
catalogs. (The built-in cast functions still follow this naming
|
|
scheme, but they have to be shown as casts in <literal>pg_cast</>
|
|
now.)
|
|
</para>
|
|
</refsect1>
|
|
|
|
|
|
<refsect1 id="sql-createcast-examples">
|
|
<title>Examples</title>
|
|
|
|
<para>
|
|
To create a cast from type <type>text</type> to type
|
|
<type>int4</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. <literal>AS IMPLICIT</> is a <productname>PostgreSQL</productname>
|
|
extension, too.
|
|
</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">,
|
|
&cite-programmer;
|
|
</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:
|
|
-->
|