Describe the date/time parsing rules.

Include specific information on the supported time zones.
 It's a really big table, so maybe it should go into an appendix instead.

diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index 1a8dcadda48dcbca632f07511d4dfbce385eac71..e6ff993b104990647842b7afbe1bcb9c530c7407 100644 (file)
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -1255,19 +1255,24 @@ the time zone becomes GMT (on most systems anyway).
        </thead>
        <tbody>
        <row>
-        <entry>ACSST</entry>
-        <entry>+10:30 </entry>
-        <entry>Central Australia Summer Std Time</entry>
+        <entry>NZDT</entry>
+        <entry>+13:00</entry>
+        <entry>New Zealand Daylight Time</entry>
        </row>
        <row>
-        <entry>ACST</entry>
-        <entry>+09:30 </entry>
-        <entry>Central Australia Std Time</entry>
+        <entry>IDLE</entry>
+        <entry>+12:00</entry>
+        <entry>International Date Line, East</entry>
        </row>
        <row>
-        <entry>ADT</entry>
-        <entry>-02:00 </entry>
-        <entry>Atlantic Daylight Time</entry>
+        <entry>NZST</entry>
+        <entry>+12:00</entry>
+        <entry>New Zealand Std Time</entry>
+       </row>
+       <row>
+        <entry>NZT</entry>
+        <entry>+12:00</entry>
+        <entry>New Zealand Time</entry>
        </row>
        <row>
         <entry>AESST</entry>
@@ -1275,44 +1280,44 @@ the time zone becomes GMT (on most systems anyway).
         <entry>Australia Eastern Summer Std Time</entry>
        </row>
        <row>
-        <entry>AEST</entry>
-        <entry>+10:00 </entry>
-        <entry>Australia Eastern Std Time</entry>
+        <entry>ACSST</entry>
+        <entry>+10:30 </entry>
+        <entry>Central Australia Summer Std Time</entry>
        </row>
        <row>
-        <entry>AHST</entry>
-        <entry>-10:00 </entry>
-        <entry>Alaska-Hawaii Std Time</entry>
+        <entry>CADT</entry>
+        <entry>+10:30 </entry>
+        <entry>Central Australia Daylight Savings Time</entry>
        </row>
        <row>
-        <entry>AST</entry>
-        <entry>-4:00 </entry>
-        <entry>Atlantic Std Time (Canada)</entry>
+        <entry>SADT</entry>
+        <entry>+10:30</entry>
+        <entry>South Australian Daylight Time</entry>
        </row>
        <row>
-        <entry>AWSST</entry>
-        <entry>+9:00 </entry>
-        <entry>Australia Western Summer Std Time</entry>
+        <entry>AEST</entry>
+        <entry>+10:00 </entry>
+        <entry>Australia Eastern Std Time</entry>
        </row>
        <row>
-        <entry>AWST</entry>
-        <entry>+8:00 </entry>
-        <entry>Australia Western Std Time</entry>
+        <entry>EAST</entry>
+        <entry>+10:00 </entry>
+        <entry>East Australian Std Time</entry>
        </row>
        <row>
-        <entry>BST</entry>
-        <entry>+1:00 </entry>
-        <entry>British Summer Time</entry>
+        <entry>GST</entry>
+        <entry>+10:00</entry>
+        <entry>Guam Std Time, USSR Zone 9</entry>
        </row>
        <row>
-        <entry>BT</entry>
-        <entry>+3:00 </entry>
-        <entry>Baghdad Time</entry>
+        <entry>LIGT</entry>
+        <entry>+10:00</entry>
+        <entry>Melbourne, Australia</entry>
        </row>
        <row>
-        <entry>CADT</entry>
-        <entry>+10:30 </entry>
-        <entry>Central Australia Daylight Savings Time</entry>
+        <entry>ACST</entry>
+        <entry>+09:30 </entry>
+        <entry>Central Australia Std Time</entry>
        </row>
        <row>
         <entry>CAST</entry>
