Skip to content

Commit 5bfb054

Browse files
tglsfdctglsfdc
committed
Update docs for 7.4 array features and polymorphic functions.
This is Joe Conway's patch of 7-Aug plus further editorializing of my own.
1 parent 329a1b7 commit 5bfb054

File tree

8 files changed

+722
-288
lines changed

8 files changed

+722
-288
lines changed

‎doc/src/sgml/array.sgml

Lines changed: 123 additions & 215 deletions
Large diffs are not rendered by default.

‎doc/src/sgml/datatype.sgml

Lines changed: 17 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.121 2003/07/29 00:03:17 tgl Exp $
2+
$Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.122 2003/08/09 22:50:21 tgl Exp $
33
-->
44

55
<chapter id="datatype">
@@ -2993,6 +2993,10 @@ SELECT * FROM test;
29932993
<primary>anyarray</primary>
29942994
</indexterm>
29952995

2996+
<indexterm zone="datatype-pseudo">
2997+
<primary>anyelement</primary>
2998+
</indexterm>
2999+
29963000
<indexterm zone="datatype-pseudo">
29973001
<primary>void</primary>
29983002
</indexterm>
@@ -3053,7 +3057,14 @@ SELECT * FROM test;
30533057

30543058
<row>
30553059
<entry><type>anyarray</></entry>
3056-
<entry>Indicates that a function accepts any array data type.</entry>
3060+
<entry>Indicates that a function accepts any array data type
3061+
(see <xref linkend="types-polymorphic">).</entry>
3062+
</row>
3063+
3064+
<row>
3065+
<entry><type>anyelement</></entry>
3066+
<entry>Indicates that a function accepts any data type
3067+
(see <xref linkend="types-polymorphic">).</entry>
30573068
</row>
30583069

30593070
<row>
@@ -3101,8 +3112,10 @@ SELECT * FROM test;
31013112
Functions coded in procedural languages may use pseudo-types only as
31023113
allowed by their implementation languages. At present the procedural
31033114
languages all forbid use of a pseudo-type as argument type, and allow
3104-
only <type>void</> as a result type (plus <type>trigger</> when the
3105-
function is used as a trigger).
3115+
only <type>void</> and <type>record</> as a result type (plus
3116+
<type>trigger</> when the function is used as a trigger). Some also
3117+
support polymorphic functions using the types <type>anyarray</> and
3118+
<type>anyelement</>.
31063119
</para>
31073120

31083121
<para>

‎doc/src/sgml/extend.sgml

Lines changed: 107 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$Header: /cvsroot/pgsql/doc/src/sgml/extend.sgml,v 1.22 2003/04/13 09:57:35 petere Exp $
2+
$Header: /cvsroot/pgsql/doc/src/sgml/extend.sgml,v 1.23 2003/08/09 22:50:21 tgl Exp $
33
-->
44

55
<chapter id="extend">
@@ -20,6 +20,11 @@ $Header: /cvsroot/pgsql/doc/src/sgml/extend.sgml,v 1.22 2003/04/13 09:57:35 pete
2020
functions (starting in <xref linkend="xfunc">)
2121
</para>
2222
</listitem>
23+
<listitem>
24+
<para>
25+
aggregates (starting in <xref linkend="xaggr">)
26+
</para>
27+
</listitem>
2328
<listitem>
2429
<para>
2530
data types (starting in <xref linkend="xtypes">)
@@ -32,7 +37,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/extend.sgml,v 1.22 2003/04/13 09:57:35 pete
3237
</listitem>
3338
<listitem>
3439
<para>
35-
aggregates (starting in <xref linkend="xaggr">)
40+
operator classes for indexes (starting in <xref linkend="xindex">)
3641
</para>
3742
</listitem>
3843
</itemizedlist>
@@ -47,7 +52,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/extend.sgml,v 1.22 2003/04/13 09:57:35 pete
4752
relational database systems, you know that they store information
4853
about databases, tables, columns, etc., in what are
4954
commonly known as system catalogs. (Some systems call
50-
this the data dictionary). The catalogs appear to the
55+
this the data dictionary.) The catalogs appear to the
5156
user as tables like any other, but the <acronym>DBMS</acronym> stores
5257
its internal bookkeeping in them. One key difference
5358
between <productname>PostgreSQL</productname> and standard relational database systems is
@@ -88,24 +93,113 @@ $Header: /cvsroot/pgsql/doc/src/sgml/extend.sgml,v 1.22 2003/04/13 09:57:35 pete
8893
</indexterm>
8994

