Add more complete details on date/time keywords and parsing rules.

Move some tabular information on these from the chapter on data types to
 the appendix on dates and times.

diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index 62117820f740a2d86d90070fdbfb453bf5026cfe..daabb71fb629e33b43ace94391c5cdf8601a0110 100644 (file)
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -1,5 +1,5 @@
 
 
  
@@ -1346,29 +1346,35 @@ SELECT b, char_length(b) FROM test2;
 
    
     Time zones, and time-zone conventions, are influenced by
-    political decisions, not just geometry. Time zones around the
+    political decisions, not just earth geometry. Time zones around the
     world became somewhat standardized during the 1900's,
     but continue to be prone to arbitrary changes.
     PostgreSQL uses your operating
-    system's underlying features to provide time-zone
+    system's underlying features to provide output time-zone
     support, and these systems usually contain information for only
     the time period 1902 through 2038 (corresponding to the full
     range of conventional Unix system time).
-    timestamp with time zone will use time zone
-    information only within that year range, and assumes that times
-    are in UTC outside that range.
+    timestamp with time zone and time with time
+     zone will use time zone
+    information only within that year range, and assume that times
+    outside that range are in UTC.
    
 
    
-    To ensure compatibility to earlier versions of
-    PostgreSQL 
-    we continue to provide datetime
+    To ensure an upgrade path from versions of
+    PostgreSQL earlier than 7.0,
+    we recognize datetime
     (equivalent to timestamp) and
-    timespan (equivalent to interval),
-    however support for these is now restricted to having an
+    timespan (equivalent to interval).
+    These types are
+    now restricted to having an
     implicit translation to timestamp and
-    interval, and these name mappings will be removed in
-    the next version.
+    interval, and 
+    support for these will be removed in the next release of
+    PostgreSQL (likely named 7.3).
+   
+
+   
     The types abstime
     and reltime are lower precision types which are used internally.
     You are discouraged from using any of these types in new
@@ -1402,7 +1408,8 @@ SELECT b, char_length(b) FROM test2;
      SQL standard requires.
      See 
      for the exact parsing rules of date/time input and for the
-     recognized time zones. 
+     recognized text fields including months, days of the week, and
+     time zones. 
     
 
     
@@ -1431,7 +1438,7 @@ SELECT b, char_length(b) FROM test2;
     
  
     
-     The following are possible inputs for the date type.
+     The following are some possible inputs for the date type.
 
      
       Date Input
@@ -1480,118 +1487,12 @@ SELECT b, char_length(b) FROM test2;
     Year and day of year
    
    
-    January 8, 99 BC
-    Year 99 before the Common Era
-   
-       
-      
-     
-    
-
-    
-     
-      Month Abbreviations
-      
-       
-   
-    Month
-    Abbreviations
-   
-       
-       
-   
-    April
-    Apr
-   
-   
-    August
-    Aug
-   
-   
-    December
-    Dec
-   
-   
-    February
-    Feb
-   
-   
-    January
-    Jan
-   
-   
-    July
-    Jul
-   
-   
-    June
-    Jun
-   
-   
-    March
-    Mar
-   
-   
-    November
-    Nov
-   
-   
-    October
-    Oct
-   
-   
-    September
-    Sep, Sept
-   
-       
-      
-     
-
-     
-      
-       The month May has no explicit abbreviation, for obvious reasons.
-      
-     
-    
-
-    
-     
-      Day of the Week Abbreviations
-      
-       
-   
-    Day
-    Abbreviation
+    J2451187
+    Julian day
    
-       
-       
    
-    Sunday
-    Sun
-   
-   
-    Monday
-    Mon
-   
-   
-    Tuesday
-    Tue, Tues
-   
-   
-    Wednesday
-    Wed, Weds
-   
-   
-    Thursday
-    Thu, Thur, Thurs
-   
-   
-    Friday
-    Fri
-   
-   
-    Saturday
-    Sat
+    January 8, 99 BC
+    Year 99 before the Common Era
    
        
       
@@ -1655,14 +1556,6 @@ SELECT b, char_length(b) FROM test2;
      04:05 PM
      Same as 16:05; input hour must be <= 12
     
-    
-     z
-     Same as 00:00:00
-    
-    
-     zulu
-     Same as 00:00:00
-    
     
      allballs
      Same as 00:00:00

diff --git a/doc/src/sgml/datetime.sgml b/doc/src/sgml/datetime.sgml
index cc1f121622fa8582d56b812ae1bd32117e9d1bb8..32ddd2365b4c22a0b7f677e684e6d93ffc60406d 100644 (file)
--- a/doc/src/sgml/datetime.sgml
+++ b/doc/src/sgml/datetime.sgml
@@ -1,11 +1,197 @@
 
 
  
   Date/Time Support
 
+  
+   PostgreSQL uses an internal heuristic
+   parser for all date/time support. Dates and times are input as
+   strings, and are broken up into distinct fields with a preliminary
+   determination of what kind of information may be in the
+   field. Each field is interpreted and either assigned a numeric
+   value, ignored, or rejected.
+   The parser contains internal lookup tables for all textual fields,
+   including months, days of the week, and time
+   zones.
+  
+
+  
+   This appendix includes information on the content of these
+   lookup tables and describes the steps used by the parser to decode
+   dates and times.
+  
+
+  
+   Date/Time Keywords
+
+   
+    
+     Month Abbreviations
+     
+      
+       
+   Month
+   Abbreviations
+       
+      
+      
+       
+   April
+   Apr
+       
+       
+   August
+   Aug
+       
+       
+   December
+   Dec
+       
+       
+   February
+   Feb
+       
+       
+   January
+   Jan
+       
+       
+   July
+   Jul
+       
+       
+   June
+   Jun
+       
+       
+   March
+   Mar
+       
+       
+   November
+   Nov
+       
+       
+   October
+   Oct
+       
+       
+   September
+   Sep, Sept
+       
+      
+     
+    
+
+    
+     
+      The month May has no explicit abbreviation, for obvious reasons.
+     
+    
+   
+
+    
+     
+      Day of the Week Abbreviations
+      
+       
+   
+    Day
+    Abbreviation
+   
+       
+       
+   
+    Sunday
+    Sun
+   
+   
+    Monday
+    Mon
+   
+   
+    Tuesday
+    Tue, Tues
+   
+   
+    Wednesday
+    Wed, Weds
+   
+   
+    Thursday
+    Thu, Thur, Thurs
+   
+   
+    Friday
+    Fri
+   
+   
+    Saturday
+    Sat
+   
+       
+      
+     
+    
+
+   
+    
+     <productname>PostgreSQL</productname> Field Modifiers
+     Field Modifiers
+     
+      
+       
+   Identifier
+   Description
+       
+      
+      
+       
+   ABSTIME
+   Keyword ignored
+       
+       
+   AM
+   Time is before 12:00
+       
+       
+   AT
+   Keyword ignored
+       
+       
+   JULIAN, JD, J
+   Next field is Julian Day
+       
+       
+   ON
+   Keyword ignored
+       
+       
+   PM
+   Time is on or after after 12:00
+       
+       
+   T
+   Next field is time
+       
+      
+     
+    
+   
+
+   
+    The keyword ABSTIME is ignored for historical
+    reasons; in very old releases of
+    PostgreSQL invalid ABSTIME
+    fields were emitted as Invalid Abstime. This is no
+    longer the case however and this keyword will likely be dropped in
+    a future release.
+   
+  
+
   
    Time Zones
 
@@ -19,6 +205,15 @@ Date/time details
     system interface to provide access to general, cross-timezone
     information. The underlying OS is used to
     provide time zone information for output, however.
+   
+
+   
+    The following table of time zones recognized by
+    PostgreSQL is organized by time
+    zone offset from UTC, rather than alphabetically; this is intended
+    to faciliate
+    matching local usage with recognized abreviations for cases where
+    these might differ.
 
     
      <productname>PostgreSQL</productname> Recognized Time Zones
@@ -360,6 +555,26 @@ Date/time details
    +00:00
    Greenwich Mean Time
        
+       
+   UT
+   +00:00
+   Universal Time
+       
+       
+   UTC
+   +00:00
+   Universal Time, Coordinated
+       
+       
+   Z
+   +00:00
+   Same as UTC
+       
+       
+   ZULU
+   +00:00
+   Same as UTC
+       
        
    WET
    +00:00
@@ -603,13 +818,15 @@ Date/time details
      
       
        
-   If the token contains a colon (":"), this is a time string.
+   If the numeric token contains a colon (":"), this is a time
+    string. Include all subsequent digits and colons.
        
       
 
       
        
-   If the token contains a dash ("-"), slash ("/"), or dot ("."),
+   If the numeric token contains a dash ("-"), slash ("/"), or
+    two or more dots ("."),
    this is a date string which may have a text month.
        
       
@@ -617,7 +834,8 @@ Date/time details
       
        
    If the token is numeric only, then it is either a single field
-   or an ISO-8601 concatenated date (e.g. 19990113 for January 13, 1999)
+   or an ISO-8601 concatenated date
+    (e.g. 19990113 for January 13, 1999)
    or time (e.g. 141516 for 14:15:16).
        
       
@@ -689,6 +907,13 @@ Date/time details
        
       
       
+      
+       
+   If four or six digits and a year has already been read, then
+    interpret as a time. 
+       
+      
+
       
        
    If four or more digits, then interpret as a year.
@@ -732,10 +957,10 @@ Date/time details
 
     
      
-      If BC has been specified, negate the year and offset by one for
+      If BC has been specified, negate the year and add one for
       internal storage
       (there is no year zero in the Gregorian calendar, so numerically
-      1BC becomes year zero).
+      1BC becomes year zero).