Documentation patch for date/time formatting functions
Due to a variety of messages over time regarding perceived weirdness in
to_timestamp and to_date, this patch adds "(see notes)" in the
description column for to_date and to_timestamp in the Formatting
Functions table and adds the following text to the opening of the usage
notes for date/time conversion:
The to_date and to_timestamp functions exist to handle unusual input
formats that cannot be converted by simple casting. These functions
interpret input liberally and with minimal error checking and while they
will produce valid output, 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.
It also adds the following usage note:
Input to to_date and to_timestamp is not restricted to normal ranges
thus to_date('20096040','YYYYMMDD') returns 2014-01-17 rather than
causing an error.
This is the first patch I have submitted directly. Please advise if I
have made any errors in method, style, etc.
Cheers,
Steve
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index a1d3aee..6f5eee0 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 notes)</entry>
<entry><literal>to_date('05 Dec 2000',
'DD Mon 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 notes)</entry>
<entry><literal>to_timestamp('05 Dec 2000',
'DD Mon YYYY')</literal></entry>
</row>
<row>
@@ -5750,10 +5750,27 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})'); <para>
Usage notes for date/time formatting:
-
+ </para>
+ <para>
+ The <function>to_date</function> and <function>to_timestamp<function>
+ functions exist to handle unusual input formats that cannot be
+ converted by simple casting. These functions interpret input
liberally
+ and with minimal error checking and while they will produce valid
output,
+ 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.
<itemizedlist>
<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 causing 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
On Thu, Nov 7, 2013 at 9:14 AM, Steve Crawford
<scrawford@pinpointresearch.com> wrote:
Due to a variety of messages over time regarding perceived weirdness in
to_timestamp and to_date, this patch adds "(see notes)" in the description
column for to_date and to_timestamp in the Formatting Functions table and
adds the following text to the opening of the usage notes for date/time
conversion:The to_date and to_timestamp functions exist to handle unusual input formats
that cannot be converted by simple casting. These functions interpret input
liberally and with minimal error checking and while they will produce valid
output, 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.It also adds the following usage note:
Input to to_date and to_timestamp is not restricted to normal ranges thus
to_date('20096040','YYYYMMDD') returns 2014-01-17 rather than causing an
error.This is the first patch I have submitted directly. Please advise if I have
made any errors in method, style, etc.
Sure. You should do the following things:
- attach a proper patch to the email you are sending such as people
can easily download it and have a look at it without having to
regenerate it themselves
- submit it to the next commit fest if you want to have it reviewed:
https://commitfest.postgresql.org/action/commitfest_view?id=20. Next
commit fest begins on the 15th of November and your patch is simple,
so for sure somebody will show up and have a closer look at it.
Here are as well general guidelines about patch submission:
http://wiki.postgresql.org/wiki/Submitting_a_Patch
Regards,
--
Michael
--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers
On Thu, Nov 7, 2013 at 11:46:24AM +0900, Michael Paquier wrote:
On Thu, Nov 7, 2013 at 9:14 AM, Steve Crawford
<scrawford@pinpointresearch.com> wrote:Due to a variety of messages over time regarding perceived weirdness in
to_timestamp and to_date, this patch adds "(see notes)" in the description
column for to_date and to_timestamp in the Formatting Functions table and
adds the following text to the opening of the usage notes for date/time
conversion:The to_date and to_timestamp functions exist to handle unusual input formats
that cannot be converted by simple casting. These functions interpret input
liberally and with minimal error checking and while they will produce valid
output, 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.It also adds the following usage note:
Input to to_date and to_timestamp is not restricted to normal ranges thus
to_date('20096040','YYYYMMDD') returns 2014-01-17 rather than causing an
error.This is the first patch I have submitted directly. Please advise if I have
made any errors in method, style, etc.Sure. You should do the following things:
- attach a proper patch to the email you are sending such as people
can easily download it and have a look at it without having to
regenerate it themselves
- submit it to the next commit fest if you want to have it reviewed:
https://commitfest.postgresql.org/action/commitfest_view?id=20. Next
commit fest begins on the 15th of November and your patch is simple,
so for sure somebody will show up and have a closer look at it.
I have applied a modified version of your doc patch, attached. I didn't
bother with "See below" as everyone seems to find that section.
Thanks.
--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com
+ Everyone has their own god. +
Attachments:
timestamp.difftext/x-diff; charset=us-asciiDownload
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
new file mode 100644
index a1f627c..b1ea466
*** a/doc/src/sgml/func.sgml
--- b/doc/src/sgml/func.sgml
*************** SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1
*** 5785,5790 ****
--- 5785,5804 ----
<listitem>
<para>
+ <function>to_timestamp</function> and <function>to_date</function>
+ exist to handle input formats that cannot be converted by
+ simple casting. These functions interpret input liberally,
+ with minimal error checking. While they produce valid output,
+ the conversion can yield unexpected results. For example,
+ input to these functions is not restricted by normal ranges,
+ thus <literal>to_date('20096040','YYYYMMDD')</literal> returns
+ <literal>2014-01-17</literal> rather than causing an error.
+ Casting does not have this behavior.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
Ordinary text is allowed in <function>to_char</function>
templates and will be output literally. You can put a substring
in double quotes to force it to be interpreted as literal text