9095
<para>
91-
Data types are divided into base types and composite types.
96+
<productname>PostgreSQL</productname> data types are divided into base
97+
types, composite types, domain types, and pseudo-types.
98+
</para>
99+
100+
<para>
92101
Base types are those, like <type>int4</type>, that are implemented
93-
in a language such as C. They generally correspond to
94-
what are often known as abstract data types. <productname>PostgreSQL</productname>
95-
can only operate on such types through methods provided
102+
below the level of the <acronym>SQL</> language (typically in a low-level
103+
language such as C). They generally correspond to
104+
what are often known as abstract data types.
105+
<productname>PostgreSQL</productname>
106+
can only operate on such types through functions provided
96107
by the user and only understands the behavior of such
97-
types to the extent that the user describes them.
98-
Composite types are created whenever the user creates a
99-
table. The
100-
user can <quote>look inside</quote> at the attributes of these types
101-
from the query language.
108+
types to the extent that the user describes them. Base types are
109+
further subdivided into scalar and array types. For each scalar type,
110+
a corresponding array type is automatically created that can hold
111+
variable-size arrays of that scalar type.
112+
</para>
113+
114+
<para>
115+
Composite types, or row types, are created whenever the user creates a
116+
table; it's also possible to define a <quote>stand-alone</> composite
117+
type with no associated table. A composite type is simply a list of
118+
base types with associated field names. A value of a composite type
119+
is a row or record of field values. The user can access the component
120+
fields from <acronym>SQL</> queries.
121+
</para>
122+
123+
<para>
124+
A domain type is based on a particular base
125+
type and for many purposes is interchangeable with its base type.
126+
However, a domain may have constraints that restrict its valid values
127+
to a subset of what the underlying base type would allow. Domains can
128+
be created by simple <acronym>SQL</> commands.
102129
</para>
130+
131+
<para>
132+
Finally, there are a few <quote>pseudo-types</> for special purposes.
133+
Pseudo-types cannot appear as fields of tables or composite types, but
134+
they can be used to declare the argument and result types of functions.
135+
This provides a mechanism within the type system to identify special
136+
classes of functions. <xref
137+
linkend="datatype-pseudotypes-table"> lists the existing
138+
pseudo-types.
139+
</para>
140+
141+
<sect2 id="types-polymorphic">
142+
<title>Polymorphic Types and Functions</title>
143+
144+
<indexterm>
145+
<primary>polymorphic types</primary>
146+
</indexterm>
147+
148+
<indexterm>
149+
<primary>polymorphic functions</primary>
150+
</indexterm>
151+
152+
<para>
153+
Two pseudo-types of special interest are <type>anyelement</> and
154+
<type>anyarray</>, which are collectively called <firstterm>polymorphic
155+
types</>. Any function declared using these types is said to be
156+
a <firstterm>polymorphic function</>. A polymorphic function can
157+
operate on many different data types, with the specific data type(s)
158+
being determined by the data types actually passed to it in a particular
159+
call.
160+
</para>
161+
162+
<para>
163+
Polymorphic arguments and results are tied to each other and are resolved
164+
to a specific data type when a query calling a polymorphic function is
165+
parsed. Each position (either argument or return value) declared as
166+
<type>anyelement</type> is allowed to have any specific actual
167+
data type, but in any given call they must all be the
168+
<emphasis>same</emphasis> actual type. Each
169+
position declared as <type>anyarray</type> can have any array data type,
170+
but similarly they must all be the same type. If there are
171+
positions declared <type>anyarray</type> and others declared
172+
<type>anyelement</type>, the actual array type in the
173+
<type>anyarray</type> positions must be an array whose elements are
174+
the same type appearing in the <type>anyelement</type> positions.
175+
</para>
176+
177+
<para>
178+
Thus, when more than one argument position is declared with a polymorphic
179+
type, the net effect is that only certain combinations of actual argument
180+
types are allowed. For example, a function declared as
181+
<literal>foo(anyelement, anyelement)</> will take any two input values,
182+
so long as they are of the same data type.
183+
</para>
184+
185+
<para>
186+
When the return value of a function is declared as a polymorphic type,
187+
there must be at least one argument position that is also polymorphic,
188+
and the actual data type supplied as the argument determines the actual
189+
result type for that call. For example, if there were not already
190+
an array subscripting mechanism, one could define a function that
191+
implements subscripting as <literal>subscript(anyarray, integer)
192+
returns anyelement</>. This declaration constrains the actual first
193+
argument to be an array type, and allows the parser to infer the correct
194+
result type from the actual first argument's type.
195+
</para>
196+
</sect2>
103197
</sect1>
104198

