Skip to content

P
Postgres FD Implementation
Commit 1ec42696 authored by Tom Lane's avatar Tom Lane
Browse files
Options

Doc: update sections 9.7 and 9.8 for new function table layout. 

Also some mop-up in section 9.9.
parent 079ac29d
Hide whitespace changes
Inline Side-by-side
Showing with 203 additions and 146 deletions
doc/src/sgml/func.sgml
View file @ 1ec42696
...@@ -3975,7 +3975,7 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three'); ...@@ -3975,7 +3975,7 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three');
This section describes functions and operators for examining and This section describes functions and operators for examining and
manipulating bit strings, that is values of the types manipulating bit strings, that is values of the types
<type>bit</type> and <type>bit varying</type>. (While only <type>bit</type> and <type>bit varying</type>. (While only
type <type>bit</type> is mentioned in the tables, values of type <type>bit</type> is mentioned in these tables, values of
type <type>bit varying</type> can be used interchangeably.) type <type>bit varying</type> can be used interchangeably.)
Bit strings support the usual comparison operators shown in Bit strings support the usual comparison operators shown in
<xref linkend="functions-comparison-op-table"/>, as well as the <xref linkend="functions-comparison-op-table"/>, as well as the
...@@ -4670,38 +4670,62 @@ substring('foobar' from '#"o_b#"%' for '#') <lineannotation>NULL</lineannotat ...@@ -4670,38 +4670,62 @@ substring('foobar' from '#"o_b#"%' for '#') <lineannotation>NULL</lineannotat
<table id="functions-posix-table"> <table id="functions-posix-table">
<title>Regular Expression Match Operators</title> <title>Regular Expression Match Operators</title>
<tgroup cols="3"> <tgroup cols="1">
<thead> <thead>
<row> <row>
<entry>Operator</entry> <entry role="functableentry">
<entry>Description</entry> Operator<?br?>Description<?br?>Example(s)
<entry>Example</entry> </entry>
</row> </row>
</thead> </thead>
<tbody> <tbody>
<row> <row>
<entry> <literal>~</literal> </entry> <entry role="functableentry">
<entry>Matches regular expression, case sensitive</entry> <type>text</type> <literal>~</literal> <type>text</type>
<entry><literal>'thomas' ~ '.*thomas.*'</literal></entry> <returnvalue>boolean</returnvalue>
<?br?>
String matches regular expression, case sensitively
<?br?>
<literal>'thomas' ~ '.*thom.*'</literal>
<returnvalue>t</returnvalue>
</entry>
</row> </row>
<row> <row>
<entry> <literal>~*</literal> </entry> <entry role="functableentry">
<entry>Matches regular expression, case insensitive</entry> <type>text</type> <literal>~*</literal> <type>text</type>
<entry><literal>'thomas' ~* '.*Thomas.*'</literal></entry> <returnvalue>boolean</returnvalue>
<?br?>
String matches regular expression, case insensitively
<?br?>
<literal>'thomas' ~* '.*Thom.*'</literal>
<returnvalue>t</returnvalue>
</entry>
</row> </row>
<row> <row>
<entry> <literal>!~</literal> </entry> <entry role="functableentry">
<entry>Does not match regular expression, case sensitive</entry> <type>text</type> <literal>!~</literal> <type>text</type>
<entry><literal>'thomas' !~ '.*Thomas.*'</literal></entry> <returnvalue>boolean</returnvalue>
<?br?>
String does not match regular expression, case sensitively
<?br?>
<literal>'thomas' !~ '.*thomas.*'</literal>
<returnvalue>f</returnvalue>
</entry>
</row> </row>
<row> <row>
<entry> <literal>!~*</literal> </entry> <entry role="functableentry">
<entry>Does not match regular expression, case insensitive</entry> <type>text</type> <literal>!~*</literal> <type>text</type>
<entry><literal>'thomas' !~* '.*vadim.*'</literal></entry> <returnvalue>boolean</returnvalue>
<?br?>
String does not match regular expression, case insensitively
<?br?>
<literal>'thomas' !~* '.*vadim.*'</literal>
<returnvalue>t</returnvalue>
</entry>
</row> </row>
</tbody> </tbody>
</tgroup> </tgroup>
...@@ -6417,97 +6441,114 @@ SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}'); ...@@ -6417,97 +6441,114 @@ SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}');
template that defines the output or input format. template that defines the output or input format.
</para> </para>
<table id="functions-formatting-table"> <table id="functions-formatting-table">
<title>Formatting Functions</title> <title>Formatting Functions</title>
<tgroup cols="4"> <tgroup cols="1">
<thead> <thead>
<row> <row>
<entry>Function</entry> <entry role="functableentry">
<entry>Return Type</entry> Function<?br?>Description<?br?>Example(s)
<entry>Description</entry> </entry>
<entry>Example</entry> </row>
</row> </thead>
</thead>
<tbody>
<row>
<entry>
<indexterm>
<primary>to_char</primary>
</indexterm>
<literal><function>to_char(<type>timestamp</type>, <type>text</type>)</function></literal>
</entry>
<entry><type>text</type></entry>
<entry>convert time stamp to string</entry>
<entry><literal>to_char(current_timestamp, 'HH12:MI:SS')</literal></entry>
</row>
<row>
<entry><literal><function>to_char(<type>interval</type>, <type>text</type>)</function></literal></entry>
<entry><type>text</type></entry>
<entry>convert interval to string</entry>
<entry><literal>to_char(interval '15h&nbsp;2m&nbsp;12s', 'HH24:MI:SS')</literal></entry>
</row>
<row>
<entry><literal><function>to_char(<type>int</type>, <type>text</type>)</function></literal></entry>
<entry><type>text</type></entry>
<entry>convert integer to string</entry>
<entry><literal>to_char(125, '999')</literal></entry>
</row>
<row>
<entry><literal><function>to_char</function>(<type>double precision</type>,
<type>text</type>)</literal></entry>
<entry><type>text</type></entry>
<entry>convert real/double precision to string</entry>
<entry><literal>to_char(125.8::real, '999D9')</literal></entry>
</row>
<row>
<entry><literal><function>to_char(<type>numeric</type>, <type>text</type>)</function></literal></entry>
<entry><type>text</type></entry>
<entry>convert numeric to string</entry>
<entry><literal>to_char(-125.8, '999D99S')</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>to_date</primary>
</indexterm>
<literal><function>to_date(<type>text</type>, <type>text</type>)</function></literal>
</entry>
<entry><type>date</type></entry>
<entry>convert string to date</entry>
<entry><literal>to_date('05&nbsp;Dec&nbsp;2000', 'DD&nbsp;Mon&nbsp;YYYY')</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>to_number</primary>
</indexterm>
<literal><function>to_number(<type>text</type>, <type>text</type>)</function></literal>
</entry>
<entry><type>numeric</type></entry>
<entry>convert string to numeric</entry>
<entry><literal>to_number('12,454.8-', '99G999D9S')</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>to_timestamp</primary>
</indexterm>
<literal><function>to_timestamp(<type>text</type>, <type>text</type>)</function></literal>
</entry>
<entry><type>timestamp with time zone</type></entry>
<entry>convert string to time stamp</entry>
<entry><literal>to_timestamp('05&nbsp;Dec&nbsp;2000', 'DD&nbsp;Mon&nbsp;YYYY')</literal></entry>
</row>
</tbody>
</tgroup>
</table>
<note> <tbody>
<para> <row>
There is also a single-argument <function>to_timestamp</function> <entry role="functableentry">
function; see <xref linkend="functions-datetime-table"/>. <indexterm>
</para> <primary>to_char</primary>
</note> </indexterm>
<function>to_char</function> ( <type>timestamp</type> <optional><literal>with time zone</literal></optional>, <type>text</type> )
<returnvalue>text</returnvalue>
<?br?>
Converts time stamp to string according to the given format.
<?br?>
<literal>to_char(timestamp '2002-04-20 17:31:12.66', 'HH12:MI:SS')</literal>
<returnvalue>05:31:12</returnvalue>
</entry>
</row>
<row>
<entry role="functableentry">
<function>to_char</function> ( <type>interval</type>, <type>text</type> )
<returnvalue>text</returnvalue>
<?br?>
Converts interval to string according to the given format.
<?br?>
<literal>to_char(interval '15h 2m 12s', 'HH24:MI:SS')</literal>
<returnvalue>15:02:12</returnvalue>
</entry>
</row>
<row>
<entry role="functableentry">
<function>to_char</function> ( <replaceable>numeric_type</replaceable>, <type>text</type> )
<returnvalue>text</returnvalue>
<?br?>
Converts number to string according to the given format; available
for <type>integer</type>, <type>bigint</type>, <type>numeric</type>,
<type>real</type>, <type>double precision</type>.
<?br?>
<literal>to_char(125, '999')</literal>
<returnvalue>125</returnvalue>
<?br?>
<literal>to_char(125.8::real, '999D9')</literal>
<returnvalue>125.8</returnvalue>
<?br?>
<literal>to_char(-125.8, '999D99S')</literal>
<returnvalue>125.80-</returnvalue>
</entry>
</row>
<row>
<entry role="functableentry">
<indexterm>
<primary>to_date</primary>
</indexterm>
<function>to_date</function> ( <type>text</type>, <type>text</type> )
<returnvalue>date</returnvalue>
<?br?>
Converts string to date according to the given format.
<?br?>
<literal>to_date('05 Dec 2000', 'DD Mon YYYY')</literal>
<returnvalue>2000-12-05</returnvalue>
</entry>
</row>
<row>
<entry role="functableentry">
<indexterm>
<primary>to_number</primary>
</indexterm>
<function>to_number</function> ( <type>text</type>, <type>text</type> )
<returnvalue>numeric</returnvalue>
<?br?>
Converts string to numeric according to the given format.
<?br?>
<literal>to_number('12,454.8-', '99G999D9S')</literal>
<returnvalue>-12454.8</returnvalue>
</entry>
</row>
<row>
<entry role="functableentry">
<indexterm>
<primary>to_timestamp</primary>
</indexterm>
<function>to_timestamp</function> ( <type>text</type>, <type>text</type> )
<returnvalue>timestamp with time zone</returnvalue>
<?br?>
Converts string to time stamp according to the given format.
(See also <function>to_timestamp(double precision)</function> in
<xref linkend="functions-datetime-table"/>.)
<?br?>
<literal>to_timestamp('05 Dec 2000', 'DD Mon YYYY')</literal>
<returnvalue>2000-12-05 00:00:00-05</returnvalue>
</entry>
</row>
</tbody>
</tgroup>
</table>
<tip> <tip>
<para> <para>
...@@ -8739,9 +8780,7 @@ SELECT EXTRACT(QUARTER FROM TIMESTAMP '2001-02-16 20:38:40'); ...@@ -8739,9 +8780,7 @@ SELECT EXTRACT(QUARTER FROM TIMESTAMP '2001-02-16 20:38:40');
<term><literal>second</literal></term> <term><literal>second</literal></term>
<listitem> <listitem>
<para> <para>
The seconds field, including fractional parts (0 - The seconds field, including any fractional seconds
59<footnote><simpara>60 if leap seconds are
implemented by the operating system</simpara></footnote>)
</para> </para>
<screen> <screen>
...@@ -8969,48 +9008,66 @@ SELECT date_trunc('hour', INTERVAL '3 days 02:47:33'); ...@@ -8969,48 +9008,66 @@ SELECT date_trunc('hour', INTERVAL '3 days 02:47:33');
</indexterm> </indexterm>
<para> <para>
The <literal>AT TIME ZONE</literal> converts time The <literal>AT TIME ZONE</literal> operator converts time
stamp <emphasis>without time zone</emphasis> to/from stamp <emphasis>without</emphasis> time zone to/from
time stamp <emphasis>with time zone</emphasis>, and time stamp <emphasis>with</emphasis> time zone, and
<emphasis>time</emphasis> values to different time zones. <xref <type>time with time zone</type> values to different time
linkend="functions-datetime-zoneconvert-table"/> shows its variants. zones. <xref linkend="functions-datetime-zoneconvert-table"/> shows its
variants.
</para> </para>
<table id="functions-datetime-zoneconvert-table"> <table id="functions-datetime-zoneconvert-table">
<title><literal>AT TIME ZONE</literal> Variants</title> <title><literal>AT TIME ZONE</literal> Variants</title>
<tgroup cols="3"> <tgroup cols="1">
<thead> <thead>
<row> <row>
<entry>Expression</entry> <entry role="functableentry">
<entry>Return Type</entry> Operator<?br?>Description<?br?>Example(s)
<entry>Description</entry> </entry>
</row> </row>
</thead> </thead>
<tbody> <tbody>
<row> <row>
<entry> <entry role="functableentry">
<literal><type>timestamp without time zone</type> AT TIME ZONE <replaceable>zone</replaceable></literal> <type>timestamp without time zone</type> <literal>AT TIME ZONE</literal> <replaceable>zone</replaceable>
<returnvalue>timestamp with time zone</returnvalue>
<?br?>
Converts given time stamp <emphasis>without</emphasis> time zone to
time stamp <emphasis>with</emphasis> time zone, assuming the given
value is in the named time zone.
<?br?>
<literal>timestamp '2001-02-16 20:38:40' at time zone 'America/Denver'</literal>
<returnvalue>2001-02-17 03:38:40+00</returnvalue>
</entry> </entry>
<entry><type>timestamp with time zone</type></entry>
<entry>Treat given time stamp <emphasis>without time zone</emphasis> as located in the specified time zone</entry>
</row> </row>
<row> <row>
<entry> <entry role="functableentry">
<literal><type>timestamp with time zone</type> AT TIME ZONE <replaceable>zone</replaceable></literal> <type>timestamp with time zone</type> <literal>AT TIME ZONE</literal> <replaceable>zone</replaceable>
<returnvalue>timestamp without time zone</returnvalue>
<?br?>
Converts given time stamp <emphasis>with</emphasis> time zone to
time stamp <emphasis>without</emphasis> time zone, as the time would
appear in that zone.
<?br?>
<literal>timestamp with time zone '2001-02-16 20:38:40-05' at time zone 'America/Denver'</literal>
<returnvalue>2001-02-16 18:38:40</returnvalue>
</entry> </entry>
<entry><type>timestamp without time zone</type></entry>
<entry>Convert given time stamp <emphasis>with time zone</emphasis> to the new time
zone, with no time zone designation</entry>
</row> </row>
<row> <row>
<entry> <entry role="functableentry">
<literal><type>time with time zone</type> AT TIME ZONE <replaceable>zone</replaceable></literal> <type>time with time zone</type> <literal>AT TIME ZONE</literal> <replaceable>zone</replaceable>
<returnvalue>time with time zone</returnvalue>
<?br?>
Converts given time <emphasis>with</emphasis> time zone to a new time
zone. Since no date is supplied, this uses the currently active UTC
offset for the named destination zone.
<?br?>
<literal>time with time zone '05:34:17-05' at time zone 'UTC'</literal>
<returnvalue>10:34:17+00</returnvalue>
</entry> </entry>
<entry><type>time with time zone</type></entry>
<entry>Convert given time <emphasis>with time zone</emphasis> to the new time zone</entry>
</row> </row>
</tbody> </tbody>
</tgroup> </tgroup>
...@@ -9018,14 +9075,17 @@ SELECT date_trunc('hour', INTERVAL '3 days 02:47:33'); ...@@ -9018,14 +9075,17 @@ SELECT date_trunc('hour', INTERVAL '3 days 02:47:33');
<para> <para>
In these expressions, the desired time zone <replaceable>zone</replaceable> can be In these expressions, the desired time zone <replaceable>zone</replaceable> can be
specified either as a text string (e.g., <literal>'America/Los_Angeles'</literal>) specified either as a text value (e.g., <literal>'America/Los_Angeles'</literal>)
or as an interval (e.g., <literal>INTERVAL '-08:00'</literal>). or as an interval (e.g., <literal>INTERVAL '-08:00'</literal>).
In the text case, a time zone name can be specified in any of the ways In the text case, a time zone name can be specified in any of the ways
described in <xref linkend="datatype-timezones"/>. described in <xref linkend="datatype-timezones"/>.
The interval case is only useful for zones that have fixed offsets from
UTC, so it is not very common in practice.
</para> </para>
<para> <para>
Examples (assuming the local time zone is <literal>America/Los_Angeles</literal>): Examples (assuming the current <xref linkend="guc-timezone"/> setting
is <literal>America/Los_Angeles</literal>):
<screen> <screen>
SELECT TIMESTAMP '2001-02-16 20:38:40' AT TIME ZONE 'America/Denver'; SELECT TIMESTAMP '2001-02-16 20:38:40' AT TIME ZONE 'America/Denver';
<lineannotation>Result: </lineannotation><computeroutput>2001-02-16 19:38:40-08</computeroutput> <lineannotation>Result: </lineannotation><computeroutput>2001-02-16 19:38:40-08</computeroutput>
...@@ -9033,7 +9093,7 @@ SELECT TIMESTAMP '2001-02-16 20:38:40' AT TIME ZONE 'America/Denver'; ...@@ -9033,7 +9093,7 @@ SELECT TIMESTAMP '2001-02-16 20:38:40' AT TIME ZONE 'America/Denver';
SELECT TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40-05' AT TIME ZONE 'America/Denver'; SELECT TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40-05' AT TIME ZONE 'America/Denver';
<lineannotation>Result: </lineannotation><computeroutput>2001-02-16 18:38:40</computeroutput> <lineannotation>Result: </lineannotation><computeroutput>2001-02-16 18:38:40</computeroutput>
SELECT TIMESTAMP '2001-02-16 20:38:40-05' AT TIME ZONE 'Asia/Tokyo' AT TIME ZONE 'America/Chicago'; SELECT TIMESTAMP '2001-02-16 20:38:40' AT TIME ZONE 'Asia/Tokyo' AT TIME ZONE 'America/Chicago';
<lineannotation>Result: </lineannotation><computeroutput>2001-02-16 05:38:40</computeroutput> <lineannotation>Result: </lineannotation><computeroutput>2001-02-16 05:38:40</computeroutput>
</screen> </screen>
The first example adds a time zone to a value that lacks it, and The first example adds a time zone to a value that lacks it, and
...@@ -9042,9 +9102,7 @@ SELECT TIMESTAMP '2001-02-16 20:38:40-05' AT TIME ZONE 'Asia/Tokyo' AT TIME ZONE ...@@ -9042,9 +9102,7 @@ SELECT TIMESTAMP '2001-02-16 20:38:40-05' AT TIME ZONE 'Asia/Tokyo' AT TIME ZONE
to the specified time zone, and returns the value without a time zone. to the specified time zone, and returns the value without a time zone.
This allows storage and display of values different from the current This allows storage and display of values different from the current
<varname>TimeZone</varname> setting. The third example converts <varname>TimeZone</varname> setting. The third example converts
Tokyo time to Chicago time. Converting <emphasis>time</emphasis> Tokyo time to Chicago time.
values to other time zones uses the currently active time zone rules
since no date is supplied.
</para> </para>
<para> <para>
...@@ -9225,17 +9283,16 @@ SELECT TIMESTAMP 'now'; -- incorrect for use with DEFAULT ...@@ -9225,17 +9283,16 @@ SELECT TIMESTAMP 'now'; -- incorrect for use with DEFAULT
The following functions are available to delay execution of the server The following functions are available to delay execution of the server
process: process:
<synopsis> <synopsis>
pg_sleep(<replaceable>seconds</replaceable>) pg_sleep ( <type>double precision</type> )
pg_sleep_for(<type>interval</type>) pg_sleep_for ( <type>interval</type> )
pg_sleep_until(<type>timestamp with time zone</type>) pg_sleep_until ( <type>timestamp with time zone</type> )
</synopsis> </synopsis>
<function>pg_sleep</function> makes the current session's process <function>pg_sleep</function> makes the current session's process
sleep until <replaceable>seconds</replaceable> seconds have sleep until the given number of seconds have
elapsed. <replaceable>seconds</replaceable> is a value of type elapsed. Fractional-second delays can be specified.
<type>double precision</type>, so fractional-second delays can be specified. <function>pg_sleep_for</function> is a convenience function to
<function>pg_sleep_for</function> is a convenience function for larger allow the sleep time to be specified as an <type>interval</type>.
sleep times specified as an <type>interval</type>.
<function>pg_sleep_until</function> is a convenience function for when <function>pg_sleep_until</function> is a convenience function for when
a specific wake-up time is desired. a specific wake-up time is desired.
For example: For example:
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment