Adjust the parser to accept the typename syntax INTERVAL ... SECOND(n)

and the literal syntax INTERVAL 'string' ... SECOND(n), as required by the
SQL standard.  Our old syntax put (n) directly after INTERVAL, which was
a mistake, but will still be accepted for backward compatibility as well
as symmetry with the TIMESTAMP cases.

Change intervaltypmodout to show it in the spec's way, too.  (This could
potentially affect clients, if there are any that analyze the typmod of an
INTERVAL in any detail.)

Also fix interval input to handle 'min:sec.frac' properly; I had overlooked
this case in my previous patch.

Document the use of the interval fields qualifier, which up to now we had
never mentioned in the docs.  (I think the omission was intentional because
it didn't work per spec; but it does now, or at least close enough to be
credible.)

1 files changed, 39 insertions, 7 deletions

diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index 48dfe0a9c47..0b969eaa22e 100644
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/datatype.sgml,v 1.227 2008/05/16 16:31:01 tgl Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/datatype.sgml,v 1.228 2008/09/11 15:27:30 tgl Exp $ -->
 
  <chapter id="datatype">
   <title id="datatype-title">Data Types</title>
@@ -131,7 +131,7 @@
       </row>
 
       <row>
-       <entry><type>interval [ (<replaceable>p</replaceable>) ]</type></entry>
+       <entry><type>interval [ <replaceable>fields</replaceable> ] [ (<replaceable>p</replaceable>) ]</type></entry>
        <entry></entry>
        <entry>time span</entry>
       </row>
@@ -1420,7 +1420,7 @@ SELECT b, char_length(b) FROM test2;
         <entry>1 microsecond / 14 digits</entry>
        </row>
        <row>
-        <entry><type>interval [ (<replaceable>p</replaceable>) ]</type></entry>
+        <entry><type>interval [ <replaceable>fields</replaceable> ] [ (<replaceable>p</replaceable>) ]</type></entry>
         <entry>12 bytes</entry>
         <entry>time intervals</entry>
         <entry>-178000000 years</entry>
@@ -1506,6 +1506,30 @@ SELECT b, char_length(b) FROM test2;
    </para>
 
    <para>
+    The <type>interval</type> type has an additional option, which is
+    to restrict the set of stored fields by writing one of these phrases:
+<programlisting>
+    YEAR
+    MONTH
+    DAY
+    HOUR
+    MINUTE
+    SECOND
+    YEAR TO MONTH
+    DAY TO HOUR
+    DAY TO MINUTE
+    DAY TO SECOND
+    HOUR TO MINUTE
+    MINUTE TO SECOND
+</programlisting>
+    Input falling outside the specified set of fields is silently discarded.
+    Note that if both <replaceable>fields</replaceable> and
+    <replaceable>precision</replaceable> are specified, the
+    <replaceable>fields</replaceable> must include <literal>SECOND</>,
+    since the precision applies only to the seconds.
+   </para>
+
+   <para>
     The type <type>time with time zone</type> is defined by the SQL
     standard, but the definition exhibits properties which lead to
     questionable usefulness. In most cases, a combination of
@@ -1928,18 +1952,26 @@ January 8 04:05:06 1999 PST
       <replaceable>direction</> can be <literal>ago</literal> or
       empty.  The at sign (<literal>@</>) is optional noise.  The amounts
       of different units are implicitly added up with appropriate
-      sign accounting.
+      sign accounting.  <literal>ago</literal> negates all the fields.
      </para>
 
      <para>
       Quantities of days, hours, minutes, and seconds can be specified without
       explicit unit markings.  For example, <literal>'1 12:59:10'</> is read
-      the same as <literal>'1 day 12 hours 59 min 10 sec'</>.
+      the same as <literal>'1 day 12 hours 59 min 10 sec'</>.  Also,
+      a combination of years and months can be specified with a dash;
+      for example <literal>'200-10'</> is read the same as <literal>'200 years
+      10 months'</>.  (These shorter forms are in fact the only ones allowed
+      by the SQL standard.)
      </para>
 
      <para>
-      The optional subsecond precision <replaceable>p</replaceable> should 
-      be between 0 and 6, and defaults to the precision of the input literal.
+      When writing an interval constant with a <replaceable>fields</>
+      specification, or when assigning to an interval column that was defined
+      with a <replaceable>fields</> specification, the interpretation of
+      unmarked quantities depends on the <replaceable>fields</>.  For
+      example <literal>INTERVAL '1' YEAR</> is read as 1 year, whereas
+      <literal>INTERVAL '1'</> means 1 second.
      </para>
 
      <para>