Skip to content

Commit eda3b45

Browse files
committed
Doc: add info about timestamps with fractional-minute UTC offsets.
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/[email protected]
1 parent 3edc2db commit eda3b45

File tree

1 file changed

+38
-8
lines changed

1 file changed

+38
-8
lines changed

doc/src/sgml/datatype.sgml

Lines changed: 38 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1943,19 +1943,27 @@ MINUTE TO SECOND
19431943
</row>
19441944
<row>
19451945
<entry><literal>04:05:06.789-8</literal></entry>
1946-
<entry>ISO 8601</entry>
1946+
<entry>ISO 8601, with time zone as UTC offset</entry>
19471947
</row>
19481948
<row>
19491949
<entry><literal>04:05:06-08:00</literal></entry>
1950-
<entry>ISO 8601</entry>
1950+
<entry>ISO 8601, with time zone as UTC offset</entry>
19511951
</row>
19521952
<row>
19531953
<entry><literal>04:05-08:00</literal></entry>
1954-
<entry>ISO 8601</entry>
1954+
<entry>ISO 8601, with time zone as UTC offset</entry>
19551955
</row>
19561956
<row>
19571957
<entry><literal>040506-08</literal></entry>
1958-
<entry>ISO 8601</entry>
1958+
<entry>ISO 8601, with time zone as UTC offset</entry>
1959+
</row>
1960+
<row>
1961+
<entry><literal>040506+0730</literal></entry>
1962+
<entry>ISO 8601, with fractional-hour time zone as UTC offset</entry>
1963+
</row>
1964+
<row>
1965+
<entry><literal>040506+07:30:00</literal></entry>
1966+
<entry>UTC offset specified to seconds (not allowed in ISO 8601)</entry>
19591967
</row>
19601968
<row>
19611969
<entry><literal>04:05:06 PST</literal></entry>
@@ -1991,25 +1999,29 @@ MINUTE TO SECOND
19911999
<entry><literal>PST8PDT</literal></entry>
19922000
<entry>POSIX-style time zone specification</entry>
19932001
</row>
2002+
<row>
2003+
<entry><literal>-8:00:00</literal></entry>
2004+
<entry>UTC offset for PST</entry>
2005+
</row>
19942006
<row>
19952007
<entry><literal>-8:00</literal></entry>
1996-
<entry>ISO-8601 offset for PST</entry>
2008+
<entry>UTC offset for PST (ISO 8601 extended format)</entry>
19972009
</row>
19982010
<row>
19992011
<entry><literal>-800</literal></entry>
2000-
<entry>ISO-8601 offset for PST</entry>
2012+
<entry>UTC offset for PST (ISO 8601 basic format)</entry>
20012013
</row>
20022014
<row>
20032015
<entry><literal>-8</literal></entry>
2004-
<entry>ISO-8601 offset for PST</entry>
2016+
<entry>UTC offset for PST (ISO 8601 basic format)</entry>
20052017
</row>
20062018
<row>
20072019
<entry><literal>zulu</literal></entry>
20082020
<entry>Military abbreviation for UTC</entry>
20092021
</row>
20102022
<row>
20112023
<entry><literal>z</literal></entry>
2012-
<entry>Short form of <literal>zulu</literal></entry>
2024+
<entry>Short form of <literal>zulu</literal> (also in ISO 8601)</entry>
20132025
</row>
20142026
</tbody>
20152027
</tgroup>
@@ -2347,6 +2359,24 @@ January 8 04:05:06 1999 PST
23472359
</tgroup>
23482360
</table>
23492361

2362+
<para>
2363+
In the <acronym>ISO</acronym> style, the time zone is always shown as
2364+
a signed numeric offset from UTC, with positive sign used for zones
2365+
east of Greenwich. The offset will be shown
2366+
as <replaceable>hh</replaceable> (hours only) if it is an integral
2367+
number of hours, else
2368+
as <replaceable>hh</replaceable>:<replaceable>mm</replaceable> if it
2369+
is an integral number of minutes, else as
2370+
<replaceable>hh</replaceable>:<replaceable>mm</replaceable>:<replaceable>ss</replaceable>.
2371+
(The third case is not possible with any modern time zone standard,
2372+
but it can appear when working with timestamps that predate the
2373+
adoption of standardized time zones.)
2374+
In the other date styles, the time zone is shown as an alphabetic
2375+
abbreviation if one is in common use in the current zone. Otherwise
2376+
it appears as a signed numeric offset in ISO 8601 basic format
2377+
(<replaceable>hh</replaceable> or <replaceable>hhmm</replaceable>).
2378+
</para>
2379+
23502380
<para>
23512381
The date/time style can be selected by the user using the
23522382
<command>SET datestyle</command> command, the <xref

0 commit comments

Comments
 (0)