Skip to content

Commit 9737704

Browse files
peterepetere
committed
pg_cast table, and standards-compliant CREATE/DROP CAST commands, plus
extension to create binary compatible casts. Includes dependency tracking as well. pg_proc.proimplicit is now defunct, but will be removed in a separate commit. pg_dump provides a migration path from the previous scheme to declare casts. Dumping binary compatible casts is currently impossible, though.
1 parent a345ac8 commit 9737704

36 files changed

+1299
-343
lines changed

‎doc/src/sgml/ref/allfiles.sgml

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$Header: /cvsroot/pgsql/doc/src/sgml/ref/allfiles.sgml,v 1.40 2002/07/18 16:47:22 tgl Exp $
2+
$Header: /cvsroot/pgsql/doc/src/sgml/ref/allfiles.sgml,v 1.41 2002/07/18 23:11:27 petere Exp $
33
PostgreSQL documentation
44
Complete list of usable sgml source files in this directory.
55
-->
@@ -51,6 +51,7 @@ Complete list of usable sgml source files in this directory.
5151
<!entity commit system "commit.sgml">
5252
<!entity copyTable system "copy.sgml">
5353
<!entity createAggregate system "create_aggregate.sgml">
54+
<!entity createCast system "create_cast.sgml">
5455
<!entity createConstraint system "create_constraint.sgml">
5556
<!entity createDatabase system "create_database.sgml">
5657
<!entity createDomain system "create_domain.sgml">
@@ -71,6 +72,7 @@ Complete list of usable sgml source files in this directory.
7172
<!entity declare system "declare.sgml">
7273
<!entity delete system "delete.sgml">
7374
<!entity dropAggregate system "drop_aggregate.sgml">
75+
<!entity dropCast system "drop_cast.sgml">
7476
<!entity dropDatabase system "drop_database.sgml">
7577
<!entity dropDomain system "drop_domain.sgml">
7678
<!entity dropFunction system "drop_function.sgml">

‎doc/src/sgml/ref/create_cast.sgml

