@ -1,4 +1,4 @@
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/func.sgml,v 1.56 2001/03/25 18:14:31 tgl Exp $ -->
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/func.sgml,v 1.57 2001/04/20 15:52:33 thomas Exp $ -->
<chapter id="functions">
<chapter id="functions">
<title>Functions and Operators</title>
<title>Functions and Operators</title>
@ -440,15 +440,15 @@
<tbody>
<tbody>
<row>
<row>
<entry>abs(<replaceable>x</replaceable>)</entry>
<entry>abs(<replaceable>x</replaceable>)</entry>
<entry>(same as argument type )</entry>
<entry>(same as x )</entry>
<entry>absolute value</entry>
<entry>absolute value</entry>
<entry>abs(-17.4)</entry>
<entry>abs(-17.4)</entry>
<entry>17.4</entry>
<entry>17.4</entry>
</row>
</row>
<row>
<row>
<entry>cbrt(<type>double precision </type>)</entry>
<entry>cbrt(<type>dp</type>)</entry>
<entry><type>double precision </type></entry>
<entry><type>dp</type></entry>
<entry>cube root</entry>
<entry>cube root</entry>
<entry>cbrt(27.0)</entry>
<entry>cbrt(27.0)</entry>
<entry>3.0</entry>
<entry>3.0</entry>
@ -463,17 +463,17 @@
</row>
</row>
<row>
<row>
<entry>degrees(<type>double precision </type>)</entry>
<entry>degrees(<type>dp</type>)</entry>
<entry><type>double precision </type></entry>
<entry><type>dp</type></entry>
<entry>convert radians to degrees</entry>
<entry>radians to degrees</entry>
<entry>degrees(0.5)</entry>
<entry>degrees(0.5)</entry>
<entry>28.6478897565412</entry>
<entry>28.6478897565412</entry>
</row>
</row>
<row>
<row>
<entry>exp(<type>double precision </type>)</entry>
<entry>exp(<type>dp</type>)</entry>
<entry><type>double precision </type></entry>
<entry><type>dp</type></entry>
<entry>exponential function </entry>
<entry>exponential</entry>
<entry>exp(1.0)</entry>
<entry>exp(1.0)</entry>
<entry>2.71828182845905</entry>
<entry>2.71828182845905</entry>
</row>
</row>
@ -487,25 +487,26 @@
</row>
</row>
<row>
<row>
<entry>ln(<type>double precision </type>)</entry>
<entry>ln(<type>dp</type>)</entry>
<entry><type>double precision </type></entry>
<entry><type>dp</type></entry>
<entry>natural logarithm</entry>
<entry>natural logarithm</entry>
<entry>ln(2.0)</entry>
<entry>ln(2.0)</entry>
<entry>0.693147180559945</entry>
<entry>0.693147180559945</entry>
</row>
</row>
<row>
<row>
<entry>log(<type>double precision </type>)</entry>
<entry>log(<type>dp</type>)</entry>
<entry><type>double precision </type></entry>
<entry><type>dp</type></entry>
<entry>base 10 logarithm</entry>
<entry>base 10 logarithm</entry>
<entry>log(100.0)</entry>
<entry>log(100.0)</entry>
<entry>2.0</entry>
<entry>2.0</entry>
</row>
</row>
<row>
<row>
<entry>log(<parameter>base</parameter> <type>numeric</type>, <parameter>x</parameter> <type>numeric</type>)</entry>
<entry>log(<parameter>b</parameter> <type>numeric</type>,
<parameter>x</parameter> <type>numeric</type>)</entry>
<entry><type>numeric</type></entry>
<entry><type>numeric</type></entry>
<entry>logarithm to specified base </entry>
<entry>logarithm to base <parameter>b</parameter> </entry>
<entry>log(2.0, 64.0)</entry>
<entry>log(2.0, 64.0)</entry>
<entry>6.0</entry>
<entry>6.0</entry>
</row>
</row>
@ -513,55 +514,56 @@
<row>
<row>
<entry>mod(<parameter>y</parameter>, <parameter>x</parameter>)</entry>
<entry>mod(<parameter>y</parameter>, <parameter>x</parameter>)</entry>
<entry>(same as argument types)</entry>
<entry>(same as argument types)</entry>
<entry>remainder (modulo) of the division <parameter>y</parameter>/<parameter>x</parameter></entry>
<entry>remainder of <parameter>y</parameter>/<parameter>x</parameter></entry>
<entry>mod(9,4)</entry>
<entry>mod(9,4)</entry>
<entry>1</entry>
<entry>1</entry>
</row>
</row>
<row>
<row>
<entry>pi()</entry>
<entry>pi()</entry>
<entry><type>double precision </type></entry>
<entry><type>dp</type></entry>
<entry><quote>Pi</quote> constant</entry>
<entry><quote>Pi</quote> constant</entry>
<entry>pi()</entry>
<entry>pi()</entry>
<entry>3.14159265358979</entry>
<entry>3.14159265358979</entry>
</row>
</row>
<row>
<row>
<entry>pow(<type>double precision</type>, <type>double precision</type>)</entry>
<entry>pow(<parameter>e</parameter> <type>dp</type>,
<entry><type>double precision</type></entry>
<parameter>n</parameter> <type>dp</type>)</entry>
<entry>raise a number to the specified exponent</entry>
<entry><type>dp</type></entry>
<entry>raise a number to exponent <parameter>e</parameter></entry>
<entry>pow(9.0, 3.0)</entry>
<entry>pow(9.0, 3.0)</entry>
<entry>729.0</entry>
<entry>729.0</entry>
</row>
</row>
<row>
<row>
<entry>radians(<type>double precision </type>)</entry>
<entry>radians(<type>dp</type>)</entry>
<entry><type>double precision </type></entry>
<entry><type>dp</type></entry>
<entry>convert degrees to radians</entry>
<entry>degrees to radians</entry>
<entry>radians(45.0)</entry>
<entry>radians(45.0)</entry>
<entry>0.785398163397448</entry>
<entry>0.785398163397448</entry>
</row>
</row>
<row>
<row>
<entry>random()</entry>
<entry>random()</entry>
<entry><type>double precision </type></entry>
<entry><type>dp</type></entry>
<entry>a pseudo-random value between 0.0 to 1.0</entry>
<entry>value between 0.0 to 1.0</entry>
<entry>random()</entry>
<entry>random()</entry>
<entry></entry>
<entry></entry>
</row>
</row>
<row>
<row>
<entry>round(<type>double precision </type>)</entry>
<entry>round(<type>dp</type>)</entry>
<entry><type>double precision </type></entry>
<entry><type>dp</type></entry>
<entry>round to nearest integer</entry>
<entry>round to nearest integer</entry>
<entry>round(42.4)</entry>
<entry>round(42.4)</entry>
<entry>42</entry>
<entry>42</entry>
</row>
</row>
<row>
<row>
<entry>round(<parameter>value </parameter> <type>numeric</type>, <parameter>scale </parameter> <type>integer</type>)</entry>
<entry>round(<parameter>v</parameter> <type>numeric</type>, <parameter>s</parameter> <type>integer</type>)</entry>
<entry><type>numeric</type></entry>
<entry><type>numeric</type></entry>
<entry>round to specified number of decimal places</entry>
<entry>round to <parameter>s</parameter> decimal places</entry>
<entry>round(42.4382, 2)</entry>
<entry>round(42.4382, 2)</entry>
<entry>42.44</entry>
<entry>42.44</entry>
</row>
</row>
@ -574,25 +576,25 @@
</row>
</row>
-->
-->
<row>
<row>
<entry>sqrt(<type>double precision </type>)</entry>
<entry>sqrt(<type>dp</type>)</entry>
<entry><type>double precision </type></entry>
<entry><type>dp</type></entry>
<entry>square root</entry>
<entry>square root</entry>
<entry>sqrt(2.0)</entry>
<entry>sqrt(2.0)</entry>
<entry>1.4142135623731</entry>
<entry>1.4142135623731</entry>
</row>
</row>
<row>
<row>
<entry>trunc(<type>double precision </type>)</entry>
<entry>trunc(<type>dp</type>)</entry>
<entry><type>double precision </type></entry>
<entry><type>dp</type></entry>
<entry>truncate ( toward zero) </entry>
<entry>truncate toward zero</entry>
<entry>trunc(42.8)</entry>
<entry>trunc(42.8)</entry>
<entry>42</entry>
<entry>42</entry>
</row>
</row>
<row>
<row>
<entry>trunc(<parameter>value</parameter> < type>numeric</type>, <parameter>scale </parameter> <type>integer</type>)</entry>
<entry>trunc(<type>numeric</type>, <parameter>s</parameter> <type>integer</type>)</entry>
<entry><type>numeric</type></entry>
<entry><type>numeric</type></entry>
<entry>truncate to specified number of decimal places</entry>
<entry>truncate to <parameter>s</parameter> decimal places</entry>
<entry>round(42.4382, 2)</entry>
<entry>round(42.4382, 2)</entry>
<entry>42.43</entry>
<entry>42.43</entry>
</row>
</row>
@ -602,12 +604,16 @@
</table>
</table>
<para>
<para>
In the table above, "<literal>dp</literal>" indicates <type>double precision</type>.
The functions <function>exp</function>, <function>ln</function>,
The functions <function>exp</function>, <function>ln</function>,
<function>log</function>, <function>pow</function>,
<function>log</function>, <function>pow</function>,
<function>round</function> (1 argument), <function>sqrt</function>,
<function>round</function> (1 argument), <function>sqrt</function>,
and <function>trunc</function> (1 argument) are also available for
and <function>trunc</function> (1 argument) are also available for
the type <type>numeric</type> in place of <type>double
the type <type>numeric</type> in place of <type>double
precision</type>. Many of these functions are implemented on top
precision</type>.
Functions returning a <type>numeric</type> result take
<type>numeric</type> input arguments, unless otherwise specified.
Many of these functions are implemented on top
of the host system's C library and behavior in boundary cases could
of the host system's C library and behavior in boundary cases could
therefore vary depending on the operating system.
therefore vary depending on the operating system.
</para>
</para>
@ -800,7 +806,7 @@
<thead>
<thead>
<row>
<row>
<entry>Function</entry>
<entry>Function</entry>
<entry>Return t ype</entry>
<entry>Return T ype</entry>
<entry>Description</entry>
<entry>Description</entry>
<entry>Example</entry>
<entry>Example</entry>
<entry>Result</entry>
<entry>Result</entry>
@ -840,8 +846,8 @@
<entry>initcap(<type>text</type>)</entry>
<entry>initcap(<type>text</type>)</entry>
<entry><type>text</type></entry>
<entry><type>text</type></entry>
<entry>Converts first letter of each word (whitespace separated) to upper case.</entry>
<entry>Converts first letter of each word (whitespace separated) to upper case.</entry>
<entry>initcap('hello thomas')</entry>
<entry>initcap('hi thomas')</entry>
<entry>Hello Thomas</entry>
<entry>Hi Thomas</entry>
</row>
</row>
<row>
<row>
@ -1362,9 +1368,14 @@
or bounded repetitions are nested. An RE like, say,
or bounded repetitions are nested. An RE like, say,
<literal>((((a{1,100}){1,100}){1,100}){1,100}){1,100}</literal>
<literal>((((a{1,100}){1,100}){1,100}){1,100}){1,100}</literal>
will (eventually) run almost any existing machine out of swap
will (eventually) run almost any existing machine out of swap
space.<footnote><para>This was written in 1994, mind you. The
space.
numbers have probably changed, but the problem
<footnote>
persists.</para></footnote>
<para>
This was written in 1994, mind you. The
numbers have probably changed, but the problem
persists.
</para>
</footnote>
</para>
</para>
<!-- end re_format.7 man page -->
<!-- end re_format.7 man page -->
</sect2>
</sect2>
@ -2026,8 +2037,8 @@
<entry><literal>'Good number: 485'</literal></entry>
<entry><literal>'Good number: 485'</literal></entry>
</row>
</row>
<row>
<row>
<entry>to_char(485.8,'"Pre-decimal :"999" Post-decimal :" .999')</entry>
<entry>to_char(485.8,'"Pre:"999" Post:" .999')</entry>
<entry><literal>'Pre-decimal : 485 Post-decimal : .800'</literal></entry>
<entry><literal>'Pre: 485 Post: .800'</literal></entry>
</row>
</row>
<row>
<row>
<entry>to_char(12,'99V999')</entry>
<entry>to_char(12,'99V999')</entry>
@ -2075,15 +2086,10 @@
</thead>
</thead>
<tbody>
<tbody>
<![IGNORE[
<!--
These two functions don't seem to do what it says here, or anything
reasonable at all for that matter.
-->
<row>
<row>
<entry>age(timestamp)</entry>
<entry>age(timestamp)</entry>
<entry>interval</entry>
<entry>interval</entry>
<entry>Subtract argument from curren t date, preserve years and m onths and days </entry>
<entry>Subtract from today</entry>
<entry>age(timestamp '1957-06-13')</entry>
<entry>age(timestamp '1957-06-13')</entry>
<entry>43 years 8 mons 3 days</entry>
<entry>43 years 8 mons 3 days</entry>
</row>
</row>
@ -2091,17 +2097,15 @@ reasonable at all for that matter.
<row>
<row>
<entry>age(timestamp, timestamp)</entry>
<entry>age(timestamp, timestamp)</entry>
<entry>interval</entry>
<entry>interval</entry>
<entry>preserve months and year s</entry>
<entry>Subtract argument s</entry>
<entry>age('now ', timestamp '1957-06-13')</entry>
<entry>age('2001-04-10 ', timestamp '1957-06-13')</entry>
<entry></entry>
<entry>43 years 9 mons 27 days </entry>
</row>
</row>
]]>
<row>
<row>
<entry>current_date</entry>
<entry>current_date</entry>
<entry>date</entry>
<entry>date</entry>
<entry>
<entry>Today's date; see <link
returns current date; see also <link
linkend="functions-datetime-current">below</link>
linkend="functions-datetime-current">below</link>
</entry>
</entry>
<entry></entry>
<entry></entry>
@ -2111,8 +2115,7 @@ reasonable at all for that matter.
<row>
<row>
<entry>current_time</entry>
<entry>current_time</entry>
<entry>time</entry>
<entry>time</entry>
<entry>
<entry>Time of day; see <link
returns current time (of day); see also <link
linkend="functions-datetime-current">below</link>
linkend="functions-datetime-current">below</link>
</entry>
</entry>
<entry></entry>
<entry></entry>
@ -2122,8 +2125,7 @@ reasonable at all for that matter.
<row>
<row>
<entry>current_timestamp</entry>
<entry>current_timestamp</entry>
<entry>timestamp</entry>
<entry>timestamp</entry>
<entry>
<entry>date and time; see also <link
returns current date and time; see also <link
linkend="functions-datetime-current">below</link>
linkend="functions-datetime-current">below</link>
</entry>
</entry>
<entry></entry>
<entry></entry>
@ -2133,8 +2135,7 @@ reasonable at all for that matter.
<row>
<row>
<entry>date_part(text, timestamp)</entry>
<entry>date_part(text, timestamp)</entry>
<entry>double precision</entry>
<entry>double precision</entry>
<entry>
<entry>Get subfield (equivalent to
extract subfield from date/time value (equivalent to
<function>extract</function>); see also <link
<function>extract</function>); see also <link
linkend="functions-datetime-datepart">below</link>
linkend="functions-datetime-datepart">below</link>
</entry>
</entry>
@ -2145,8 +2146,7 @@ reasonable at all for that matter.
<row>
<row>
<entry>date_part(text, interval)</entry>
<entry>date_part(text, interval)</entry>
<entry>double precision</entry>
<entry>double precision</entry>
<entry>
<entry>Get subfield (equivalent to
extract subfield from interval value (equivalent to
<function>extract</function>); see also <link
<function>extract</function>); see also <link
linkend="functions-datetime-datepart">below</link>
linkend="functions-datetime-datepart">below</link>
</entry>
</entry>
@ -2157,8 +2157,7 @@ reasonable at all for that matter.
<row>
<row>
<entry>date_trunc(text, timestamp)</entry>
<entry>date_trunc(text, timestamp)</entry>
<entry>timestamp</entry>
<entry>timestamp</entry>
<entry>
<entry>Truncate to specified precision; see also <link
truncate date to specified precision; see also <link
linkend="functions-datetime-trunc">below</link>
linkend="functions-datetime-trunc">below</link>
</entry>
</entry>
<entry>date_trunc('hour', timestamp '2001-02-16 20:38:40')</entry>
<entry>date_trunc('hour', timestamp '2001-02-16 20:38:40')</entry>
@ -2166,10 +2165,9 @@ reasonable at all for that matter.
</row>
</row>
<row>
<row>
<entry>extract(identifier from timestamp)</entry>
<entry>extract(<parameter>field</parameter> from timestamp)</entry>
<entry>double precision</entry>
<entry>double precision</entry>
<entry>
<entry>Get subfield; see also <link
extract subfield from date/time value; see also <link
linkend="functions-datetime-extract">below</link>
linkend="functions-datetime-extract">below</link>
</entry>
</entry>
<entry>extract(hour from timestamp '2001-02-16 20:38:40')</entry>
<entry>extract(hour from timestamp '2001-02-16 20:38:40')</entry>
@ -2177,10 +2175,9 @@ reasonable at all for that matter.
</row>
</row>
<row>
<row>
<entry>extract(identifier from interval)</entry>
<entry>extract(<parameter>field</parameter> from interval)</entry>
<entry>double precision</entry>
<entry>double precision</entry>
<entry>
<entry>Get subfield; see also <link
extract subfield from interval value; see also <link
linkend="functions-datetime-extract">below</link>
linkend="functions-datetime-extract">below</link>
</entry>
</entry>
<entry>extract(month from interval '2 years 3 months')</entry>
<entry>extract(month from interval '2 years 3 months')</entry>
@ -2190,7 +2187,7 @@ reasonable at all for that matter.
<row>
<row>
<entry>isfinite(timestamp)</entry>
<entry>isfinite(timestamp)</entry>
<entry>boolean</entry>
<entry>boolean</entry>
<entry>Returns true if the time stamp is finite (neither invalid nor infinity)</entry>
<entry>Test for finite time stamp (neither invalid nor infinity)</entry>
<entry>isfinite(timestamp '2001-02-16 21:28:30')</entry>
<entry>isfinite(timestamp '2001-02-16 21:28:30')</entry>
<entry>true</entry>
<entry>true</entry>
</row>
</row>
@ -2198,7 +2195,7 @@ reasonable at all for that matter.
<row>
<row>
<entry>isfinite(interval)</entry>
<entry>isfinite(interval)</entry>
<entry>boolean</entry>
<entry>boolean</entry>
<entry>Returns true if the interval is finite in length </entry>
<entry>Test for finite interval </entry>
<entry>isfinite(interval '4 hours')</entry>
<entry>isfinite(interval '4 hours')</entry>
<entry>true</entry>
<entry>true</entry>
</row>
</row>
@ -2206,8 +2203,7 @@ reasonable at all for that matter.
<row>
<row>
<entry>now()</entry>
<entry>now()</entry>
<entry>timestamp</entry>
<entry>timestamp</entry>
<entry>
<entry>Current date and time (equivalent to
returns current date and time (equivalent to
<function>current_timestamp</function>); see also <link
<function>current_timestamp</function>); see also <link
linkend="functions-datetime-current">below</link>
linkend="functions-datetime-current">below</link>
</entry>
</entry>
@ -2218,8 +2214,7 @@ reasonable at all for that matter.
<row>
<row>
<entry>timeofday()</entry>
<entry>timeofday()</entry>
<entry>text</entry>
<entry>text</entry>
<entry>
<entry>High-precision date and time; see also <link
returns high-precision date and time; see also <link
linkend="functions-datetime-current">below</link>
linkend="functions-datetime-current">below</link>
</entry>
</entry>
<entry>timeofday()</entry>
<entry>timeofday()</entry>
@ -2229,7 +2224,7 @@ reasonable at all for that matter.
<row>
<row>
<entry>timestamp(date)</entry>
<entry>timestamp(date)</entry>
<entry>timestamp</entry>
<entry>timestamp</entry>
<entry>convert d ate to timestamp</entry>
<entry>D ate to timestamp</entry>
<entry>timestamp(date '2000-12-25')</entry>
<entry>timestamp(date '2000-12-25')</entry>
<entry>2000-12-25 00:00:00</entry>
<entry>2000-12-25 00:00:00</entry>
</row>
</row>
@ -2237,7 +2232,7 @@ reasonable at all for that matter.
<row>
<row>
<entry>timestamp(date, time)</entry>
<entry>timestamp(date, time)</entry>
<entry>timestamp</entry>
<entry>timestamp</entry>
<entry>combine date and time in to a timestamp</entry>
<entry>Date and time to a timestamp</entry>
<entry>timestamp(date '1998-02-24',time '23:07')</entry>
<entry>timestamp(date '1998-02-24',time '23:07')</entry>
<entry>1998-02-24 23:07:00</entry>
<entry>1998-02-24 23:07:00</entry>
</row>
</row>
@ -2260,8 +2255,8 @@ EXTRACT (<replaceable>field</replaceable> FROM <replaceable>source</replaceable>
evaluates to type <type>timestamp</type> or <type>interval</type>.
evaluates to type <type>timestamp</type> or <type>interval</type>.
(Expressions of type <type>date</type> or <type>time</type> will
(Expressions of type <type>date</type> or <type>time</type> will
be cast to <type>timestamp</type> and can therefore be used as
be cast to <type>timestamp</type> and can therefore be used as
well.) <replaceable>field</replaceable> is an identifier (not a
well.) <replaceable>field</replaceable> is an identifier or
string!) that selects what field to extract from the source value.
string that selects what field to extract from the source value.
The <function>extract</function> function returns values of type
The <function>extract</function> function returns values of type
<type>double precision</type>.
<type>double precision</type>.
The following are valid values:
The following are valid values:
@ -2283,7 +2278,9 @@ SELECT EXTRACT(CENTURY FROM TIMESTAMP '2001-02-16 20:38:40');
</informalexample>
</informalexample>
<para>
<para>
Note that this is not really the century that the date is in.
Note that the result for the century field is simply the year field
divided by 100, and not the conventional definition which puts most
years in the 1900's in the twentieth century.
</para>
</para>
</listitem>
</listitem>
</varlistentry>
</varlistentry>
@ -2422,7 +2419,9 @@ SELECT EXTRACT(MILLENNIUM FROM TIMESTAMP '2001-02-16 20:38:40');
</informalexample>
</informalexample>
<para>
<para>
Note that this is not really the millennium that the date is in.
Note that the result for the millennium field is simply the year field
divided by 1000, and not the conventional definition which puts
years in the 1900's in the second millennium.
</para>
</para>
</listitem>
</listitem>
</varlistentry>
</varlistentry>
@ -2577,8 +2576,8 @@ tz_minute
<anchor id="functions-datetime-datepart">
<anchor id="functions-datetime-datepart">
<para>
<para>
The <function>date_part</function> function is the traditional
The <function>date_part</function> function is modeled on the traditional
<productname>Post gres</productname> equivalent to the
<productname>In gres</productname> equivalent to the
<acronym>SQL</acronym>-function <function>extract</function>:
<acronym>SQL</acronym>-function <function>extract</function>:
<synopsis>
<synopsis>
date_part('<replaceable>field</replaceable>', <replaceable>source</replaceable>)
date_part('<replaceable>field</replaceable>', <replaceable>source</replaceable>)
@ -3459,7 +3458,7 @@ SELECT NULLIF(value, '(none)') ...
<title>Miscellaneous Functions</>
<title>Miscellaneous Functions</>
<tgroup cols="3">
<tgroup cols="3">
<thead>
<thead>
<row><entry>Name</> <entry>Return t ype</> <entry>Description</></row>
<row><entry>Name</> <entry>Return T ype</> <entry>Description</></row>
</thead>
</thead>
<tbody>
<tbody>