diff options
Diffstat (limited to 'doc/src')
| -rw-r--r-- | doc/src/sgml/ref/allfiles.sgml | 4 | ||||
| -rw-r--r-- | doc/src/sgml/ref/create_cast.sgml | 232 | ||||
| -rw-r--r-- | doc/src/sgml/ref/create_function.sgml | 72 | ||||
| -rw-r--r-- | doc/src/sgml/ref/drop_cast.sgml | 133 | ||||
| -rw-r--r-- | doc/src/sgml/reference.sgml | 4 | ||||
| -rw-r--r-- | doc/src/sgml/release.sgml | 3 |
6 files changed, 374 insertions, 74 deletions
diff --git a/doc/src/sgml/ref/allfiles.sgml b/doc/src/sgml/ref/allfiles.sgml index c9ece5af561..55b4fc5c9f0 100644 --- a/doc/src/sgml/ref/allfiles.sgml +++ b/doc/src/sgml/ref/allfiles.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/allfiles.sgml,v 1.40 2002/07/18 16:47:22 tgl Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/allfiles.sgml,v 1.41 2002/07/18 23:11:27 petere Exp $ PostgreSQL documentation Complete list of usable sgml source files in this directory. --> @@ -51,6 +51,7 @@ Complete list of usable sgml source files in this directory. <!entity commit system "commit.sgml"> <!entity copyTable system "copy.sgml"> <!entity createAggregate system "create_aggregate.sgml"> +<!entity createCast system "create_cast.sgml"> <!entity createConstraint system "create_constraint.sgml"> <!entity createDatabase system "create_database.sgml"> <!entity createDomain system "create_domain.sgml"> @@ -71,6 +72,7 @@ Complete list of usable sgml source files in this directory. <!entity declare system "declare.sgml"> <!entity delete system "delete.sgml"> <!entity dropAggregate system "drop_aggregate.sgml"> +<!entity dropCast system "drop_cast.sgml"> <!entity dropDatabase system "drop_database.sgml"> <!entity dropDomain system "drop_domain.sgml"> <!entity dropFunction system "drop_function.sgml"> diff --git a/doc/src/sgml/ref/create_cast.sgml b/doc/src/sgml/ref/create_cast.sgml new file mode 100644 index 00000000000..81259949f1e --- /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: +--> diff --git a/doc/src/sgml/ref/create_function.sgml b/doc/src/sgml/ref/create_function.sgml index b2d2314a733..e2170dcc45d 100644 --- a/doc/src/sgml/ref/create_function.sgml +++ b/doc/src/sgml/ref/create_function.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.39 2002/05/18 13:47:59 petere Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.40 2002/07/18 23:11:27 petere Exp $ --> <refentry id="SQL-CREATEFUNCTION"> @@ -20,7 +20,6 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable> { LANGUAGE <replaceable class="parameter">langname</replaceable> | IMMUTABLE | STABLE | VOLATILE | CALLED ON NULL INPUT | RETURNS NULL ON NULL INPUT | STRICT - | IMPLICIT CAST | [EXTERNAL] SECURITY INVOKER | [EXTERNAL] SECURITY DEFINER | AS '<replaceable class="parameter">definition</replaceable>' | AS '<replaceable class="parameter">obj_file</replaceable>', '<replaceable class="parameter">link_symbol</replaceable>' @@ -188,18 +187,6 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable> </listitem> </varlistentry> - <varlistentry> - <term><literal>IMPLICIT CAST</literal</term> - - <listitem> - <para> - Indicates that the function may be used for implicit type - conversions. See <xref linkend="sql-createfunction-cast-functions" - endterm="sql-createfunction-cast-functions-title"> for more detail. - </para> - </listitem> - </varlistentry> - <varlistentry> <term><optional>EXTERNAL</optional> SECURITY INVOKER</term> <term><optional>EXTERNAL</optional> SECURITY DEFINER</term> @@ -285,14 +272,6 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable> </listitem> </varlistentry> - <varlistentry> - <term>implicitCoercion</term> - <listitem> - <para> - Same as <literal>IMPLICIT CAST</literal> - </para> - </listitem> - </varlistentry> </variablelist> Attribute names are not case-sensitive. @@ -394,55 +373,6 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable> </para> </refsect1> - <refsect1 id="sql-createfunction-cast-functions"> - <title id="sql-createfunction-cast-functions-title"> - Type Cast Functions - </title> - <para> - A function that has one argument and is named the same as its return - data type (including the schema name) is considered to be a <firstterm>type - casting function</>: it can be invoked to convert a value of its input - data type into a value - of its output datatype. For example, -<programlisting> -SELECT CAST(42 AS text); -</programlisting> - converts the integer constant 42 to text by invoking a function - <literal>text(int4)</>, if such a function exists and returns type - text. (If no suitable conversion function can be found, the cast fails.) - </para> - - <para> - If a potential cast function is marked <literal>IMPLICIT CAST</>, - then 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 <literal>text(int4)</> is marked - <literal>IMPLICIT CAST</>, otherwise not. - </para> - - <para> - It is wise to be conservative about marking cast functions as - implicit casts. 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> - </refsect1> - <refsect1 id="sql-createfunction-examples"> <title>Examples</title> diff --git a/doc/src/sgml/ref/drop_cast.sgml b/doc/src/sgml/ref/drop_cast.sgml new file mode 100644 index 00000000000..37152114bca --- /dev/null +++ b/doc/src/sgml/ref/drop_cast.sgml @@ -0,0 +1,133 @@ +<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_cast.sgml,v 1.1 2002/07/18 23:11:27 petere Exp $ --> + +<refentry id="SQL-DROPCAST"> + <refmeta> + <refentrytitle id="SQL-DROPCAST-TITLE">DROP CAST</refentrytitle> + <refmiscinfo>SQL - Language Statements</refmiscinfo> + </refmeta> + + <refnamediv> + <refname>DROP CAST</refname> + <refpurpose>remove a user-defined cast</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +DROP CAST (<replaceable>sourcetype</replaceable> AS <replaceable>targettype</replaceable>) + [ CASCADE | RESTRICT ] +</synopsis> + </refsynopsisdiv> + + <refsect1 id="sql-dropcast-description"> + <title>Description</title> + + <para> + <command>DROP CAST</command> removes a previously defined cast. + </para> + + <para> + To be able to drop a cast, you must own the underlying function. + To be able to drop a binary compatible cast, you must own both the + source and the target data type. These are the same privileges + that are required to create a cast. + </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><literal>CASCADE</literal></term> + <term><literal>RESTRICT</literal></term> + + <listitem> + <para> + These key words do not have any effect, since there are no + dependencies on casts. + </para> + </listitem> + </varlistentry> + </variablelist> + + </refsect1> + + <refsect1 id="sql-dropcast-notes"> + <title>Notes</title> + + <para> + Use <command>CREATE CAST</command> to create user-defined casts. + </para> + + <para> + The privileges required to drop a cast may be changed in a future + release. + </para> + </refsect1> + + + <refsect1 id="sql-dropcast-examples"> + <title>Examples</title> + + <para> + To drop the cast from type <type>text</type> to type <type>int</type>: +<programlisting> +DROP CAST (text AS int4); +</programlisting> + </para> + </refsect1> + + + <refsect1 id="sql-dropcast-compat"> + <title>Compatibility</title> + + <para> + The <command>DROP CAST</command> command conforms to SQL99. + </para> + </refsect1> + + + <refsect1 id="sql-dropcast-seealso"> + <title>See Also</title> + + <para> + <xref linkend="sql-createcast" endterm="sql-createcast-title"> + </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: +--> diff --git a/doc/src/sgml/reference.sgml b/doc/src/sgml/reference.sgml index 8249039826c..39fec262dd0 100644 --- a/doc/src/sgml/reference.sgml +++ b/doc/src/sgml/reference.sgml @@ -1,5 +1,5 @@ <!-- reference.sgml -$Header: /cvsroot/pgsql/doc/src/sgml/reference.sgml,v 1.29 2002/07/18 16:47:22 tgl Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/reference.sgml,v 1.30 2002/07/18 23:11:27 petere Exp $ PostgreSQL Reference Manual --> @@ -60,6 +60,7 @@ PostgreSQL Reference Manual &commit; ©Table; &createAggregate; + &createCast; &createConstraint; &createDatabase; &createDomain; @@ -80,6 +81,7 @@ PostgreSQL Reference Manual &declare; &delete; &dropAggregate; + &dropCast; &dropDatabase; &dropDomain; &dropFunction; diff --git a/doc/src/sgml/release.sgml b/doc/src/sgml/release.sgml index f215c84b93e..4f7911ff4e1 100644 --- a/doc/src/sgml/release.sgml +++ b/doc/src/sgml/release.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/release.sgml,v 1.141 2002/07/16 22:12:18 tgl Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/release.sgml,v 1.142 2002/07/18 23:11:27 petere Exp $ --> <appendix id="release"> @@ -24,6 +24,7 @@ CDATA means the content is "SGML-free", so you can write without worries about funny characters. --> <literallayout><![CDATA[ +CREATE CAST/DROP CAST Sequences created by SERIAL column definitions now auto-drop with the column Most forms of DROP now support RESTRICT and CASCADE options Recursive SQL functions can be defined |