@@ -1320,155 +1325,145 @@ the time zone becomes GMT (on most systems anyway).
         <entry>Central Australia Std Time</entry>
        </row>
        <row>
-        <entry>CAT</entry>
-        <entry>-10:00 </entry>
-        <entry>Central Alaska Time</entry>
-       </row>
-       <row>
-        <entry>CCT</entry>
-        <entry>+8:00 </entry>
-        <entry>China Coastal Time</entry>
+        <entry>SAT</entry>
+        <entry>+9:30</entry>
+        <entry>South Australian Std Time</entry>
        </row>
        <row>
-        <entry>CDT</entry>
-        <entry>-5:00 </entry>
-        <entry>Central Daylight Time</entry>
+        <entry>AWSST</entry>
+        <entry>+9:00 </entry>
+        <entry>Australia Western Summer Std Time</entry>
        </row>
        <row>
-        <entry>CET</entry>
-        <entry>+1:00 </entry>
-        <entry>Central European Time</entry>
+        <entry>JST</entry>
+        <entry>+9:00</entry>
+        <entry>Japan Std Time,USSR Zone 8</entry>
        </row>
        <row>
-        <entry>CETDST</entry>
-        <entry>+2:00 </entry>
-        <entry>Central European Daylight Savings Time</entry>
+        <entry>KST</entry>
+        <entry>+9:00</entry>
+        <entry>Korea Standard Time</entry>
        </row>
        <row>
-        <entry>CST</entry>
-        <entry>+6:00 </entry>
-        <entry>Central Std Time</entry>
+        <entry>WDT</entry>
+        <entry>+9:00</entry>
+        <entry>West Australian Daylight Time</entry>
        </row>
        <row>
-        <entry>DNT</entry>
-        <entry>+1:00 </entry>
-        <entry>Dansk Normal Tid</entry>
+        <entry>MT</entry>
+        <entry>+8:30</entry>
+        <entry>Moluccas Time</entry>
        </row>
        <row>
-        <entry>DST</entry>
-        <entry>+1:00 </entry>
-        <entry>Dansk Standard Time (?)</entry>
+        <entry>AWST</entry>
+        <entry>+8:00 </entry>
+        <entry>Australia Western Std Time</entry>
        </row>
        <row>
-        <entry>EAST</entry>
-        <entry>+10:00 </entry>
-        <entry>East Australian Std Time</entry>
+        <entry>CCT</entry>
+        <entry>+8:00 </entry>
+        <entry>China Coastal Time</entry>
        </row>
        <row>
-        <entry>EDT</entry>
-        <entry>-4:00 </entry>
-        <entry>Eastern Daylight Time</entry>
+        <entry>WADT</entry>
+        <entry>+8:00</entry>
+        <entry>West Australian Daylight Time</entry>
        </row>
        <row>
-        <entry>EET</entry>
-        <entry>+2:00 </entry>
-        <entry>Eastern Europe, USSR Zone 1</entry>
+        <entry>WST</entry>
+        <entry>+8:00</entry>
+        <entry>West Australian Std Time</entry>
        </row>
        <row>
-        <entry>EETDST</entry>
-        <entry>+3:00 </entry>
-        <entry>Eastern Europe Daylight Savings Time</entry>
+        <entry>JT</entry>
+        <entry>+7:30</entry>
+        <entry>Java Time</entry>
        </row>
        <row>
-        <entry>EST</entry>
-        <entry>-5:00 </entry>
-        <entry>Eastern Standard Time</entry>
+        <entry>WAST</entry>
+        <entry>+7:00</entry>
+        <entry>West Australian Std Time</entry>
        </row>
        <row>
-        <entry>FST</entry>
-        <entry>+1:00 </entry>
-        <entry>French Summer Time</entry>
+        <entry>IT</entry>
+        <entry>+3:30</entry>
+        <entry>Iran Time</entry>
        </row>
        <row>
