<!-- $PostgreSQL: pgsql/doc/src/sgml/catalogs.sgml,v 2.166 2008/05/09 23:32:03 tgl Exp $ -->

<!-- $PostgreSQL: pgsql/doc/src/sgml/catalogs.sgml,v 2.167 2008/07/11 07:02:43 petere Exp $ -->

<!--

Documentation of the system catalogs, directed toward PostgreSQL developers

-->

<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 binarycompatible (that is, no

stored if the data types are binarycoercible (that is, no

run-time operation is needed to perform the cast)

</entry>

</row>

<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/create_cast.sgml,v 1.26 2007/06/05 21:31:04 tgl Exp $ -->

<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/create_cast.sgml,v 1.27 2008/07/11 07:02:43 petere Exp $ -->

<refentry id="SQL-CREATECAST">

<refmeta>

</para>

<para>

Two types can 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.

Two types can be <firstterm>binary coercible</firstterm>, which

means that the conversion can be performed <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

coercible both ways. Binary coercibility is not necessarily a

symmetric relationship. For example, the cast

from <type>xml</type> to <type>text</type> can be performed for

free in the present implementation, but the reverse direction

requires a function that performs at least a syntax check. (Two

types that are binary coercible both ways are also referred to as

binary compatible.)

</para>

<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

data type. To create a binary-coercible cast, you must be superuser.

(This restriction is made because an erroneous binary-coercible cast

conversion can easily crash the server.)

</para>

</refsect1>

<listitem>

<para>

Indicates that the source type and the target type are binary

compatible, so no function is required to perform the cast.

coercible, so no function is required to perform the cast.

</para>

</listitem>

</varlistentry>

<para>

Cast implementation functions can have one to three arguments.

The first argument type must be identical tothe cast's source type.

The second argument,

The first argument type must be identical toor binary-coercible from

the cast's source type.The second argument,

if present, must be type <type>integer</>; it receives the type

modifier associated with the destination type, or <literal>-1</>

if there is none. The third argument,

your own data types so that this matters.)

</para>

<para>

The return type of a cast function must be identical to or

binary-coercible to the cast's target type.

</para>

<para>

Ordinarily a cast must have different source and target data types.

However, it is allowed to declare a cast with identical source and

request without having matched it to an actual function.

If a function call <replaceable>name</>(<replaceable>x</>) does not

exactly match any existing function, but <replaceable>name</> is the name

of a data type and <structname>pg_cast</> provides a binary-compatible cast

of a data type and <structname>pg_cast</> provides a binary-coercible cast

to this type from the type of <replaceable>x</>, then the call will be

construed as a binary-compatible cast. This exception is made so that

binary-compatible casts can be invoked using functional syntax, even

binary-coercible casts can be invoked using functional syntax, even

though they lack any function. Likewise, if there is no

<structname>pg_cast</> entry but the cast would be to or from a string

type, the call will be construed as an I/O conversion cast. This

<para>

The <command>CREATE CAST</command> command conforms to the

<acronym>SQL</acronym> standard,

except that SQL does not make provisions for binary-compatible

except that SQL does not make provisions for binary-coercible

types or extra arguments to implementation functions.

<literal>AS IMPLICIT</> is a <productname>PostgreSQL</productname>

extension, too.

<!-- $PostgreSQL: pgsql/doc/src/sgml/typeconv.sgml,v 1.53 2007/11/26 16:46:50 tgl Exp $ -->

<!-- $PostgreSQL: pgsql/doc/src/sgml/typeconv.sgml,v 1.54 2008/07/11 07:02:43 petere Exp $ -->

<chapter Id="typeconv">

<title>Type Conversion</title>

to be a special type conversion request. This happens if the function call

has just one argument and the function name is the same as the (internal)

name of some data type. Furthermore, the function argument must be either

an unknown-type literal, or a type that is binary-compatible with the named

an unknown-type literal, or a type that is binary-coercible to the named

data type, or a type that could be converted to the named data type by

applying that type's I/O functions (that is, the conversion is either to or

from one of the standard string types). When these conditions are met,

to be resolved as <type>text</type> concatenation. Then the <type>text</type>

result of the operator is converted to <type>bpchar</type> (<quote>blank-padded

char</>, the internal name of the <type>character</type> data type) to match the target

column type. (Since thetypes<type>text</type>and

<type>bpchar</type>are binary-compatible, this conversion does

column type. (Since theconversion from<type>text</type>to

<type>bpchar</type>is binary-coercible, this conversion does

not insert any real function call.) Finally, the sizing function

<literal>bpchar(bpchar, integer)</literal> is found in the system catalog

and applied to the operator's result and the stored column length. This

ereport(ERROR,

(errcode(ERRCODE_INVALID_OBJECT_DEFINITION),

errmsg("cast function must take one to three arguments")));

if (procstruct->proargtypes.values[0]!=sourcetypeid)

if (!IsBinaryCoercible(sourcetypeid,procstruct->proargtypes.values[0]))

ereport(ERROR,

(errcode(ERRCODE_INVALID_OBJECT_DEFINITION),

errmsg("argument of cast function must match source data type")));

errmsg("argument of cast function must matchor be binary-compatible withsource data type")));

if (nargs>1&&procstruct->proargtypes.values[1]!=INT4OID)

ereport(ERROR,

(errcode(ERRCODE_INVALID_OBJECT_DEFINITION),

ereport(ERROR,

(errcode(ERRCODE_INVALID_OBJECT_DEFINITION),

errmsg("third argument of cast function must be type boolean")));

if (procstruct->prorettype!=targettypeid)

if (!IsBinaryCoercible(procstruct->prorettype,targettypeid))

ereport(ERROR,

(errcode(ERRCODE_INVALID_OBJECT_DEFINITION),

errmsg("return data type of cast function must match target data type")));

errmsg("return data type of cast function must matchor be binary-compatible withtarget data type")));