105199
&xfunc;
200+
&xaggr;
106201
&xtypes;
107202
&xoper;
108-
&xaggr;
109203
&xindex;
110204

111205
</chapter>

‎doc/src/sgml/func.sgml

Lines changed: 41 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$Header: /cvsroot/pgsql/doc/src/sgml/func.sgml,v 1.164 2003/08/04 14:00:13 petere Exp $
2+
$Header: /cvsroot/pgsql/doc/src/sgml/func.sgml,v 1.165 2003/08/09 22:50:21 tgl Exp $
33
PostgreSQL documentation
44
-->
55

@@ -7044,28 +7044,67 @@ SELECT pg_type_is_visible('myschema.widget'::regtype);
70447044
<tbody>
70457045
<row>
70467046
<entry> <literal>=</literal> </entry>
7047-
<entry>equals</entry>
7047+
<entry>equal</entry>
70487048
<entry><literal>ARRAY[1.1,2.1,3.1]::int[] = ARRAY[1,2,3]</literal></entry>
70497049
<entry><literal>t</literal></entry>
70507050
</row>
7051+
7052+
<row>
7053+
<entry> <literal>&lt;&gt;</literal> </entry>
7054+
<entry>not equal</entry>
7055+
<entry><literal>ARRAY[1,2,3] &lt;&gt; ARRAY[1,2,4]</literal></entry>
7056+
<entry><literal>t</literal></entry>
7057+
</row>
7058+
7059+
<row>
7060+
<entry> <literal>&lt;</literal> </entry>
7061+
<entry>less than</entry>
7062+
<entry><literal>ARRAY[1,2,3] &lt; ARRAY[1,2,4]</literal></entry>
7063+
<entry><literal>t</literal></entry>
7064+
</row>
7065+
7066+
<row>
7067+
<entry> <literal>&gt;</literal> </entry>
7068+
<entry>greater than</entry>
7069+
<entry><literal>ARRAY[1,4,3] &gt; ARRAY[1,2,4]</literal></entry>
7070+
<entry><literal>t</literal></entry>
7071+
</row>
7072+
7073+
<row>
7074+
<entry> <literal>&lt;=</literal> </entry>
7075+
<entry>less than or equal</entry>
7076+
<entry><literal>ARRAY[1,2,3] &lt;= ARRAY[1,2,3]</literal></entry>
7077+
<entry><literal>t</literal></entry>
7078+
</row>
7079+
7080+
<row>
7081+
<entry> <literal>&gt;=</literal> </entry>
7082+
<entry>greater than or equal</entry>
7083+
<entry><literal>ARRAY[1,4,3] &gt;= ARRAY[1,4,3]</literal></entry>
7084+
<entry><literal>t</literal></entry>
7085+
</row>
7086+
70517087
<row>
70527088
<entry> <literal>||</literal> </entry>
70537089
<entry>array-to-array concatenation</entry>
70547090
<entry><literal>ARRAY[1,2,3] || ARRAY[4,5,6]</literal></entry>
70557091
<entry><literal>{{1,2,3},{4,5,6}}</literal></entry>
70567092
</row>
7093+
70577094
<row>
70587095
<entry> <literal>||</literal> </entry>
70597096
<entry>array-to-array concatenation</entry>
70607097
<entry><literal>ARRAY[1,2,3] || ARRAY[[4,5,6],[7,8,9]]</literal></entry>
70617098
<entry><literal>{{1,2,3},{4,5,6},{7,8,9}}</literal></entry>
70627099
</row>
7100+
70637101
<row>
70647102
<entry> <literal>||</literal> </entry>
70657103
<entry>element-to-array concatenation</entry>
70667104
<entry><literal>3 || ARRAY[4,5,6]</literal></entry>
70677105
<entry><literal>{3,4,5,6}</literal></entry>
70687106
</row>
7107+
70697108
<row>
70707109
<entry> <literal>||</literal> </entry>
70717110
<entry>array-to-element concatenation</entry>

0 commit comments

Comments
 (0)