Document that "Q" is ignored by to_date and to_timestamp. Add C comment

bmomjian · bmomjian · commit ea066f87c3e9 · 2010-03-03T22:28:42.000Z
about the behavior.

Document that quotes in to_date, to_timestamp, to_number skip input
characters.
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.506 2010/02/23 16:14:25 momjian Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.507 2010/03/03 22:28:42 momjian Exp $ -->
 
  <chapter id="functions">
   <title>Functions and Operators</title>
@@ -5089,7 +5089,7 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
        </row>
        <row>
         <entry><literal>Q</literal></entry>
-        <entry>quarter</entry>
+        <entry>quarter (ignored by <function>to_date</> and <function>to_timestamp</>)</entry>
        </row>
        <row>
         <entry><literal>RM</literal></entry>
@@ -5209,7 +5209,10 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
        even if it contains pattern key words.  For example, in
        <literal>'"Hello Year "YYYY'</literal>, the <literal>YYYY</literal>
        will be replaced by the year data, but the single <literal>Y</literal> in <literal>Year</literal>
-       will not be.
+       will not be.  In <function>to_date</>, <function>to_number</>,
+       and <function>to_timestamp</>, double-quoted strings skip the number of
+       input characters contained in the string, e.g. <literal>"XX"</>
+       skips two input characters.
       </para>
      </listitem>
 
diff --git a/src/backend/utils/adt/formatting.c b/src/backend/utils/adt/formatting.c
@@ -1,7 +1,7 @@
 /* -----------------------------------------------------------------------
  * formatting.c
  *
- * $PostgreSQL: pgsql/src/backend/utils/adt/formatting.c,v 1.168 2010/02/26 02:01:08 momjian Exp $
+ * $PostgreSQL: pgsql/src/backend/utils/adt/formatting.c,v 1.169 2010/03/03 22:28:42 momjian Exp $
  *
  *
  *	 Portions Copyright (c) 1999-2010, PostgreSQL Global Development Group
@@ -2671,10 +2671,12 @@ DCH_from_char(FormatNode *node, char *in, TmFromChar *out)
 				s += SKIP_THth(n->suffix);
 				break;
 			case DCH_Q:
-
 				/*
-				 * We ignore Q when converting to date because it is not
-				 * normative.
+				 * We ignore 'Q' when converting to date because it is
+				 * unclear which date in the quarter to use, and some
+				 * people specify both quarter and month, so if it was
+				 * honored it might conflict with the supplied month.
+				 * That is also why we don't throw an error.
 				 *
 				 * We still parse the source string for an integer, but it
 				 * isn't stored anywhere in 'out'.

Original file line number	Diff line number	Diff line change
`@@ -1,7 +1,7 @@`
`1`	`1`	`/* -----------------------------------------------------------------------`
`2`	`2`	`* formatting.c`
`3`	`3`	`*`
`4`		`- * $PostgreSQL: pgsql/src/backend/utils/adt/formatting.c,v 1.168 2010/02/26 02:01:08 momjian Exp $`
	`4`	`+ * $PostgreSQL: pgsql/src/backend/utils/adt/formatting.c,v 1.169 2010/03/03 22:28:42 momjian Exp $`
`5`	`5`	`*`
`6`	`6`	`*`
`7`	`7`	`* Portions Copyright (c) 1999-2010, PostgreSQL Global Development Group`
`@@ -2671,10 +2671,12 @@ DCH_from_char(FormatNode node, char in, TmFromChar *out)`
`2671`	`2671`	`s += SKIP_THth(n->suffix);`
`2672`	`2672`	`break;`
`2673`	`2673`	`case DCH_Q:`
`2674`		`-`
`2675`	`2674`	`/*`
`2676`		`- * We ignore Q when converting to date because it is not`
`2677`		`- * normative.`
	`2675`	`+ * We ignore 'Q' when converting to date because it is`
	`2676`	`+ * unclear which date in the quarter to use, and some`
	`2677`	`+ * people specify both quarter and month, so if it was`
	`2678`	`+ * honored it might conflict with the supplied month.`
	`2679`	`+ * That is also why we don't throw an error.`
`2678`	`2680`	`*`
`2679`	`2681`	`* We still parse the source string for an integer, but it`
`2680`	`2682`	`* isn't stored anywhere in 'out'.`