Doc: add info about timestamps with fractional-minute UTC offsets.

tglsfdc · tglsfdc · commit c1123be619fc · 2021-07-06T10:34:51.000-04:00
Our code has supported fractional-minute UTC offsets for ages, but there was no mention of the possibility in the main docs, and only a very indirect reference in Appendix B. Improve that. Discussion: https://postgr.es/m/162543102827.697.5755498651217979813@wrigleys.postgresql.org
diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
@@ -1950,19 +1950,27 @@ MINUTE TO SECOND
          </row>
          <row>
           <entry><literal>04:05:06.789-8</literal></entry>
-          <entry>ISO 8601</entry>
+          <entry>ISO 8601, with time zone as UTC offset</entry>
          </row>
          <row>
           <entry><literal>04:05:06-08:00</literal></entry>
-          <entry>ISO 8601</entry>
+          <entry>ISO 8601, with time zone as UTC offset</entry>
          </row>
          <row>
           <entry><literal>04:05-08:00</literal></entry>
-          <entry>ISO 8601</entry>
+          <entry>ISO 8601, with time zone as UTC offset</entry>
          </row>
          <row>
           <entry><literal>040506-08</literal></entry>
-          <entry>ISO 8601</entry>
+          <entry>ISO 8601, with time zone as UTC offset</entry>
+         </row>
+         <row>
+          <entry><literal>040506+0730</literal></entry>
+          <entry>ISO 8601, with fractional-hour time zone as UTC offset</entry>
+         </row>
+         <row>
+          <entry><literal>040506+07:30:00</literal></entry>
+          <entry>UTC offset specified to seconds (not allowed in ISO 8601)</entry>
          </row>
          <row>
           <entry><literal>04:05:06 PST</literal></entry>
@@ -1998,25 +2006,29 @@ MINUTE TO SECOND
           <entry><literal>PST8PDT</literal></entry>
           <entry>POSIX-style time zone specification</entry>
          </row>
+         <row>
+          <entry><literal>-8:00:00</literal></entry>
+          <entry>UTC offset for PST</entry>
+         </row>
          <row>
           <entry><literal>-8:00</literal></entry>
-          <entry>ISO-8601 offset for PST</entry>
+          <entry>UTC offset for PST (ISO 8601 extended format)</entry>
          </row>
          <row>
           <entry><literal>-800</literal></entry>
-          <entry>ISO-8601 offset for PST</entry>
+          <entry>UTC offset for PST (ISO 8601 basic format)</entry>
          </row>
          <row>
           <entry><literal>-8</literal></entry>
-          <entry>ISO-8601 offset for PST</entry>
+          <entry>UTC offset for PST (ISO 8601 basic format)</entry>
          </row>
          <row>
           <entry><literal>zulu</literal></entry>
           <entry>Military abbreviation for UTC</entry>
          </row>
          <row>
           <entry><literal>z</literal></entry>
-          <entry>Short form of <literal>zulu</literal></entry>
+          <entry>Short form of <literal>zulu</literal> (also in ISO 8601)</entry>
          </row>
         </tbody>
        </tgroup>
@@ -2354,6 +2366,24 @@ January 8 04:05:06 1999 PST
       </tgroup>
      </table>
 
+    <para>
+     In the <acronym>ISO</acronym> style, the time zone is always shown as
+     a signed numeric offset from UTC, with positive sign used for zones
+     east of Greenwich.  The offset will be shown
+     as <replaceable>hh</replaceable> (hours only) if it is an integral
+     number of hours, else
+     as <replaceable>hh</replaceable>:<replaceable>mm</replaceable> if it
+     is an integral number of minutes, else as
+     <replaceable>hh</replaceable>:<replaceable>mm</replaceable>:<replaceable>ss</replaceable>.
+     (The third case is not possible with any modern time zone standard,
+     but it can appear when working with timestamps that predate the
+     adoption of standardized time zones.)
+     In the other date styles, the time zone is shown as an alphabetic
+     abbreviation if one is in common use in the current zone.  Otherwise
+     it appears as a signed numeric offset in ISO 8601 basic format
+     (<replaceable>hh</replaceable> or <replaceable>hhmm</replaceable>).
+    </para>
+
     <para>
      The date/time style can be selected by the user using the
      <command>SET datestyle</command> command, the <xref