-        <entry>FWT</entry>
-        <entry>+2:00</entry>
-        <entry>French Winter Time</entry>
+        <entry>BT</entry>
+        <entry>+3:00 </entry>
+        <entry>Baghdad Time</entry>
        </row>
        <row>
-        <entry>GMT</entry>
-        <entry>0:00</entry>
-        <entry>Greenwish Mean Time</entry>
+        <entry>EETDST</entry>
+        <entry>+3:00 </entry>
+        <entry>Eastern Europe Daylight Savings Time</entry>
        </row>
        <row>
-        <entry>GST</entry>
-        <entry>+10:00</entry>
-        <entry>Guam Std Time, USSR Zone 9</entry>
+        <entry>CETDST</entry>
+        <entry>+2:00 </entry>
+        <entry>Central European Daylight Savings Time</entry>
        </row>
        <row>
-        <entry>HDT</entry>
-        <entry>-9:00</entry>
-        <entry>Hawaii/Alaska</entry>
+        <entry>EET</entry>
+        <entry>+2:00 </entry>
+        <entry>Eastern Europe, USSR Zone 1</entry>
        </row>
        <row>
-        <entry>IDLE</entry>
-        <entry>+12:00</entry>
-        <entry>International Date Line, East</entry>
+        <entry>FWT</entry>
+        <entry>+2:00</entry>
+        <entry>French Winter Time</entry>
        </row>
        <row>
-        <entry>IDLW</entry>
-        <entry>-12:00</entry>
-        <entry>International Date Line, West</entry>
+        <entry>IST</entry>
+        <entry>+2:00</entry>
+        <entry>Israel Std Time</entry>
        </row>
        <row>
-        <entry>IST</entry>
+        <entry>MEST</entry>
         <entry>+2:00</entry>
-        <entry>Israel</entry>
+        <entry>Middle Europe Summer Time</entry>
        </row>
        <row>
-        <entry>IT</entry>
-        <entry>+3:40</entry>
-        <entry>Iran Time</entry>
+        <entry>METDST</entry>
+        <entry>+2:00</entry>
+        <entry>Middle Europe Daylight Time</entry>
        </row>
        <row>
-        <entry>JST</entry>
-        <entry>+9:00</entry>
-        <entry>Japan Std Time,USSR Zone 8</entry>
+        <entry>SST</entry>
+        <entry>+2:00</entry>
+        <entry>Swedish Summer Time</entry>
        </row>
        <row>
-        <entry>JT</entry>
-        <entry>+7:30</entry>
-        <entry>Java Time</entry>
+        <entry>BST</entry>
+        <entry>+1:00 </entry>
+        <entry>British Summer Time</entry>
        </row>
        <row>
-        <entry>KST</entry>
-        <entry>+9:00</entry>
-        <entry>Korea Standard Time</entry>
+        <entry>CET</entry>
+        <entry>+1:00 </entry>
+        <entry>Central European Time</entry>
        </row>
        <row>
-        <entry>LIGT</entry>
-        <entry>+10:00</entry>
-        <entry>Melbourne, Australia</entry>
+        <entry>DNT</entry>
+        <entry>+1:00 </entry>
+        <entry>Dansk Normal Tid</entry>
        </row>
        <row>
-        <entry>MDT</entry>
-        <entry>-6:00</entry>
-        <entry>Mountain Daylight Time</entry>
+        <entry>DST</entry>
+        <entry>+1:00 </entry>
+        <entry>Dansk Standard Time (?)</entry>
        </row>
        <row>
-        <entry>MEST</entry>
-        <entry>+2:00</entry>
-        <entry>Middle Europe Summer Time</entry>
+        <entry>FST</entry>
+        <entry>+1:00 </entry>
+        <entry>French Summer Time</entry>
        </row>
        <row>
         <entry>MET</entry>
         <entry>+1:00</entry>
         <entry>Middle Europe Time</entry>
        </row>
