diff options
Diffstat (limited to 'doc/src/sgml/func.sgml')
| -rw-r--r-- | doc/src/sgml/func.sgml | 83 |
1 files changed, 82 insertions, 1 deletions
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index db7cd1d1f3..0baf152594 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.372 2007/04/01 09:00:24 petere Exp $ --> +<!-- $PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.373 2007/04/02 03:49:36 tgl Exp $ --> <chapter id="functions"> <title>Functions and Operators</title> @@ -6646,6 +6646,87 @@ SELECT pg_sleep(1.5); </sect1> + <sect1 id="functions-enum"> + <title>Enum Support Functions</title> + + <para> + For enum types (described in <xref linkend="datatype-enum">), + there are several functions that allow cleaner programming without + hard-coding particular values of an enum type. + These are listed in <xref linkend="functions-enum-table">. The examples + assume an enum type created as: + +<programlisting> +CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple'); +</programlisting> + + </para> + + <table id="functions-enum-table"> + <title>Enum Support Functions</title> + <tgroup cols="4"> + <thead> + <row> + <entry>Function</entry> + <entry>Description</entry> + <entry>Example</entry> + <entry>Example Result</entry> + </row> + </thead> + <tbody> + <row> + <entry><literal>enum_first(anyenum)</literal></entry> + <entry>Returns the first value of the input enum type</entry> + <entry><literal>enum_first(null::rainbow)</literal></entry> + <entry><literal>red</literal></entry> + </row> + <row> + <entry><literal>enum_last(anyenum)</literal></entry> + <entry>Returns the last value of the input enum type</entry> + <entry><literal>enum_last(null::rainbow)</literal></entry> + <entry><literal>purple</literal></entry> + </row> + <row> + <entry><literal>enum_range(anyenum)</literal></entry> + <entry>Returns all values of the input enum type in an ordered array</entry> + <entry><literal>enum_range(null::rainbow)</literal></entry> + <entry><literal>{red,orange,yellow,green,blue,purple}</literal></entry> + </row> + <row> + <entry morerows="2"><literal>enum_range(anyenum, anyenum)</literal></entry> + <entry morerows="2"> + Returns the range between the two given enum values, as an ordered + array. The values must be from the same enum type. If the first + parameter is null, the result will start with the first value of + the enum type. + If the second parameter is null, the result will end with the last + value of the enum type. + </entry> + <entry><literal>enum_range('orange'::rainbow, 'green'::rainbow)</literal></entry> + <entry><literal>{orange,yellow,green}</literal></entry> + </row> + <row> + <entry><literal>enum_range(NULL, 'green'::rainbow)</literal></entry> + <entry><literal>{red,orange,yellow,green}</literal></entry> + </row> + <row> + <entry><literal>enum_range('orange'::rainbow, NULL)</literal></entry> + <entry><literal>{orange,yellow,green,blue,purple}</literal></entry> + </row> + </tbody> + </tgroup> + </table> + + <para> + Notice that except for the two-argument form of <function>enum_range</>, + these functions disregard the specific value passed to them; they care + only about its declared datatype. Either NULL or a specific value of + the type can be passed, with the same result. It is more common to + apply these functions to a table column or function argument than to + a hardwired type name as suggested by the examples. + </para> + </sect1> + <sect1 id="functions-geometry"> <title>Geometric Functions and Operators</title> |