open-dsi
/
postgres
mirror of https://github.com/postgres/postgres
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Clean up wrong, misleading, or obsolete documentation about array types,

Browse Source 
particularly in the CREATE TYPE reference page.  Fix some other errors
in the CREATE TYPE page, too.
REL7_2_STABLE
Tom Lane 25 years ago
parent f008976bcd
commit 3d5ddc0b3c
4 changed files with 139 additions and 89 deletions
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Show Stats Download Patch File Download Diff File
  1. 11
      doc/src/sgml/array.sgml
  2. 31
      doc/src/sgml/catalogs.sgml
  3. 180
      doc/src/sgml/ref/create_type.sgml
  4. 6
      doc/src/sgml/ref/drop_type.sgml

11
doc/src/sgml/array.sgml
Unescape View File

@ -1,4 +1,4 @@
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/array.sgml,v 1.12 2001/09/09 17:21:44 petere Exp $ -->
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/array.sgml,v 1.13 2001/11/03 21:42:47 tgl Exp $ -->
<chapter id="arrays">
<title>Arrays</title>
@ -23,15 +23,15 @@ CREATE TABLE sal_emp (
<structname>sal_emp</structname> with a <type>text</type> string
(<structfield>name</structfield>), a one-dimensional array of type
<type>integer</type> (<structfield>pay_by_quarter</structfield>),
which shall represent the employee's salary by quarter, and a
which represents the employee's salary by quarter, and a
two-dimensional array of <type>text</type>
(<structfield>schedule</structfield>), which represents the
employee's weekly schedule.
</para>
<para>
Now we do some <command>INSERT</command>s; note that when appending
to an array, we enclose the values within braces and separate them
Now we do some <command>INSERT</command>s. Observe that to write an array
value, we enclose the element values within braces and separate them
by commas. If you know C, this is not unlike the syntax for
initializing structures.
@ -200,8 +200,7 @@ SELECT * FROM sal_emp WHERE pay_by_quarter[1] = 10000 OR
However, this quickly becomes tedious for large arrays, and is not
helpful if the size of the array is unknown. Although it is not part
of the primary <productname>PostgreSQL</productname> distribution,
in the contributions directory, there is an extension to
<productname>PostgreSQL</productname> that defines new functions and
there is an extension available that defines new functions and
operators for iterating over array values. Using this, the above
query could be:

31
doc/src/sgml/catalogs.sgml
Unescape View File

@ -1,6 +1,6 @@
<!--
Documentation of the system catalogs, directed toward PostgreSQL developers
$Header: /cvsroot/pgsql/doc/src/sgml/catalogs.sgml,v 2.26 2001/10/15 22:47:47 tgl Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/catalogs.sgml,v 2.27 2001/11/03 21:42:47 tgl Exp $
-->
<chapter id="catalogs">
@ -420,7 +420,9 @@
<entry><type>int4</type></entry>
<entry></entry>
<entry>
Number of dimensions, if the column is an array; otherwise 0.
Number of dimensions, if the column is an array type; otherwise 0.
(Presently, the number of dimensions of an array is not enforced,
so any nonzero value effectively means <quote>it's an array</>.)
</entry>
</row>
@ -1064,7 +1066,7 @@
<entry><type>int2vector</type></entry>
<entry>pg_attribute.attnum</entry>
<entry>
This is an vector (array) of up to
This is a vector (array) of up to
<symbol>INDEX_MAX_KEYS</symbol> values that indicate which
table columns this index pertains to. For example a value of
<literal>1 3</literal> would mean that the first and the third
@ -2336,7 +2338,9 @@
<entry>typdelim</entry>
<entry><type>char</type></entry>
<entry></entry>
<entry>Character that separates two values of this type when parsing array input</entry>
<entry>Character that separates two values of this type when parsing
array input. Note that the delimiter is associated with the array
element datatype, not the array datatype.</entry>
</row>
<row>
@ -2360,14 +2364,17 @@
If <structfield>typelem</structfield> is not 0 then it
identifies another row in <structname>pg_type</structname>.
The current type can then be subscripted like an array yielding
values of type <structfield>typelem</structfield>. A non-zero
<structfield>typelem</structfield> does not guarantee this type
to be a <quote>real</quote> array type; some ordinary
fixed-length types can also be subscripted (e.g.,
<type>oidvector</type>). Variable-length types can
<emphasis>not</emphasis> be turned into pseudo-arrays like
that. Hence, the way to determine whether a type is a
<quote>true</quote> array type is typelem != 0 and typlen < 0.
values of type <structfield>typelem</structfield>. A
<quote>true</quote> array type is variable length
(<structfield>typlen</structfield> = -1),
but some fixed-length (<structfield>typlen</structfield> &gt; 0) types
also have nonzero <structfield>typelem</structfield>, for example
<type>name</type> and <type>oidvector</type>.
If a fixed-length type has a <structfield>typelem</structfield> then
its internal representation must be N values of the
<structfield>typelem</structfield> datatype with no other data.
Variable-length array types have a header defined by the array
subroutines.
</entry>
</row>

180
doc/src/sgml/ref/create_type.sgml
Unescape View File

@ -1,5 +1,5 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_type.sgml,v 1.23 2001/09/13 19:05:29 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_type.sgml,v 1.24 2001/11/03 21:42:47 tgl Exp $
Postgres documentation
-->
@ -27,7 +27,7 @@ CREATE TYPE <replaceable class="parameter">typename</replaceable> ( INPUT = <rep
, INTERNALLENGTH = { <replaceable
class="parameter">internallength</replaceable> | VARIABLE }
[ , EXTERNALLENGTH = { <replaceable class="parameter">externallength</replaceable> | VARIABLE } ]
[ , DEFAULT = "<replaceable class="parameter">default</replaceable>" ]
[ , DEFAULT = <replaceable class="parameter">default</replaceable> ]
[ , ELEMENT = <replaceable class="parameter">element</replaceable> ] [ , DELIMITER = <replaceable class="parameter">delimiter</replaceable> ]
[ , SEND = <replaceable class="parameter">send_function</replaceable> ] [ , RECEIVE = <replaceable class="parameter">receive_function</replaceable> ]
[ , PASSEDBYVALUE ]
@ -113,7 +113,8 @@ CREATE TYPE <replaceable class="parameter">typename</replaceable> ( INPUT = <rep
<term><replaceable class="parameter">delimiter</replaceable></term>
<listitem>
<para>
The delimiter character for the array elements.
The delimiter character to be used between values in arrays made
of this type.
</para>
</listitem>
</varlistentry>
@ -219,82 +220,101 @@ CREATE
<para>
<command>CREATE TYPE</command> requires the registration of two functions
(using create function) before defining the type. The
(using CREATE FUNCTION) before defining the type. The
representation of a new base type is determined by
<replaceable class="parameter">input_function</replaceable>, which
converts the type's external representation to an internal
representation usable by the
operators and functions defined for the type. Naturally,
<replaceable class="parameter">output_function</replaceable>
performs the reverse transformation. Both
the input and output functions must be declared to take
one or two arguments of type <type>opaque</type>.
performs the reverse transformation. The input function may be
declared as taking one argument of type <type>opaque</type>,
or as taking three arguments of types
<type>opaque</type>, <type>OID</type>, <type>int4</type>.
(The first argument is the input text as a C string, the second
argument is the element type in case this is an array type,
and the third is the typmod of the destination column, if known.)
The output function may be
declared as taking one argument of type <type>opaque</type>,
or as taking two arguments of types
<type>opaque</type>, <type>OID</type>.
(The first argument is actually of the datatype itself, but since the
output function must be declared first, it's easier to declare it as
accepting type <type>opaque</type>. The second argument is again
the array element type for array types.)
</para>
<para>
New base data types can be fixed length, in which case
<replaceable class="parameter">internallength</replaceable> is a
positive integer, or variable length,
in which case PostgreSQL assumes that the new type has the
same format
as the PostgreSQL-supplied data type, <type>text</type>.
To indicate that a type is variable length, set
positive integer, or variable length, indicated by setting
<replaceable class="parameter">internallength</replaceable>
to <option>VARIABLE</option>.
The external representation is similarly specified using the
to <option>VARIABLE</option>. (Internally, this is represented
by setting typlen to -1.) The internal representation of all
variable-length types must start with an integer giving the total
length of this value of the type.
</para>
<para>
The external representation length is similarly specified using the
<replaceable class="parameter">externallength</replaceable>
keyword.
keyword. (This value is not presently used, and is typically omitted,
letting it default to <option>VARIABLE</option>.)
</para>
<para>
To indicate that a type is an array and to indicate that a
type has array elements, indicate the type of the array
element using the element keyword. For example, to define
To indicate that a type is an array,
specify the type of the array
elements using the <option>ELEMENT</> keyword. For example, to define
an array of 4-byte integers ("int4"), specify
<programlisting>ELEMENT = int4</programlisting>
More details about array types appear below.
</para>
<para>
To indicate the delimiter to be used on arrays of this
type, <replaceable class="parameter">delimiter</replaceable>
can be
To indicate the delimiter to be used between values in the external
representation of arrays of this type, <replaceable
class="parameter">delimiter</replaceable> can be
set to a specific character. The default delimiter is the comma
("<literal>,</literal>").
('<literal>,</literal>'). Note that the delimiter is associated
with the array element type, not the array type itself.
</para>
<para>
A default value is optionally available in case a user
wants some specific bit pattern to mean <quote>data not present</quote>.
Specify the default with the <literal>DEFAULT</literal> keyword.
<comment>How does the user specify that bit pattern and associate
it with the fact that the data is not present></comment>
A default value may be specified, in case a user wants columns of the
datatype to default to something other than NULL.
Specify the default with the <option>DEFAULT</option> keyword.
(Such a default may be overridden by an explicit <option>DEFAULT</option>
clause attached to a particular column.)
</para>
<para>
The optional arguments
<replaceable class="parameter">send_function</replaceable> and
<replaceable class="parameter">receive_function</replaceable>
are used when the application program requesting PostgreSQL
services resides on a different machine. In this case,
the machine on which PostgreSQL runs may use a format for the data
type different from that used on the remote machine.
In this case it is appropriate to convert data items to a
standard form when sending from the server to the client
and converting from the standard format to the machine
specific format when the server receives the data from the
client. If these functions are not specified, then it is
assumed that the internal format of the type is acceptable
on all relevant machine architectures. For example, single
characters do not have to be converted if passed from
a Sun-4 to a DECstation, but many other types do.
are not currently used, and are usually omitted (allowing them
to default to the
<replaceable class="parameter">output_function</replaceable> and
<replaceable class="parameter">input_function</replaceable>
respectively). These functions may someday be resurrected for use
in specifying machine-independent binary representations.
</para>
<para>
The optional flag, <option>PASSEDBYVALUE</option>, indicates that operators
and functions which use this data type should be passed an
argument by value rather than by reference. Note that you
The optional flag, <option>PASSEDBYVALUE</option>, indicates that
values of this data type are passed
by value rather than by reference. Note that you
may not pass by value types whose internal representation is
more than four bytes.
longer than the width of the <type>Datum</> type (four bytes on
most machines, eight bytes on a few).
</para>
<para>
The <replaceable class="parameter">alignment</replaceable> keyword
specifies the storage alignment required for the datatype. The
allowed values equate to alignment on 1, 2, 4, or 8 byte boundaries.
Note that variable-length types must have an alignment of at least
4, since they necessarily contain an <type>int4</> as their first component.
</para>
<para>
@ -315,19 +335,40 @@ CREATE
<literal>extended</literal> and <literal>external</literal> items.)
</para>
<para>
For new base types, a user can define operators, functions
and aggregates using the appropriate facilities described
in this section.
</para>
<refsect2>
<title>Array Types</title>
<para>
Two generalized built-in functions, array_in and
array_out, exist for quick creation of variable-length
array types. These functions operate on arrays of any
existing PostgreSQL type.
Whenever a user-defined datatype is created,
<productname>PostgreSQL</productname> automatically creates an
associated array type, whose name consists of the base type's
name prepended with an underscore. The parser understands this
naming convention, and translates requests for columns of type
<literal>foo[]</> into requests for type <literal>_foo</>.
The implicitly-created array type is variable length and uses the
built-in input and output functions <literal>array_in</> and
<literal>array_out</>.
</para>
<para>
You might reasonably ask <quote>why is there an <option>ELEMENT</>
option, if the system makes the correct array type automatically?</quote>
The only case where it's useful to use <option>ELEMENT</> is when you are
making a fixed-length type that happens to be internally an array of N
identical things, and you want to allow the N things to be accessed
directly by subscripting, in addition to whatever operations you plan
to provide for the type as a whole. For example, type <type>name</>
allows its constitutent <type>char</>s to be accessed this way.
A 2-D <type>point</> type could allow its two component floats to be
accessed like <literal>point[0]</> and <literal>point[1]</>.
Note that
this facility only works for fixed-length types whose internal form
is exactly a sequence of N identical fields. A subscriptable
variable-length type must have the generalized internal representation
used by <literal>array_in</> and <literal>array_out</>.
For historical reasons (i.e., this is clearly wrong but it's far too
late to change it), subscripting of fixed-length array types starts from
zero, rather than from one as for variable-length arrays.
</para>
</refsect2>
</refsect1>
@ -336,41 +377,42 @@ CREATE
<title>Notes</title>
<para>
Type names cannot begin with the underscore character
(<quote><literal>_</literal></quote>) and can only be 31
characters long. This is because PostgreSQL silently creates an
array type for each base type with a name consisting of the base
type's name prepended with an underscore.
User-defined type names cannot begin with the underscore character
(<quote><literal>_</literal></quote>) and can only be 30
characters long (or in general <literal>NAMEDATALEN-2</>, rather than
the <literal>NAMEDATALEN-1</> characters allowed for other names).
Type names beginning with underscore are
reserved for internally-created array type names.
</para>
</refsect1>
<refsect1>
<title>Examples</title>
<para>
This command creates the <type>box</type> data type and then uses the
This example creates the <type>box</type> data type and then uses the
type in a table definition:
<programlisting>
CREATE TYPE box (INTERNALLENGTH = 8,
CREATE TYPE box (INTERNALLENGTH = 16,
INPUT = my_procedure_1, OUTPUT = my_procedure_2);
CREATE TABLE myboxes (id INT4, description box);
</programlisting>
</para>
<para>
This command creates a variable length array type with
<type>integer</type> elements:
If <type>box</type>'s internal structure were an array of four
<type>float4</>s, we might instead say
<programlisting>
CREATE TYPE int4array (INPUT = array_in, OUTPUT = array_out,
INTERNALLENGTH = VARIABLE, ELEMENT = int4);
CREATE TABLE myarrays (id int4, numbers int4array);
CREATE TYPE box (INTERNALLENGTH = 16,
INPUT = my_procedure_1, OUTPUT = my_procedure_2,
ELEMENT = float4);
</programlisting>
which would allow a box value's component floats to be accessed
by subscripting. Otherwise the type behaves the same as before.
</para>
<para>
This command creates a large object type and uses it in
This example creates a large object type and uses it in
a table definition:
<programlisting>
CREATE TYPE bigobj (INPUT = lo_filein, OUTPUT = lo_fileout,
INTERNALLENGTH = VARIABLE);

6
doc/src/sgml/ref/drop_type.sgml
Unescape View File

@ -1,5 +1,5 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_type.sgml,v 1.11 2001/09/13 19:05:29 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_type.sgml,v 1.12 2001/11/03 21:42:47 tgl Exp $
Postgres documentation
-->
@ -105,7 +105,9 @@ ERROR: RemoveType: type '<replaceable class="parameter">typename</replaceable>'
<para>
It is the user's responsibility to remove any operators,
functions, aggregates, access methods, subtypes, and tables that
use a deleted type.
use a deleted type. However, the associated array datatype
(which was automatically created by <command>CREATE TYPE</command>)
will be removed automatically.
</para>
</listitem>

Write Preview
Loading…
Cancel
Save