-       <row>
-        <entry>METDST</entry>
-        <entry>+2:00</entry>
-        <entry>Middle Europe Daylight Time</entry>
-       </row>
        <row>
         <entry>MEWT</entry>
         <entry>+1:00</entry>
@@ -1480,149 +1475,154 @@ the time zone becomes GMT (on most systems anyway).
         <entry>Middle Europe Zone</entry>
        </row>
        <row>
-        <entry>MST</entry>
-        <entry>-7:00</entry>
-        <entry>Mountain Standard Time</entry>
-       </row>
-       <row>
-        <entry>MT</entry>
-        <entry>+8:30</entry>
-        <entry>Moluccas Time</entry>
+        <entry>NOR</entry>
+        <entry>+1:00</entry>
+        <entry>Norway Standard Time</entry>
        </row>
        <row>
-        <entry>NDT</entry>
-        <entry>-2:30</entry>
-        <entry>Newfoundland Daylight Time</entry>
+        <entry>SET</entry>
+        <entry>+1:00</entry>
+        <entry>Seychelles Time</entry>
        </row>
        <row>
-        <entry>NFT</entry>
-        <entry>-3:30</entry>
-        <entry>Newfoundland Standard Time</entry>
+        <entry>SWT</entry>
+        <entry>+1:00</entry>
+        <entry>Swedish Winter Time</entry>
        </row>
        <row>
-        <entry>NOR</entry>
+        <entry>WETDST</entry>
         <entry>+1:00</entry>
-        <entry>Norway Standard Time</entry>
+        <entry>Western Europe Daylight Savings Time</entry>
        </row>
        <row>
-        <entry>NST</entry>
-        <entry>-3:30</entry>
-        <entry>Newfoundland Standard Time</entry>
+        <entry>GMT</entry>
+        <entry>0:00</entry>
+        <entry>Greenwish Mean Time</entry>
        </row>
        <row>
-        <entry>NT</entry>
-        <entry>-11:00</entry>
-        <entry>Nome Time</entry>
+        <entry>WET</entry>
+        <entry>0:00</entry>
+        <entry>Western Europe</entry>
        </row>
        <row>
-        <entry>NZDT</entry>
-        <entry>+13:00</entry>
-        <entry>New Zealand Daylight Time</entry>
+        <entry>WAT</entry>
+        <entry>-1:00</entry>
+        <entry>West Africa Time</entry>
        </row>
        <row>
-        <entry>NZST</entry>
-        <entry>+12:00</entry>
-        <entry>New Zealand Std Time</entry>
+        <entry>NDT</entry>
+        <entry>-2:30</entry>
+        <entry>Newfoundland Daylight Time</entry>
        </row>
        <row>
-        <entry>NZT</entry>
-        <entry>+12:00</entry>
-        <entry>New Zealand Time</entry>
+        <entry>ADT</entry>
+        <entry>-03:00 </entry>
+        <entry>Atlantic Daylight Time</entry>
        </row>
        <row>
-        <entry>PDT</entry>
-        <entry>-7:00</entry>
-        <entry>Pacific Daylight Time</entry>
+        <entry>NFT</entry>
+        <entry>-3:30</entry>
+        <entry>Newfoundland Standard Time</entry>
        </row>
        <row>
-        <entry>PST</entry>
-        <entry>-8:00</entry>
-        <entry>Pacific Std Time</entry>
+        <entry>NST</entry>
+        <entry>-3:30</entry>
+        <entry>Newfoundland Standard Time</entry>
        </row>
        <row>
-        <entry>SADT</entry>
-        <entry>+10:30</entry>
-        <entry>South Australian Daylight Time</entry>
+        <entry>AST</entry>
+        <entry>-4:00 </entry>
+        <entry>Atlantic Std Time (Canada)</entry>
        </row>
        <row>
-        <entry>SAT</entry>
-        <entry>+9:30</entry>
-        <entry>South Australian Std Time</entry>
+        <entry>EDT</entry>
+        <entry>-4:00 </entry>
+        <entry>Eastern Daylight Time</entry>
        </row>
        <row>