Lines changed: 232 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,232 @@
1+
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/create_cast.sgml,v 1.1 2002/07/18 23:11:27 petere Exp $ -->
2+
3+
<refentry id="SQL-CREATECAST">
4+
<refmeta>
5+
<refentrytitle id="SQL-CREATECAST-TITLE">CREATE CAST</refentrytitle>
6+
<refmiscinfo>SQL - Language Statements</refmiscinfo>
7+
</refmeta>
8+
9+
<refnamediv>
10+
<refname>CREATE CAST</refname>
11+
<refpurpose>define a user-defined cast</refpurpose>
12+
</refnamediv>
13+
14+
<refsynopsisdiv>
15+
<synopsis>
16+
CREATE CAST (<replaceable>sourcetype</replaceable> AS <replaceable>targettype</replaceable>)
17+
WITH FUNCTION <replaceable>funcname</replaceable> (<replaceable>argtype</replaceable>)
18+
[AS ASSIGNMENT]
19+
20+
CREATE CAST (<replaceable>sourcetype</replaceable> AS <replaceable>targettype</replaceable>)
21+
WITHOUT FUNCTION
22+
[AS ASSIGNMENT]
23+
</synopsis>
24+
</refsynopsisdiv>
25+
26+
<refsect1 id="sql-createcast-description">
27+
<title>Description</title>
28+
29+
<para>
30+
<command>CREATE CAST</command> defines a new cast. A cast
31+
specifies which function can be invoked when a conversion between
32+
two data types is requested. For example,
33+
<programlisting>
34+
SELECT CAST(42 AS text);
35+
</programlisting>
36+
converts the integer constant 42 to type <type>text</type> by
37+
invoking a previously specified function, in this case
38+
<literal>text(int4)</>. (If no suitable cast has been defined, the
39+
conversion fails.)
40+
</para>
41+
42+
<para>
43+
Two types may be <firstterm>binary compatible</firstterm>, which
44+
means that they can be converted into one another <quote>for
45+
free</quote> without invoking any function. This requires that
46+
corresponding values use the same internal representation. For
47+
instance, the types <type>text</type> and <type>varchar</type> are
48+
binary compatible.
49+
</para>
50+
51+
<para>
52+
A cast can marked <literal>AS ASSIGNMENT</>, which means that it
53+
can be invoked implicitly in any context where the conversion it
54+
defines is required. Cast functions not so marked can be invoked
55+
only by explicit <literal>CAST</>,
56+
<replaceable>x</><literal>::</><replaceable>typename</>, or
57+
<replaceable>typename</>(<replaceable>x</>) constructs. For
58+
example, supposing that <literal>foo.f1</literal> is a column of
59+
type <type>text</type>, then
60+
<programlisting>
61+
INSERT INTO foo(f1) VALUES(42);
62+
</programlisting>
63+
will be allowed if the cast from type <type>integer</type> to type
64+
<type>text</type> is marked <literal>AS ASSIGNMENT</>, otherwise
65+
not. (We generally use the term <firstterm>implicit
66+
cast</firstterm> to describe this kind of cast.)
67+
</para>
68+
69+
<para>
70+
It is wise to be conservative about marking casts as implicit. An
71+
overabundance of implicit casting paths can cause
72+
<productname>PostgreSQL</productname> to choose surprising
73+
interpretations of commands, or to be unable to resolve commands at
74+
all because there are multiple possible interpretations. A good
75+
rule of thumb is to make cast implicitly invokable only for
76+
information-preserving transformations between types in the same
77+
general type category. For example, <type>int2</type> to
78+
<type>int4</type> casts can reasonably be implicit, but be wary of
79+
marking <type>int4</type> to <type>text</type> or
80+
<type>float8</type> to <type>int4</type> as implicit casts.
81+
</para>
82+
83+
<para>
84+
To be able to create a cast, you must own the underlying function.
85+
To be able to create a binary compatible cast, you must own both
86+
the source and the target data type.
87+
</para>
88+
89+
<variablelist>
90+
<title>Parameters</title>
91+
92+
<varlistentry>
93+
<term><replaceable>sourcetype</replaceable></term>
94+
95+
<listitem>
96+
<para>
97+
The name of the source data type of the cast.
98+
</para>
99+
</listitem>
100+
</varlistentry>
101+
102+
<varlistentry>
103+
<term><replaceable>targettype</replaceable></term>
104+
105+
<listitem>
106+
<para>
107+
The name of the target data type of the cast.
108+
</para>
109+
</listitem>
110+
</varlistentry>
111+
112+
<varlistentry>
113+
<term><replaceable>funcname</replaceable>(<replaceable>argtype</replaceable>)</term>
114+
115+
<listitem>
116+
<para>
117+
The function used to perform the cast. The function name may
118+
be schema-qualified. If it is not, the function will be looked
119+
up in the path. The argument type must be identical to the
120+
source type, the result data type must match the target type of
121+
the cast. Cast functions must be marked immutable.
122+
</para>
123+
</listitem>
124+
</varlistentry>
125+
126+
<varlistentry>
127+
<term><literal>WITHOUT FUNCTION</literal></term>
128+
129+
<listitem>
130+
<para>
131+
Indicates that the source type and the target type are binary
132+
compatible, so no function is required to perform the cast.
133+
</para>
134+
</listitem>
135+
</varlistentry>
136+
137+
<varlistentry>
138+
<term><literal>AS ASSIGNMENT</literal></term>
139+
140+
<listitem>
141+
<para>
142+
Indicates that the cast may be invoked implicitly.
143+
</para>
144+
</listitem>
145+
</varlistentry>
146+
</variablelist>
147+
148+
</refsect1>
149+
150+
<refsect1 id="sql-createcast-notes">
151+
<title>Notes</title>
152+
153+
<para>
154+
Use <command>DROP CAST</command> to remove user-defined casts.
155+
</para>
156+
157+
<para>
158+
The privileges required to create a cast may be changed in a future
159+
release.
160+
</para>
161+
162+
<para>
163+
Remember that if you want to be able to convert types both ways you
164+
need to declare casts both ways explicitly.
165+
</para>
166+
167+
<para>
168+
Prior to PostgreSQL 7.3, every function that had the same name as a
169+
data type, returned that data type, and took one argument of a
170+
different type was automatically a cast function. This system has
171+
been abandoned in face of the introduction of schemas and to be
172+
able to store binary compatible casts. The built-in cast functions
173+
still follow this naming scheme, but they have to be declared as
174+
casts explicitly now.
175+
</para>
176+
</refsect1>
177+
178+
179+
<refsect1 id="sql-createcast-examples">
180+
<title>Examples</title>
181+
182+
<para>
183+
To create a cast from type <type>text</type> to type
184+
<type>int</type> using the function <literal>int4(text)</literal>:
185+
<programlisting>
186+
CREATE CAST (text AS int4) WITH FUNCTION int4(text);
187+
</programlisting>
188+
(This cast is already predefined in the system.)
189+
</para>
190+
</refsect1>
191+
192+
193+
<refsect1 id="sql-createcast-compat">
194+
<title>Compatibility</title>
195+
196+
<para>
197+
The <command>CREATE CAST</command> command conforms to SQL99,
198+
except that SQL99 does not make provisions for binary compatible
199+
types.
200+
</para>
201+
</refsect1>
202+
203+
204+
<refsect1 id="sql-createcast-seealso">
205+
<title>See Also</title>
206+
207+
<para>
208+
<xref linkend="sql-createfunction" endterm="sql-createfunction-title">,
209+
<xref linkend="sql-createtype" endterm="sql-createtype-title">,
210+
<xref linkend="sql-dropcast" endterm="sql-dropcast-title">,
211+
<citetitle>PostgreSQL Programmer's Guide</citetitle>
212+
</para>
213+
</refsect1>
214+
215+
</refentry>
216+
217+
<!-- Keep this comment at the end of the file
218+
Local variables:
219+
mode:sgml
220+
sgml-omittag:nil
221+
sgml-shorttag:t
222+
sgml-minimize-attributes:nil
223+
sgml-always-quote-attributes:t
224+
sgml-indent-step:1
225+
sgml-indent-data:t
226+
sgml-parent-document:nil
227+
sgml-default-dtd-file:"../reference.ced"
228+
sgml-exposed-tags:nil
229+
sgml-local-catalogs:("/usr/lib/sgml/catalog")
230+
sgml-local-ecat-files:nil
231+
End:
232+
-->

