[HACKERS] Documentation patch for to_date and to_timestamp

[Steve Crawford]

The attached patch is in response to ongoing mailing-list questions 
regarding perceived weirdness in to_timestamp and to_date.

The patch modifies doc/src/sgml/func.sgml to add "(see usage notes)" in 
the description column for to_date and to_timestamp in the Formatting 
Functions table and adds the following two list items to the start of 
the usage notes for date/time conversion:

The to_date and to_timestamp functions exist to parse unusual input 
formats that cannot be handled by casting. These functions interpret 
input liberally and with minimal error checking so the conversion has 
the potential to yield unexpected results. Read the following notes and 
test carefully before use. Casting is the preferred method of conversion 
wherever possible.

Input to to_date and to_timestamp is not restricted to normal ranges 
thus to_date('20096040','YYYYMMDD') returns 2014-01-17 rather than 
generating an error.

Cheers,
Steve

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index c76d357..19197ce 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -5426,7 +5426,7 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
          <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>convert string to date (see usage notes)</entry>
         <entry><literal>to_date('05&nbsp;Dec&nbsp;2000', 'DD&nbsp;Mon&nbsp;YYYY')</literal></entry>
        </row>
        <row>
@@ -5448,7 +5448,7 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
          <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>convert string to time stamp (see usage notes)</entry>
         <entry><literal>to_timestamp('05&nbsp;Dec&nbsp;2000', 'DD&nbsp;Mon&nbsp;YYYY')</literal></entry>
        </row>
        <row>
@@ -5750,10 +5750,32 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
 
    <para>
     Usage notes for date/time formatting:
+   </para>
 
+   <para>
     <itemizedlist>
      <listitem>
       <para>
+       The <function>to_date</function> and <function>to_timestamp</function>
+       functions exist to parse unusual input formats that cannot be handled
+       by casting.  These functions interpret input liberally and with minimal
+       error checking so the conversion has the potential to yield unexpected
+       results.  Read the following notes and test carefully before use.
+       Casting is the preferred method of conversion wherever possible.
+      </para>
+     </listitem>
+
+     <listitem>
+      <para>
+       Input to <function>to_date</function> and
+       <function>to_timestamp</function> is not restricted to normal ranges
+       thus <literal>to_date('20096040','YYYYMMDD')</literal> returns
+       <literal>2014-01-17</literal> rather than generating an error.
+      </para>
+     </listitem>
+
+     <listitem>
+      <para>
        <literal>FM</literal> suppresses leading zeroes and trailing blanks
        that would otherwise be added to make the output of a pattern be
        fixed-width.  In <productname>PostgreSQL</productname>,
-- 
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers