diff options
Diffstat (limited to 'doc/src/sgml/func.sgml')
| -rw-r--r-- | doc/src/sgml/func.sgml | 111 |
1 files changed, 46 insertions, 65 deletions
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index 2de07c04ae8..96fc4ea6989 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -1,5 +1,5 @@ <!-- -$PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.231 2004/12/21 01:02:28 momjian Exp $ +$PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.232 2004/12/23 23:07:38 tgl Exp $ PostgreSQL documentation --> @@ -1347,7 +1347,8 @@ PostgreSQL documentation <footnote> <para> The <function>to_ascii</function> function supports conversion from - <literal>LATIN1</>, <literal>LATIN2</>, and <literal>WIN1250</> only. + <literal>LATIN1</>, <literal>LATIN2</>, <literal>LATIN9</>, + and <literal>WIN1250</> encodings only. </para> </footnote> </entry> @@ -2483,11 +2484,11 @@ cast(-44 as bit(12)) <lineannotation>111111010100</lineannotation> There are three separate approaches to pattern matching provided by <productname>PostgreSQL</productname>: the traditional <acronym>SQL</acronym> <function>LIKE</function> operator, the - more recent <literal>>SIMILAR TO</literal> operator (since + more recent <function>SIMILAR TO</function> operator (added in SQL:1999), and <acronym>POSIX</acronym>-style regular expressions. Additionally, a pattern matching function, <function>substring</function>, is available, using either - <literal>SIMILAR TO</literal>-style or POSIX-style regular + <function>SIMILAR TO</function>-style or POSIX-style regular expressions. </para> @@ -2544,7 +2545,7 @@ cast(-44 as bit(12)) <lineannotation>111111010100</lineannotation> <para> <function>LIKE</function> pattern matches always cover the entire - string. To match a pattern anywhere within a string, the + string. To match a sequence anywhere within a string, the pattern must therefore start and end with a percent sign. </para> @@ -2578,7 +2579,7 @@ cast(-44 as bit(12)) <lineannotation>111111010100</lineannotation> <para> The key word <token>ILIKE</token> can be used instead of - <token>LIKE</token> to make the match case insensitive according + <token>LIKE</token> to make the match case-insensitive according to the active locale. This is not in the <acronym>SQL</acronym> standard but is a <productname>PostgreSQL</productname> extension. </para> @@ -2818,9 +2819,11 @@ substring('foobar' from '#"o_b#"%' for '#') <lineannotation>NULL</lineannotat pattern. But if the pattern contains any parentheses, the portion of the text that matched the first parenthesized subexpression (the one whose left parenthesis comes first) is - returned. You can always put parentheses around the whole expression + returned. You can put parentheses around the whole expression if you want to use parentheses within it without triggering this - exception. Also see the non-capturing parentheses described below. + exception. If you need parentheses in the pattern before the + subexpression you want to extract, see the non-capturing parentheses + described below. </para> <para> @@ -3073,7 +3076,7 @@ substring('foobar' from 'o(.)b') <lineannotation>o</lineannotation> <para> The forms using <literal>{</><replaceable>...</><literal>}</> - are known as <firstterm>bound</>s. + are known as <firstterm>bounds</>. The numbers <replaceable>m</> and <replaceable>n</> within a bound are unsigned decimal integers with permissible values from 0 to 255 inclusive. </para> @@ -3603,9 +3606,10 @@ substring('foobar' from 'o(.)b') <lineannotation>o</lineannotation> Normally the flavor of RE being used is determined by <varname>regex_flavor</>. However, this can be overridden by a <firstterm>director</> prefix. - If an RE of any flavor begins with <literal>***:</>, - the rest of the RE is taken as an ARE. - If an RE of any flavor begins with <literal>***=</>, + If an RE begins with <literal>***:</>, + the rest of the RE is taken as an ARE regardless of + <varname>regex_flavor</>. + If an RE begins with <literal>***=</>, the rest of the RE is taken to be a literal string, with all characters considered ordinary characters. </para> @@ -3703,8 +3707,8 @@ substring('foobar' from 'o(.)b') <lineannotation>o</lineannotation> <para> Embedded options take effect at the <literal>)</> terminating the sequence. - They are available only at the start of an ARE, - and may not be used later within it. + They may appear only at the start of an ARE (after the + <literal>***:</> director if any). </para> <para> @@ -3732,13 +3736,13 @@ substring('foobar' from 'o(.)b') <lineannotation>o</lineannotation> </listitem> <listitem> <para> - white space and comments are illegal within multi-character symbols, - like the ARE <literal>(?:</> or the BRE <literal>\(</> + white space and comments cannot appear within multi-character symbols, + such as <literal>(?:</> </para> </listitem> </itemizedlist> - Expanded-syntax white-space characters are blank, tab, newline, and + For this purpose, white-space characters are blank, tab, newline, and any character that belongs to the <replaceable>space</> character class. </para> @@ -4330,7 +4334,7 @@ substring('foobar' from 'o(.)b') <lineannotation>o</lineannotation> </table> <para> - Usage notes for the date/time formatting: + Usage notes for date/time formatting: <itemizedlist> <listitem> @@ -4506,7 +4510,7 @@ substring('foobar' from 'o(.)b') <lineannotation>o</lineannotation> </table> <para> - Usage notes for the numeric formatting: + Usage notes for numeric formatting: <itemizedlist> <listitem> @@ -5068,10 +5072,10 @@ EXTRACT (<replaceable>field</replaceable> FROM <replaceable>source</replaceable> <para> The <function>extract</function> function retrieves subfields - from date/time values, such as year or hour. - <replaceable>source</replaceable> is a value expression that - evaluates to type <type>timestamp</type> or <type>interval</type>. - (Expressions of type <type>date</type> or <type>time</type> will + such as year or hour from date/time values. + <replaceable>source</replaceable> must be a value expression of + type <type>timestamp</type>, <type>time</type>, or <type>interval</type>. + (Expressions of type <type>date</type> will be cast to <type>timestamp</type> and can therefore be used as well.) <replaceable>field</replaceable> is an identifier or string that selects what field to extract from the source value. @@ -5699,7 +5703,7 @@ SELECT TIMESTAMP 'now'; </programlisting> </para> - <note> + <tip> <para> You do not want to use the third form when specifying a <literal>DEFAULT</> clause while creating a table. The system will convert <literal>now</literal> @@ -5710,7 +5714,7 @@ SELECT TIMESTAMP 'now'; because they are function calls. Thus they will give the desired behavior of defaulting to the time of row insertion. </para> - </note> + </tip> </sect2> </sect1> @@ -6803,7 +6807,7 @@ SELECT NULLIF(value, '(none)') ... <para> <xref linkend="array-functions-table"> shows the functions available for use with array types. See <xref linkend="arrays"> - for more discussion and examples for the use of these functions. + for more discussion and examples of the use of these functions. </para> <table id="array-functions-table"> @@ -6827,10 +6831,7 @@ SELECT NULLIF(value, '(none)') ... </literal> </entry> <entry><type>anyarray</type></entry> - <entry> - concatenate two arrays, returning <literal>NULL</literal> - for <literal>NULL</literal> inputs - </entry> + <entry>concatenate two arrays</entry> <entry><literal>array_cat(ARRAY[1,2,3], ARRAY[4,5])</literal></entry> <entry><literal>{1,2,3,4,5}</literal></entry> </row> @@ -6842,10 +6843,7 @@ SELECT NULLIF(value, '(none)') ... </literal> </entry> <entry><type>anyarray</type></entry> - <entry> - append an element to the end of an array, returning - <literal>NULL</literal> for <literal>NULL</literal> inputs - </entry> + <entry>append an element to the end of an array</entry> <entry><literal>array_append(ARRAY[1,2], 3)</literal></entry> <entry><literal>{1,2,3}</literal></entry> </row> @@ -6857,10 +6855,7 @@ SELECT NULLIF(value, '(none)') ... </literal> </entry> <entry><type>anyarray</type></entry> - <entry> - append an element to the beginning of an array, returning - <literal>NULL</literal> for <literal>NULL</literal> inputs - </entry> + <entry>append an element to the beginning of an array</entry> <entry><literal>array_prepend(1, ARRAY[2,3])</literal></entry> <entry><literal>{1,2,3}</literal></entry> </row> @@ -6872,10 +6867,7 @@ SELECT NULLIF(value, '(none)') ... </literal> </entry> <entry><type>text</type></entry> - <entry> - returns a text representation of array dimension lower and upper bounds, - generating an ERROR for <literal>NULL</literal> inputs - </entry> + <entry>returns a text representation of array's dimensions</entry> <entry><literal>array_dims(array[[1,2,3], [4,5,6]])</literal></entry> <entry><literal>[1:2][1:3]</literal></entry> </row> @@ -6887,10 +6879,7 @@ SELECT NULLIF(value, '(none)') ... </literal> </entry> <entry><type>integer</type></entry> - <entry> - returns lower bound of the requested array dimension, returning - <literal>NULL</literal> for <literal>NULL</literal> inputs - </entry> + <entry>returns lower bound of the requested array dimension</entry> <entry><literal>array_lower(array_prepend(0, ARRAY[1,2,3]), 1)</literal></entry> <entry><literal>0</literal></entry> </row> @@ -6902,10 +6891,7 @@ SELECT NULLIF(value, '(none)') ... </literal> </entry> <entry><type>integer</type></entry> - <entry> - returns upper bound of the requested array dimension, returning - <literal>NULL</literal> for <literal>NULL</literal> inputs - </entry> + <entry>returns upper bound of the requested array dimension</entry> <entry><literal>array_upper(ARRAY[1,2,3,4], 1)</literal></entry> <entry><literal>4</literal></entry> </row> @@ -6917,10 +6903,7 @@ SELECT NULLIF(value, '(none)') ... </literal> </entry> <entry><type>text</type></entry> - <entry> - concatenates array elements using provided delimiter, returning - <literal>NULL</literal> for <literal>NULL</literal> inputs - </entry> + <entry>concatenates array elements using provided delimiter</entry> <entry><literal>array_to_string(array[1, 2, 3], '~^~')</literal></entry> <entry><literal>1~^~2~^~3</literal></entry> </row> @@ -6932,10 +6915,7 @@ SELECT NULLIF(value, '(none)') ... </literal> </entry> <entry><type>text[]</type></entry> - <entry> - splits string into array elements using provided delimiter, returning - <literal>NULL</literal> for <literal>NULL</literal> inputs - </entry> + <entry>splits string into array elements using provided delimiter</entry> <entry><literal>string_to_array( 'xx~^~yy~^~zz', '~^~')</literal></entry> <entry><literal>{xx,yy,zz}</literal></entry> </row> @@ -7181,7 +7161,7 @@ SELECT NULLIF(value, '(none)') ... It should be noted that except for <function>count</function>, these functions return a null value when no rows are selected. In particular, <function>sum</function> of no rows returns null, not - zero as one might expect. The function <function>coalesce</function> may be + zero as one might expect. The <function>coalesce</function> function may be used to substitute zero for null when necessary. </para> @@ -8045,9 +8025,10 @@ select current_date + s.a as dates from generate_series(0,14,7) as s(a); </indexterm> <para> - The <function>session_user</function> is the user that initiated a - database connection; it is fixed for the duration of that - connection. The <function>current_user</function> is the user identifier + The <function>session_user</function> is normally the user who initiated + the current database connection; but superusers can change this setting + with <xref linkend="sql-set-session-authorization">. + The <function>current_user</function> is the user identifier that is applicable for permission checking. Normally, it is equal to the session user, but it changes during the execution of functions with the attribute <literal>SECURITY DEFINER</literal>. @@ -8106,8 +8087,8 @@ SET search_path TO <replaceable>schema</> <optional>, <replaceable>schema</>, .. <function>inet_server_addr</function> returns the IP address on which the server accepted the current connection, and <function>inet_server_port</function> returns the port number. - All these functions return NULL if the connection is via a Unix-domain - socket. + All these functions return NULL if the current connection is via a + Unix-domain socket. </para> <indexterm zone="functions-info"> @@ -8325,7 +8306,7 @@ SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute'); </para> <para> - To evaluate whether a user holds a grant option on the privilege, + To test whether a user holds a grant option on the privilege, append <literal> WITH GRANT OPTION</literal> to the privilege key word; for example <literal>'UPDATE WITH GRANT OPTION'</literal>. </para> |