From 45d04099df76c00d93479b2617fb9975807fdb43 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Thu, 8 May 2003 22:19:58 +0000 Subject: Reinstate pg_type's typsend and typreceive columns. They don't do much yet, but they're there. Also some editorial work on CREATE TYPE reference page. --- doc/src/sgml/catalogs.sgml | 37 +++--- doc/src/sgml/ref/create_type.sgml | 238 ++++++++++++++++++++++++-------------- 2 files changed, 176 insertions(+), 99 deletions(-) (limited to 'doc/src/sgml') diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml index e70cee4506f..0cc355330dd 100644 --- a/doc/src/sgml/catalogs.sgml +++ b/doc/src/sgml/catalogs.sgml @@ -1,6 +1,6 @@ @@ -3315,9 +3315,9 @@ The catalog pg_type stores information about data types. Base types (scalar types) are created with CREATE TYPE. - A complex type is automatically created for each table in the database, to + A composite type is automatically created for each table in the database, to represent the row structure of the table. It is also possible to create - complex types with CREATE TYPE AS and + composite types with CREATE TYPE AS and derived types with CREATE DOMAIN. @@ -3378,12 +3378,9 @@ typbyval determines whether internal routines pass a value of this type by value or by reference. - Only char, short, and - int equivalent items can be passed by value, so if - the type is not 1, 2, or 4 bytes long, - PostgreSQL does not have - the option of passing by value and so - typbyval had better be false. + typbyval had better be false if + typlen is not 1, 2, or 4 (or 8 on machines + where Datum is 8 bytes). Variable-length types are always passed by reference. Note that typbyval can be false even if the length would allow pass-by-value; this is currently true for @@ -3397,7 +3394,7 @@ typtype is b for - a base type, c for a complex type (i.e., + a base type, c for a composite type (i.e., a table's row type), d for a derived type (i.e., a domain), or p for a pseudo-type. See also typrelid @@ -3431,7 +3428,7 @@ oid pg_class.oid - If this is a complex type (see + If this is a composite type (see typtype), then this column points to the pg_class entry that defines the corresponding table. (For a free-standing composite type, the @@ -3468,14 +3465,28 @@ typinput regproc pg_proc.oid - Input conversion function + Input conversion function (text format) typoutput regproc pg_proc.oid - Output conversion function + Output conversion function (text format) + + + + typreceive + regproc + pg_proc.oid + Input conversion function (binary format), or 0 if none + + + + typsend + regproc + pg_proc.oid + Output conversion function (binary format), or 0 if none diff --git a/doc/src/sgml/ref/create_type.sgml b/doc/src/sgml/ref/create_type.sgml index 70a4a6cb808..5fe4d2be4fc 100644 --- a/doc/src/sgml/ref/create_type.sgml +++ b/doc/src/sgml/ref/create_type.sgml @@ -1,5 +1,5 @@ @@ -16,18 +16,22 @@ PostgreSQL documentation +CREATE TYPE typename AS + ( attribute_name data_type [, ... ] ) + CREATE TYPE typename ( - INPUT = input_function, OUTPUT = output_function - , INTERNALLENGTH = { internallength | VARIABLE } - [ , DEFAULT = default ] - [ , ELEMENT = element ] [ , DELIMITER = delimiter ] + INPUT = input_function, + OUTPUT = output_function + [ , RECEIVE = receive_function ] + [ , SEND = send_function ] + [ , INTERNALLENGTH = { internallength | VARIABLE } ] [ , PASSEDBYVALUE ] [ , ALIGNMENT = alignment ] [ , STORAGE = storage ] + [ , DEFAULT = default ] + [ , ELEMENT = element ] + [ , DELIMITER = delimiter ] ) - -CREATE TYPE typename AS - ( attribute_name data_type [, ... ] ) @@ -49,18 +53,42 @@ CREATE TYPE typename AS table in the same schema.) + + Composite Types + + + The first form of CREATE TYPE + creates a composite type. + The composite type is specified by a list of attribute names and data types. + This is essentially the same as the row type + of a table, but using CREATE TYPE avoids the need to + create an actual table when all that is wanted is to define a type. + A stand-alone composite type is useful as the return type of a function. + + + Base Types - The first form of CREATE TYPE creates a new base type - (scalar type). It requires the - registration of two functions (using CREATE - FUNCTION) before defining the - type. The internal representation of the new base type is determined by - input_function, which - converts the type's external representation to an internal - representation usable by the + The second form of CREATE TYPE creates a new base type + (scalar type). The parameters may appear in any order, not only that + illustrated above, and most are optional. You must register + two or more functions (using CREATE FUNCTION) before + defining the type. The support functions + input_function and + output_function + are required, while the functions + receive_function and + send_function + are optional. Generally these functions have to be coded in C + or another low-level language. + + + + The input_function + converts the type's external textual representation to the internal + representation used by the operators and functions defined for the type. output_function performs the reverse transformation. The input function may be @@ -70,7 +98,7 @@ CREATE TYPE typename AS 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. - It should return a value of the data type itself. + The input function should return a value of the data type itself. The output function may be declared as taking one argument of the new data type, or as taking two arguments of which the second is type oid. @@ -78,22 +106,50 @@ CREATE TYPE typename AS The output function should return type cstring. + + The optional receive_function + converts the type's external binary representation to the internal + representation. If this function is not supplied, the type cannot + participate in binary input. The binary representation should be + chosen to be cheap to convert to internal form, while being reasonably + portable. (For example, the standard integer datatypes use network + byte order as the external binary representation, while the internal + representation is in the machine's native byte order.) The receive + function should perform adequate checking to ensure that the value is + valid. + The receive function should be declared as taking one argument of type + internal and returning a value of the data type itself. + (The argument actually supplied is a pointer to a StringInfo buffer + holding the received byte string.) Similarly, the optional + send_function converts + from the internal representation to the external binary representation. + If this function is not supplied, the type cannot participate in binary + output. The send function should be declared as taking one argument of the + new data type and returning type bytea. + + You should at this point be wondering how the input and output functions can be declared to have results or arguments of the new type, when they have to be created before the new type can be created. The answer is that the - input function must be created first, then the output function, then the - data type. + input function must be created first, then the output function (and + the binary I/O functions if wanted), and finally the data type. PostgreSQL will first see the name of the new data type as the return type of the input function. It will create a shell type, which is simply a placeholder entry in the system catalog, and link the input function definition to the shell - type. Similarly the output function will be linked to the (now already + type. Similarly the other functions will be linked to the (now already existing) shell type. Finally, CREATE TYPE replaces the shell entry with a complete type definition, and the new type can be used. + While the details of the new type's internal representation are only + known to the I/O functions and other functions you create to work with + the type, there are several properties of the internal representation + that must be declared to PostgreSQL. + Foremost of these is + internallength. Base data types can be fixed-length, in which case internallength is a positive integer, or variable length, indicated by setting @@ -104,34 +160,9 @@ CREATE TYPE typename AS length of this value of the type. - - To indicate that a type is an array, specify the type of the array - elements using the ELEMENT key word. For example, to - define an array of 4-byte integers (int4), specify - ELEMENT = int4 More details about array types - appear below. - - - - To indicate the delimiter to be used between values in the external - representation of arrays of this type, delimiter can be - set to a specific character. The default delimiter is the comma - (,). Note that the delimiter is associated - with the array element type, not the array type itself. - - - - A default value may be specified, in case a user wants columns of the - data type to default to something other than the null value. - Specify the default with the DEFAULT key word. - (Such a default may be overridden by an explicit DEFAULT - clause attached to a particular column.) - - The optional flag PASSEDBYVALUE indicates that - values of this data type are passed by value rather than by + values of this data type are passed by value, rather than by reference. You may not pass by value types whose internal representation is larger than the size of the Datum type (4 bytes on most machines, 8 bytes on a few). @@ -163,20 +194,32 @@ CREATE TYPE typename AS table preferentially over extended and external items.) - - - Composite Types + + A default value may be specified, in case a user wants columns of the + data type to default to something other than the null value. + Specify the default with the DEFAULT key word. + (Such a default may be overridden by an explicit DEFAULT + clause attached to a particular column.) + - The second form of CREATE TYPE - creates a composite type. - The composite type is specified by a list of attribute names and data types. - This is essentially the same as the row type - of a table, but using CREATE TYPE avoids the need to - create an actual table when all that is wanted is to define a type. - A stand-alone composite type is useful as the return type of a function. + To indicate that a type is an array, specify the type of the array + elements using the ELEMENT key word. For example, to + define an array of 4-byte integers (int4), specify + ELEMENT = int4. More details about array types + appear below. + + + + To indicate the delimiter to be used between values in the external + representation of arrays of this type, delimiter can be + set to a specific character. The default delimiter is the comma + (,). Note that the delimiter is associated + with the array element type, not the array type itself. + @@ -218,7 +261,7 @@ CREATE TYPE typename AS - Parameter + Parameters @@ -231,11 +274,20 @@ CREATE TYPE typename AS - internallength + attribute_name - A numeric constant that specifies the internal length of the new - type. + The name of an attribute (column) for the composite type. + + + + + + data_type + + + The name of an existing data type to become a column of the + composite type. @@ -245,7 +297,7 @@ CREATE TYPE typename AS The name of a function that converts data from the type's - external form to the its internal form. + external textual form to its internal form. @@ -255,37 +307,38 @@ CREATE TYPE typename AS The name of a function that converts data from the type's - internal form to a form suitable for display. + internal form to its external textual form. - element + receive_function - The type being created is an array; this specifies the type of - the array elements. + The name of a function that converts data from the type's + external binary form to its internal form. - delimiter + send_function - The delimiter character to be used between values in arrays made - of this type. + The name of a function that converts data from the type's + internal form to its external binary form. - default + internallength - The default value for the data type. If this is omitted, the - default is null. + A numeric constant that specifies the length in bytes of the new + type's internal representation. The default assumption is that + it is variable-length. @@ -306,7 +359,7 @@ CREATE TYPE typename AS storage - The storage strateg for the data type. If specified, must be + The storage strategy for the data type. If specified, must be plain, external, extended, or main; the default is plain. @@ -315,19 +368,31 @@ CREATE TYPE typename AS - attribute_name + default - The name of an attribute of the composite type. + The default value for the data type. If this is omitted, the + default is null. - data_type + element - The name of an existing data type. + The type being created is an array; this specifies the type of + the array elements. + + + + + + delimiter + + + The delimiter character to be used between values in arrays made + of this type. @@ -378,7 +443,17 @@ CREATE TYPE typename AS Examples - This example creates the data type box and then uses the + This example creates a composite type and uses it in + a function definition: + +CREATE TYPE compfoo AS (f1 int, f2 text); +CREATE FUNCTION getfoo() RETURNS SETOF compfoo AS + 'SELECT fooid, fooname FROM foo' LANGUAGE SQL; + + + + + This example creates the base data type box and then uses the type in a table definition: CREATE TYPE box ( @@ -424,15 +499,6 @@ CREATE TABLE big_objs ( - - This example creates a composite type and uses it in - a function definition: - -CREATE TYPE compfoo AS (f1 int, f2 text); -CREATE FUNCTION getfoo() RETURNS SETOF compfoo AS 'SELECT fooid, fooname FROM foo' LANGUAGE SQL; - - - More examples, including suitable input and output functions, are in . -- cgit v1.2.3