-        <entry>SET</entry>
-        <entry>+1:00</entry>
-        <entry>Seychelles Time</entry>
+        <entry>ZP4</entry>
+        <entry>-4:00</entry>
+        <entry>GMT +4 hours</entry>
        </row>
        <row>
-        <entry>SST</entry>
-        <entry>+2:00</entry>
-        <entry>Swedish Summer Time</entry>
+        <entry>CDT</entry>
+        <entry>-5:00 </entry>
+        <entry>Central Daylight Time</entry>
        </row>
        <row>
-        <entry>SWT</entry>
-        <entry>+1:00</entry>
-        <entry>Swedish Winter Time</entry>
+        <entry>EST</entry>
+        <entry>-5:00 </entry>
+        <entry>Eastern Standard Time</entry>
        </row>
        <row>
-        <entry>WADT</entry>
-        <entry>+8:00</entry>
-        <entry>West Australian Daylight Time</entry>
+        <entry>ZP5</entry>
+        <entry>-5:00</entry>
+        <entry>GMT +5  hours</entry>
        </row>
        <row>
-        <entry>WAST</entry>
-        <entry>+7:00</entry>
-        <entry>West Australian Std Time</entry>
+        <entry>CST</entry>
+        <entry>-6:00 </entry>
+        <entry>Central Std Time</entry>
        </row>
        <row>
-        <entry>WAT</entry>
-        <entry>-1:00</entry>
-        <entry>West Africa Time</entry>
+        <entry>MDT</entry>
+        <entry>-6:00</entry>
+        <entry>Mountain Daylight Time</entry>
        </row>
        <row>
-        <entry>WDT</entry>
-        <entry>+9:00</entry>
-        <entry>West Australian Daylight Time</entry>
+        <entry>ZP6</entry>
+        <entry>-6:00</entry>
+        <entry>GMT +6  hours</entry>
        </row>
        <row>
-        <entry>WET</entry>
-        <entry>0:00</entry>
-        <entry>Western Europe</entry>
+        <entry>MST</entry>
+        <entry>-7:00</entry>
+        <entry>Mountain Standard Time</entry>
        </row>
        <row>
-        <entry>WETDST</entry>
-        <entry>+1:00</entry>
-        <entry>Western Europe Daylight Savings Time</entry>
+        <entry>PDT</entry>
+        <entry>-7:00</entry>
+        <entry>Pacific Daylight Time</entry>
        </row>
        <row>
-        <entry>WST</entry>
-        <entry>+8:00</entry>
-        <entry>West Australian Std Time</entry>
+        <entry>PST</entry>
+        <entry>-8:00</entry>
+        <entry>Pacific Std Time</entry>
        </row>
        <row>
         <entry>YDT</entry>
         <entry>-8:00</entry>
         <entry>Yukon Daylight Time</entry>
        </row>
+       <row>
+        <entry>HDT</entry>
+        <entry>-9:00</entry>
+        <entry>Hawaii/Alaska Daylight Time</entry>
+       </row>
        <row>
         <entry>YST</entry>
         <entry>-9:00</entry>
         <entry>Yukon Standard Time</entry>
        </row>
        <row>
-        <entry>ZP4</entry>
-        <entry>-4:00</entry>
-        <entry>GMT +4 hours</entry>
+        <entry>AHST</entry>
+        <entry>-10:00 </entry>
+        <entry>Alaska-Hawaii Std Time</entry>
        </row>
        <row>
-        <entry>ZP5</entry>
-        <entry>-5:00</entry>
-        <entry>GMT +5  hours</entry>
+        <entry>CAT</entry>
+        <entry>-10:00 </entry>
+        <entry>Central Alaska Time</entry>
        </row>
        <row>
-        <entry>ZP6</entry>
-        <entry>-6:00</entry>
-        <entry>GMT +6  hours</entry>
+        <entry>NT</entry>
+        <entry>-11:00</entry>
+        <entry>Nome Time</entry>
+       </row>
+       <row>
+        <entry>IDLW</entry>
+        <entry>-12:00</entry>
+        <entry>International Date Line, West</entry>
        </row>
        </tbody>
       </tgroup>
