Skip to content
Snippets Groups Projects
Commit d584bf48 authored by Tom Lane's avatar Tom Lane
Browse files

Improve description of to_char templates.

parent 7f020491
No related branches found
No related tags found
No related merge requests found
Show whitespace changes
Inline Side-by-side
Showing
with 73 additions and 55 deletions
doc/src/sgml/func.sgml
+ 73
− 55
View file @ d584bf48
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/func.sgml,v 1.54 2001/02/21 23:15:24 tgl Exp $ --> <!-- $Header: /cvsroot/pgsql/doc/src/sgml/func.sgml,v 1.55 2001/03/15 01:07:51 tgl Exp $ -->
<chapter id="functions"> <chapter id="functions">
<title>Functions and Operators</title> <title>Functions and Operators</title>
...@@ -1387,9 +1387,9 @@ ...@@ -1387,9 +1387,9 @@
provide a powerful set of tools for converting various data types provide a powerful set of tools for converting various data types
(date/time, integer, floating point, numeric) to formatted strings (date/time, integer, floating point, numeric) to formatted strings
and for converting from formatted strings to specific data types. and for converting from formatted strings to specific data types.
These functions all follow a common calling convention: The first These functions all follow a common calling convention: the first
argument is the value to be formatted and the second argument is a argument is the value to be formatted and the second argument is a
template that defines the output format. template that defines the output or input format.
</para> </para>
<para> <para>
...@@ -1437,7 +1437,7 @@ ...@@ -1437,7 +1437,7 @@
</row> </row>
<row> <row>
<entry>to_timestamp(text, text)</entry> <entry>to_timestamp(text, text)</entry>
<entry>date</entry> <entry>timestamp</entry>
<entry>convert string to timestamp</entry> <entry>convert string to timestamp</entry>
<entry>to_timestamp('05 Dec 2000', 'DD Mon YYYY')</entry> <entry>to_timestamp('05 Dec 2000', 'DD Mon YYYY')</entry>
</row> </row>
...@@ -1452,13 +1452,22 @@ ...@@ -1452,13 +1452,22 @@
</table> </table>
</para> </para>
<para>
In an output template string, there are certain patterns that are
recognized and replaced with appropriately-formatted data from the value
to be formatted. Any text that is not a template pattern is simply
copied verbatim. Similarly, in an input template string template patterns
identify the parts of the input data string to be looked at and the
values to be found there.
</para>
<para> <para>
<table tocentry="1"> <table tocentry="1">
<title>Templates for date/time conversions</title> <title>Template patterns for date/time conversions</title>
<tgroup cols="2"> <tgroup cols="2">
<thead> <thead>
<row> <row>
<entry>Template</entry> <entry>Pattern</entry>
<entry>Description</entry> <entry>Description</entry>
</row> </row>
</thead> </thead>
...@@ -1525,19 +1534,19 @@ ...@@ -1525,19 +1534,19 @@
</row> </row>
<row> <row>
<entry>MONTH</entry> <entry>MONTH</entry>
<entry>full upper case month name (9 chars)</entry> <entry>full upper case month name (blank-padded to 9 chars)</entry>
</row> </row>
<row> <row>
<entry>Month</entry> <entry>Month</entry>
<entry>full mixed case month name (9 chars)</entry> <entry>full mixed case month name (blank-padded to 9 chars)</entry>
</row> </row>
<row> <row>
<entry>month</entry> <entry>month</entry>
<entry>full lower case month name (9 chars)</entry> <entry>full lower case month name (blank-padded to 9 chars)</entry>
</row> </row>
<row> <row>
<entry>MON</entry> <entry>MON</entry>
<entry>upper case abbreviated month name (3 chars)</entry> <entry>abbreviated upper case month name (3 chars)</entry>
</row> </row>
<row> <row>
<entry>Mon</entry> <entry>Mon</entry>
...@@ -1549,19 +1558,19 @@ ...@@ -1549,19 +1558,19 @@
</row> </row>
<row> <row>
<entry>MM</entry> <entry>MM</entry>
<entry>month (01-12)</entry> <entry>month number (01-12)</entry>
</row> </row>
<row> <row>
<entry>DAY</entry> <entry>DAY</entry>
<entry>full upper case day name (9 chars)</entry> <entry>full upper case day name (blank-padded to 9 chars)</entry>
</row> </row>
<row> <row>
<entry>Day</entry> <entry>Day</entry>
<entry>full mixed case day name (9 chars)</entry> <entry>full mixed case day name (blank-padded to 9 chars)</entry>
</row> </row>
<row> <row>
<entry>day</entry> <entry>day</entry>
<entry>full lower case day name (9 chars)</entry> <entry>full lower case day name (blank-padded to 9 chars)</entry>
</row> </row>
<row> <row>
<entry>DY</entry> <entry>DY</entry>
...@@ -1621,11 +1630,11 @@ ...@@ -1621,11 +1630,11 @@
</row> </row>
<row> <row>
<entry>TZ</entry> <entry>TZ</entry>
<entry>timezone string - upper case</entry> <entry>timezone name - upper case</entry>
</row> </row>
<row> <row>
<entry>tz</entry> <entry>tz</entry>
<entry>timezone string - lower case</entry> <entry>timezone name - lower case</entry>
</row> </row>
</tbody> </tbody>
</tgroup> </tgroup>
...@@ -1633,45 +1642,46 @@ ...@@ -1633,45 +1642,46 @@
</para> </para>
<para> <para>
All templates allow the use of prefix and suffix modifiers. Modifiers are Certain modifiers may be applied to any template pattern to alter its
always valid for use in templates. The prefix behavior. For example, <quote><literal>FMMonth</literal></quote>
<quote><literal>FX</literal></quote> is a global modifier only. is the <quote><literal>Month</literal></quote> pattern with the
<quote><literal>FM</literal></quote> prefix.
</para> </para>
<para> <para>
<table tocentry="1"> <table tocentry="1">
<title>Suffixes for templates for date/time to_char()</title> <title>Template pattern modifiers for date/time conversions</title>
<tgroup cols="3"> <tgroup cols="3">
<thead> <thead>
<row> <row>
<entry>Suffix</entry> <entry>Modifier</entry>
<entry>Description</entry> <entry>Description</entry>
<entry>Example</entry> <entry>Example</entry>
</row> </row>
</thead> </thead>
<tbody> <tbody>
<row> <row>
<entry>FM</entry> <entry><literal>FM</literal> prefix</entry>
<entry>fill mode prefix</entry> <entry>fill mode (suppress padding blanks and zeroes)</entry>
<entry>FMMonth</entry> <entry>FMMonth</entry>
</row> </row>
<row> <row>
<entry>TH</entry> <entry><literal>TH</literal> suffix</entry>
<entry>upper ordinal number suffix</entry> <entry>add upper-case ordinal number suffix</entry>
<entry>DDTH</entry> <entry>DDTH</entry>
</row> </row>
<row> <row>
<entry>th</entry> <entry><literal>th</literal> suffix</entry>
<entry>lower ordinal number suffix</entry> <entry>add lower-case ordinal number suffix</entry>
<entry>DDTH</entry> <entry>DDth</entry>
</row> </row>
<row> <row>
<entry>FX</entry> <entry><literal>FX</literal> prefix</entry>
<entry>FiXed format global option (see below)</entry> <entry>FiXed format global option (see below)</entry>
<entry>FX Month DD Day</entry> <entry>FX Month DD Day</entry>
</row> </row>
<row> <row>
<entry>SP</entry> <entry><literal>SP</literal> suffix</entry>
<entry>spell mode (not yet implemented)</entry> <entry>spell mode (not yet implemented)</entry>
<entry>DDSP</entry> <entry>DDSP</entry>
</row> </row>
...@@ -1684,15 +1694,23 @@ ...@@ -1684,15 +1694,23 @@
Usage notes: Usage notes:
<itemizedlist> <itemizedlist>
<listitem>
<para>
<literal>FM</literal> suppresses leading zeroes or trailing blanks
that would otherwise be added to make the output of a pattern be
fixed-width.
</para>
</listitem>
<listitem> <listitem>
<para> <para>
<function>to_timestamp</function> and <function>to_date</function> <function>to_timestamp</function> and <function>to_date</function>
skip multiple blank space in converted string if the <literal>FX</literal> option skip multiple blank spaces in the input string if the <literal>FX</literal> option
is not used. <literal>FX</literal> must be specified as the first item is not used. <literal>FX</literal> must be specified as the first item
in the template; for example in the template; for example
<literal>to_timestamp('2000 JUN','YYYY MON')</literal> is right, but <literal>to_timestamp('2000 JUN','YYYY MON')</literal> is right, but
<literal>to_timestamp('2000 JUN','FXYYYY MON')</literal> returns error, <literal>to_timestamp('2000 JUN','FXYYYY MON')</literal> returns an error,
because to_timestamp() expects one blank space only. because <function>to_timestamp</function> expects one blank space only.
</para> </para>
</listitem> </listitem>
...@@ -1709,19 +1727,20 @@ ...@@ -1709,19 +1727,20 @@
<listitem> <listitem>
<para> <para>
Ordinary text is allowed in <function>to_char</function> Ordinary text is allowed in <function>to_char</function>
templates but any string between double quotes is guaranteed templates and will be output literally. You can put a substring
that it will not be interpreted as a template keyword and it is in double quotes to force it to be interpreted as literal text
also processed faster. (Example: <literal>'"Hello Year: even if it contains pattern keywords. For example, in
"YYYY'</literal>). <literal>'"Hello Year: "YYYY'</literal>, the <literal>YYYY</literal>
will be replaced by year data, but the single <literal>Y</literal>
will not be.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
A double quote (<quote><literal>"</literal></quote>) between If you want to
quotation marks is skipped and is not parsed. If you want to
have a double quote in the output you must precede it with a have a double quote in the output you must precede it with a
double backslash, for example <literal>'\\"YYYY backslash, for example <literal>'\\"YYYY
Month\\"'</literal>. <!-- " font-lock sanity :-) --> Month\\"'</literal>. <!-- " font-lock sanity :-) -->
</para> </para>
</listitem> </listitem>
...@@ -1745,11 +1764,11 @@ ...@@ -1745,11 +1764,11 @@
<para> <para>
<table tocentry="1"> <table tocentry="1">
<title>Templates for to_char(<replaceable>numeric</replaceable>)</title> <title>Template patterns for numeric conversions</title>
<tgroup cols="2"> <tgroup cols="2">
<thead> <thead>
<row> <row>
<entry>Template</entry> <entry>Pattern</entry>
<entry>Description</entry> <entry>Description</entry>
</row> </row>
</thead> </thead>
...@@ -1843,25 +1862,24 @@ ...@@ -1843,25 +1862,24 @@
<listitem> <listitem>
<para> <para>
<literal>PL</literal>, <literal>SG</literal>, and <literal>9</literal> specifies a value with the same number of
<literal>TH</literal> are <productname>Postgres</productname> digits as there are <literal>9</literal>s. If a digit is
extensions. not available use blank space.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
<literal>9</literal> specifies a value with the same number of <literal>TH</literal> does not convert values less than zero
digits as there are <literal>9</literal>s. If a digit is and does not convert decimal numbers.
not available use blank space.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
<literal>TH</literal> does not convert values less than zero <literal>PL</literal>, <literal>SG</literal>, and
and does not convert decimal numbers. <literal>TH</literal> is <literal>TH</literal> are <productname>Postgres</productname>
a <productname>Postgres</productname> extension. extensions.
</para> </para>
</listitem> </listitem>
...@@ -1892,12 +1910,12 @@ ...@@ -1892,12 +1910,12 @@
</thead> </thead>
<tbody> <tbody>
<row> <row>
<entry>to_char(now(),'Day, HH12:MI:SS')</entry> <entry>to_char(now(),'Day, DD HH12:MI:SS')</entry>
<entry><literal>'Tuesday , 05:39:18'</literal></entry> <entry><literal>'Tuesday , 06 05:39:18'</literal></entry>
</row> </row>
<row> <row>
<entry>to_char(now(),'FMDay, HH12:MI:SS')</entry> <entry>to_char(now(),'FMDay, FMDD HH12:MI:SS')</entry>
<entry><literal>'Tuesday, 05:39:18'</literal></entry> <entry><literal>'Tuesday, 6 05:39:18'</literal></entry>
</row> </row>
<row> <row>
<entry>to_char(-0.1,'99.99')</entry> <entry>to_char(-0.1,'99.99')</entry>
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment