diff options
Diffstat (limited to 'doc/src')
| -rw-r--r-- | doc/src/sgml/datatype.sgml | 16 | ||||
| -rw-r--r-- | doc/src/sgml/extend.sgml | 18 | ||||
| -rw-r--r-- | doc/src/sgml/func.sgml | 46 | ||||
| -rw-r--r-- | doc/src/sgml/plpgsql.sgml | 8 | ||||
| -rw-r--r-- | doc/src/sgml/xfunc.sgml | 8 |
5 files changed, 74 insertions, 22 deletions
diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml index 3802aa24dff..c64b040e457 100644 --- a/doc/src/sgml/datatype.sgml +++ b/doc/src/sgml/datatype.sgml @@ -1,4 +1,4 @@ -<!-- $PostgreSQL: pgsql/doc/src/sgml/datatype.sgml,v 1.203 2007/06/01 23:40:18 neilc Exp $ --> +<!-- $PostgreSQL: pgsql/doc/src/sgml/datatype.sgml,v 1.204 2007/06/06 23:00:35 tgl Exp $ --> <chapter id="datatype"> <title id="datatype-title">Data Types</title> @@ -3677,11 +3677,15 @@ SELECT * FROM pg_attribute </indexterm> <indexterm zone="datatype-pseudo"> + <primary>anyelement</primary> + </indexterm> + + <indexterm zone="datatype-pseudo"> <primary>anyarray</primary> </indexterm> <indexterm zone="datatype-pseudo"> - <primary>anyelement</primary> + <primary>anynonarray</primary> </indexterm> <indexterm zone="datatype-pseudo"> @@ -3761,6 +3765,12 @@ SELECT * FROM pg_attribute </row> <row> + <entry><type>anynonarray</></entry> + <entry>Indicates that a function accepts any non-array data type + (see <xref linkend="extend-types-polymorphic">).</entry> + </row> + + <row> <entry><type>cstring</></entry> <entry>Indicates that a function accepts or returns a null-terminated C string.</entry> </row> @@ -3813,7 +3823,7 @@ SELECT * FROM pg_attribute only <type>void</> and <type>record</> as a result type (plus <type>trigger</> when the function is used as a trigger). Some also support polymorphic functions using the types <type>anyarray</>, - <type>anyelement</> and <type>anyenum</>. + <type>anyelement</>, <type>anyenum</>, and <type>anynonarray</>. </para> <para> diff --git a/doc/src/sgml/extend.sgml b/doc/src/sgml/extend.sgml index bb5834e74a9..28bdfb85322 100644 --- a/doc/src/sgml/extend.sgml +++ b/doc/src/sgml/extend.sgml @@ -1,4 +1,4 @@ -<!-- $PostgreSQL: pgsql/doc/src/sgml/extend.sgml,v 1.34 2007/04/02 03:49:36 tgl Exp $ --> +<!-- $PostgreSQL: pgsql/doc/src/sgml/extend.sgml,v 1.35 2007/06/06 23:00:35 tgl Exp $ --> <chapter id="extend"> <title>Extending <acronym>SQL</acronym></title> @@ -193,8 +193,8 @@ </indexterm> <para> - Three pseudo-types of special interest are <type>anyelement</>, - <type>anyarray</>, and <type>anyenum</>, + Four pseudo-types of special interest are <type>anyelement</>, + <type>anyarray</>, <type>anynonarray</>, and <type>anyenum</>, which are collectively called <firstterm>polymorphic types</>. Any function declared using these types is said to be a <firstterm>polymorphic function</>. A polymorphic function can @@ -216,6 +216,9 @@ <type>anyelement</type>, the actual array type in the <type>anyarray</type> positions must be an array whose elements are the same type appearing in the <type>anyelement</type> positions. + <type>anynonarray</> is treated exactly the same as <type>anyelement</>, + but adds the additional constraint that the actual type must not be + an array type. <type>anyenum</> is treated exactly the same as <type>anyelement</>, but adds the additional constraint that the actual type must be an enum type. @@ -242,6 +245,15 @@ is that a function declared as <literal>f(anyarray) returns anyenum</> will only accept arrays of enum types. </para> + + <para> + Note that <type>anynonarray</> and <type>anyenum</> do not represent + separate type variables; they are the same type as + <type>anyelement</type>, just with an additional constraint. For + example, declaring a function as <literal>f(anyelement, anyenum)</> + is equivalent to declaring it as <literal>f(anyenum, anyenum)</>: + both actual arguments have to be the same enum type. + </para> </sect2> </sect1> diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index c2f3371dc48..387c4e81c8f 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -1,4 +1,4 @@ -<!-- $PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.381 2007/05/30 18:13:29 momjian Exp $ --> +<!-- $PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.382 2007/06/06 23:00:35 tgl Exp $ --> <chapter id="functions"> <title>Functions and Operators</title> @@ -986,24 +986,36 @@ <para> This section describes functions and operators for examining and manipulating string values. Strings in this context include values - of all the types <type>character</type>, <type>character - varying</type>, and <type>text</type>. Unless otherwise noted, all + of the types <type>character</type>, <type>character varying</type>, + and <type>text</type>. Unless otherwise noted, all of the functions listed below work on all of these types, but be - wary of potential effects of the automatic padding when using the - <type>character</type> type. Generally, the functions described - here also work on data of non-string types by converting that data - to a string representation first. Some functions also exist + wary of potential effects of automatic space-padding when using the + <type>character</type> type. Some functions also exist natively for the bit-string types. </para> <para> - <acronym>SQL</acronym> defines some string functions with a special syntax where - certain key words rather than commas are used to separate the + <acronym>SQL</acronym> defines some string functions with a special syntax + wherein certain key words rather than commas are used to separate the arguments. Details are in <xref linkend="functions-string-sql">. These functions are also implemented using the regular syntax for function invocation. (See <xref linkend="functions-string-other">.) </para> + <note> + <para> + Before <productname>PostgreSQL</productname> 8.3, these functions would + silently accept values of several non-string data types as well, due to + the presence of implicit coercions from those data types to + <type>text</>. Those coercions have been removed because they frequently + caused surprising behaviors. However, the string concatenation operator + (<literal>||</>) still accepts non-string input, so long as at least one + input is of a string type, as shown in <xref + linkend="functions-string-sql">. For other cases, insert an explicit + coercion to <type>text</> if you need to duplicate the previous behavior. + </para> + </note> + <indexterm> <primary>bit_length</primary> </indexterm> @@ -1065,6 +1077,22 @@ </row> <row> + <entry> + <literal><parameter>string</parameter> <literal>||</literal> + <parameter>non-string</parameter></literal> + or + <literal><parameter>non-string</parameter> <literal>||</literal> + <parameter>string</parameter></literal> + </entry> + <entry> <type>text</type> </entry> + <entry> + String concatenation with one non-string input + </entry> + <entry><literal>'Value: ' || 42</literal></entry> + <entry><literal>Value: 42</literal></entry> + </row> + + <row> <entry><literal><function>bit_length</function>(<parameter>string</parameter>)</literal></entry> <entry><type>int</type></entry> <entry>Number of bits in string</entry> diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml index c1f57ddf4f8..d14519b6133 100644 --- a/doc/src/sgml/plpgsql.sgml +++ b/doc/src/sgml/plpgsql.sgml @@ -1,4 +1,4 @@ -<!-- $PostgreSQL: pgsql/doc/src/sgml/plpgsql.sgml,v 1.109 2007/04/29 01:21:08 neilc Exp $ --> +<!-- $PostgreSQL: pgsql/doc/src/sgml/plpgsql.sgml,v 1.110 2007/06/06 23:00:36 tgl Exp $ --> <chapter id="plpgsql"> <title><application>PL/pgSQL</application> - <acronym>SQL</acronym> Procedural Language</title> @@ -210,8 +210,8 @@ $$ LANGUAGE plpgsql; <para> <application>PL/pgSQL</> functions can also be declared to accept and return the polymorphic types - <type>anyelement</type>, <type>anyarray</type>, and <type>anyenum</>. - The actual + <type>anyelement</type>, <type>anyarray</type>, <type>anynonarray</type>, + and <type>anyenum</>. The actual data types handled by a polymorphic function can vary from call to call, as discussed in <xref linkend="extend-types-polymorphic">. An example is shown in <xref linkend="plpgsql-declaration-aliases">. @@ -700,7 +700,7 @@ $$ LANGUAGE plpgsql; <para> When the return type of a <application>PL/pgSQL</application> function is declared as a polymorphic type (<type>anyelement</type>, - <type>anyarray</type>, or <type>anyenum</>), + <type>anyarray</type>, <type>anynonarray</type>, or <type>anyenum</>), a special parameter <literal>$0</literal> is created. Its data type is the actual return type of the function, as deduced from the actual input types (see <xref diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml index 553b33e1732..de7eed5a6db 100644 --- a/doc/src/sgml/xfunc.sgml +++ b/doc/src/sgml/xfunc.sgml @@ -1,4 +1,4 @@ -<!-- $PostgreSQL: pgsql/doc/src/sgml/xfunc.sgml,v 1.127 2007/04/02 03:49:37 tgl Exp $ --> +<!-- $PostgreSQL: pgsql/doc/src/sgml/xfunc.sgml,v 1.128 2007/06/06 23:00:36 tgl Exp $ --> <sect1 id="xfunc"> <title>User-Defined Functions</title> @@ -718,7 +718,8 @@ SELECT name, listchildren(name) FROM nodes; <para> <acronym>SQL</acronym> functions can be declared to accept and return the polymorphic types <type>anyelement</type>, - <type>anyarray</type>, and <type>anyenum</type>. See <xref + <type>anyarray</type>, <type>anynonarray</type>, and + <type>anyenum</type>. See <xref linkend="extend-types-polymorphic"> for a more detailed explanation of polymorphic functions. Here is a polymorphic function <function>make_array</function> that builds up an array @@ -2831,7 +2832,8 @@ CREATE OR REPLACE FUNCTION retcomposite(IN integer, IN integer, <para> C-language functions can be declared to accept and return the polymorphic types - <type>anyelement</type>, <type>anyarray</type>, and <type>anyenum</type>. + <type>anyelement</type>, <type>anyarray</type>, <type>anynonarray</type>, + and <type>anyenum</type>. See <xref linkend="extend-types-polymorphic"> for a more detailed explanation of polymorphic functions. When function arguments or return types are defined as polymorphic types, the function author cannot know |