‎doc/src/sgml/ref/create_function.sgml

Lines changed: 1 addition & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.39 2002/05/18 13:47:59 petere Exp $
2+
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.40 2002/07/18 23:11:27 petere Exp $
33
-->
44

55
<refentry id="SQL-CREATEFUNCTION">
@@ -20,7 +20,6 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable>
2020
{ LANGUAGE <replaceable class="parameter">langname</replaceable>
2121
| IMMUTABLE | STABLE | VOLATILE
2222
| CALLED ON NULL INPUT | RETURNS NULL ON NULL INPUT | STRICT
23-
| IMPLICIT CAST
2423
| [EXTERNAL] SECURITY INVOKER | [EXTERNAL] SECURITY DEFINER
2524
| AS '<replaceable class="parameter">definition</replaceable>'
2625
| 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>
188187
</listitem>
189188
</varlistentry>
190189

191-
<varlistentry>
192-
<term><literal>IMPLICIT CAST</literal</term>
193-
194-
<listitem>
195-
<para>
196-
Indicates that the function may be used for implicit type
197-
conversions. See <xref linkend="sql-createfunction-cast-functions"
198-
endterm="sql-createfunction-cast-functions-title"> for more detail.
199-
</para>
200-
</listitem>
201-
</varlistentry>
202-
203190
<varlistentry>
204191
<term><optional>EXTERNAL</optional> SECURITY INVOKER</term>
205192
<term><optional>EXTERNAL</optional> SECURITY DEFINER</term>
@@ -285,14 +272,6 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable>
285272
</listitem>
286273
</varlistentry>
287274

288-
<varlistentry>
289-
<term>implicitCoercion</term>
290-
<listitem>
291-
<para>
292-
Same as <literal>IMPLICIT CAST</literal>
293-
</para>
294-
</listitem>
295-
</varlistentry>
296275
</variablelist>
297276

298277
Attribute names are not case-sensitive.
@@ -394,55 +373,6 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable>
394373
</para>
395374
</refsect1>
396375

397-
<refsect1 id="sql-createfunction-cast-functions">
398-
<title id="sql-createfunction-cast-functions-title">
399-
Type Cast Functions
400-
</title>
401-
<para>
402-
A function that has one argument and is named the same as its return
403-
data type (including the schema name) is considered to be a <firstterm>type
404-
casting function</>: it can be invoked to convert a value of its input
405-
data type into a value
406-
of its output datatype. For example,
407-
<programlisting>
408-
SELECT CAST(42 AS text);
409-
</programlisting>
410-
converts the integer constant 42 to text by invoking a function
411-
<literal>text(int4)</>, if such a function exists and returns type
412-
text. (If no suitable conversion function can be found, the cast fails.)
413-
</para>
414-
415-
<para>
416-
If a potential cast function is marked <literal>IMPLICIT CAST</>,
417-
then it can be invoked implicitly in any context where the
418-
conversion it defines is required. Cast functions not so marked
419-
can be invoked only by explicit <literal>CAST</>,
420-
<replaceable>x</><literal>::</><replaceable>typename</>, or
421-
<replaceable>typename</>(<replaceable>x</>) constructs. For
422-
example, supposing that <literal>foo.f1</literal> is a column of
423-
type <type>text</type>, then
424-
<programlisting>
425-
INSERT INTO foo(f1) VALUES(42);
426-
</programlisting>
427-
will be allowed if <literal>text(int4)</> is marked
428-
<literal>IMPLICIT CAST</>, otherwise not.
429-
</para>
430-
431-
<para>
432-
It is wise to be conservative about marking cast functions as
433-
implicit casts. An overabundance of implicit casting paths can
434-
cause <productname>PostgreSQL</productname> to choose surprising
435-
interpretations of commands, or to be unable to resolve commands at
436-
all because there are multiple possible interpretations. A good
437-
rule of thumb is to make cast implicitly invokable only for
438-
information-preserving transformations between types in the same
439-
general type category. For example, <type>int2</type> to
440-
<type>int4</type> casts can reasonably be implicit, but be wary of
441-
marking <type>int4</type> to <type>text</type> or
442-
<type>float8</type> to <type>int4</type> as implicit casts.
443-
</para>
444-
</refsect1>
445-
446376
<refsect1 id="sql-createfunction-examples">
447377
<title>Examples</title>
448378

0 commit comments

Comments
 (0)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy