<!-- doc/src/sgml/datetime.sgml -->

 <appendix id="datetime-appendix">
  <title>Date/Time Support</title>

  <para>
   <productname>PostgreSQL</productname> uses an internal heuristic
   parser for all date/time input support. Dates and times are input as
   strings, and are broken up into distinct fields with a preliminary
   determination of what kind of information can 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.
  </para>

  <para>
   This appendix includes information on the content of these
   lookup tables and describes the steps used by the parser to decode
   dates and times.
  </para>

  <sect1 id="datetime-input-rules">
   <title>Date/Time Input Interpretation</title>

   <para>
    Date/time input strings are decoded using the following procedure.
   </para>

   <procedure>
    <step>
     <para>
      Break the input string into tokens and categorize each token as
      a string, time, time zone, or number.
     </para>

     <substeps>
      <step>
       <para>
        If the numeric token contains a colon (<literal>:</literal>), this is
        a time string. Include all subsequent digits and colons.
       </para>
      </step>

      <step>
       <para>
        If the numeric token contains a dash (<literal>-</literal>), slash
        (<literal>/</literal>), or two or more dots (<literal>.</literal>), this is
        a date string which might have a text month.  If a date token has
        already been seen, it is instead interpreted as a time zone
        name (e.g., <literal>America/New_York</literal>).
       </para>
      </step>

      <step>
       <para>
        If the token is numeric only, then it is either a single field
        or an ISO 8601 concatenated date (e.g.,
        <literal>19990113</literal> for January 13, 1999) or time
        (e.g., <literal>141516</literal> for 14:15:16).
       </para>
      </step>

      <step>
       <para>
        If the token starts with a plus (<literal>+</literal>) or minus
        (<literal>-</literal>), then it is either a numeric time zone or a special
        field.
       </para>
      </step>
     </substeps>
    </step>

    <step>
     <para>
      If the token is an alphabetic string, match up with possible strings:
     </para>

     <substeps>
      <step>
       <para>
        See if the token matches any known time zone abbreviation.
        These abbreviations are determined by the configuration settings
        described in <xref linkend="datetime-config-files"/>.
       </para>
      </step>

      <step>
       <para>
        If not found, search an internal table to match
        the token as either a special string (e.g., <literal>today</literal>),
        day (e.g., <literal>Thursday</literal>),
        month (e.g., <literal>January</literal>),
        or noise word (e.g., <literal>at</literal>, <literal>on</literal>).
       </para>
      </step>

      <step>
       <para>
        If still not found, throw an error.
       </para>
      </step>
     </substeps>
    </step>

    <step>
     <para>
      When the token is a number or number field:
     </para>

     <substeps>
      <step>
       <para>
        If there are eight or six digits,
        and if no other date fields have been previously read, then interpret
        as a <quote>concatenated date</quote> (e.g.,
        <literal>19990118</literal> or <literal>990118</literal>).
        The interpretation is <literal>YYYYMMDD</literal> or <literal>YYMMDD</literal>.
       </para>
      </step>

      <step>
       <para>
        If the token is three digits
        and a year has already been read, then interpret as day of year.
       </para>
      </step>

      <step>
       <para>
        If four or six digits and a year has already been read, then
        interpret as a time (<literal>HHMM</literal>