@@ -1633,17 +1633,21 @@ the time zone becomes GMT (on most systems anyway).
        then <literal>EST</literal> refers to Australia Eastern Std Time,
        which has an offset of +10:00 hours from UTC.
       </para>
-
-      <para>
-       It is interesting that Australian time zones and their naming variants
-       account for fully one quarter of all time zones in the 
-       <productname>Postgres</productname> time zone lookup table.
-      </para>
      </note>
+
+    <para>
+     Australian time zones and their naming variants
+     account for fully one quarter of all time zones in the 
+     <productname>Postgres</productname> time zone lookup table.
     </para>
 
     <procedure>
      <title>Date/Time Input Interpretation</title>
+
+     <para>
+      The date/time types are all decoded using a common set of routines.
+     </para>
+
      <step>
       <para>
        Break the input string into tokens and categorize each token as
@@ -1717,48 +1721,89 @@ the time zone becomes GMT (on most systems anyway).
 
      <step>
       <para>
-       The token is a number or number field. If there are more than 4 digits, 
+       The token is a number or number field.
+       If there are more than 4 digits, 
        and if no other date fields have been previously read, then interpret 
-       as a "concatenated date".
+       as a "concatenated date" (e.g. <literal>19990118</literal>).
       </para>
 
       <substeps>
        <step>
-       <para>If there </para>
+       <para>
+        If there are more than 4 digits, 
+        and if no other date fields have been previously read, then interpret 
+        as a "concatenated date" (e.g. <literal>19990118</literal>).
+       </para>
        </step>
-      </substeps>
-     </step>
 
-     <step>
-      <para>
-      </para>
-     </step>
+       <step>
+       <para>
+        If three digits and a year has already been decoded, then interpret as day of year.
+       </para>
+       </step>
 
-     <step>
-      <para>
-      </para>
-     </step>
+       <step>
+       <para>
+        If longer than two digits, then interpret as a year.
+       </para>
+       </step>
 
-     <step>
-      <para>
-      </para>
+       <step>
+       <para>
+        If in European date mode, and if the day field has not yet been read,
+        and if the value is less than or equal to 31, then interpret as a day.
+       </para>
+       </step>
+
+       <step>
+       <para>
+        If in non-European (US) date mode, and if the month field has not yet been read,
+        and if the value is less than or equal to 12, then interpret as a month.
+       </para>
+       </step>
+
+       <step>
+       <para>
+        If the day field has not yet been read,
+        and if the value is less than or equal to 31, then interpret as a month.
+       </para>
+       </step>
+
+       <step>
+       <para>
+        If the month field has not yet been read,
+        and if the value is less than or equal to 12, then interpret as a month.
+       </para>
+       </step>
+
+       <step>
+       <para>
+        Otherwise, interpret as a year.
+       </para>
+       </step>
+      </substeps>
      </step>
 
      <step>
       <para>
+       If BC has been specified, negate the year and offset by one 
+       (there is no year zero in the Gregorian calendar).
       </para>
      </step>
 
      <step>
       <para>
+       If BC was not specified, and if the year field was two digits in length, then
+       adjust the year to 4 digits. If the field was less than 70, then add 2000;
+       otherwise, add 1900.
       </para>
      </step>
 
     </procedure>
-</sect2>
+   </sect2>
 
-<sect2>
-<title>datetime</title>
+   <sect2>
+    <title>datetime</title>
 
 <para>
 General-use date and time is input using a wide range of
@@ -2377,7 +2422,7 @@ the bits part.
 <!-- Keep this comment at the end of the file
 Local variables:
 mode: sgml
-sgml-omittag:t
+sgml-omittag:nil
 sgml-shorttag:t
 sgml-minimize-attributes:nil
 sgml-always-quote-attributes:t