Skip to content

Commit ab2e199

Browse files
tglsfdctglsfdc
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/162543102827.697.5755498651217979813@wrigleys.postgresql.org
1 parent 8aafb02 commit ab2e199

File tree

1 file changed

+38
-8
lines changed

1 file changed

+38
-8
lines changed

‎doc/src/sgml/datatype.sgml

+38-8
Original file line numberDiff line numberDiff line change
@@ -2020,19 +2020,27 @@ MINUTE TO SECOND
20202020
</row>
20212021
<row>
20222022
<entry><literal>04:05:06.789-8</literal></entry>
2023-
<entry>ISO 8601</entry>
2023+
<entry>ISO 8601, with time zone as UTC offset</entry>
20242024
</row>
20252025
<row>
20262026
<entry><literal>04:05:06-08:00</literal></entry>
2027-
<entry>ISO 8601</entry>
2027+
<entry>ISO 8601, with time zone as UTC offset</entry>
20282028
</row>
20292029
<row>
20302030
<entry><literal>04:05-08:00</literal></entry>
2031-
<entry>ISO 8601</entry>
2031+
<entry>ISO 8601, with time zone as UTC offset</entry>
20322032
</row>
20332033
<row>
20342034
<entry><literal>040506-08</literal></entry>
2035-
<entry>ISO 8601</entry>
2035+
<entry>ISO 8601, with time zone as UTC offset</entry>
2036+
</row>
2037+
<row>
2038+
<entry><literal>040506+0730</literal></entry>
2039+
<entry>ISO 8601, with fractional-hour time zone as UTC offset</entry>
2040+
</row>
2041+
<row>
2042+
<entry><literal>040506+07:30:00</literal></entry>
2043+
<entry>UTC offset specified to seconds (not allowed in ISO 8601)</entry>
20362044
</row>
20372045
<row>
20382046
<entry><literal>04:05:06 PST</literal></entry>
@@ -2068,25 +2076,29 @@ MINUTE TO SECOND
20682076
<entry><literal>PST8PDT</literal></entry>
20692077
<entry>POSIX-style time zone specification</entry>
20702078
</row>
2079+
<row>
2080+
<entry><literal>-8:00:00</literal></entry>
2081+
<entry>UTC offset for PST</entry>
2082+
</row>
20712083
<row>
20722084
<entry><literal>-8:00</literal></entry>
2073-
<entry>ISO-8601 offset for PST</entry>
2085+
<entry>UTC offset for PST (ISO 8601 extended format)</entry>
20742086
</row>
20752087
<row>
20762088
<entry><literal>-800</literal></entry>
2077-
<entry>ISO-8601 offset for PST</entry>
2089+
<entry>UTC offset for PST (ISO 8601 basic format)</entry>
20782090
</row>
20792091
<row>
20802092
<entry><literal>-8</literal></entry>
2081-
<entry>ISO-8601 offset for PST</entry>
2093+
<entry>UTC offset for PST (ISO 8601 basic format)</entry>
20822094
</row>
20832095
<row>
20842096
<entry><literal>zulu</literal></entry>
20852097
<entry>Military abbreviation for UTC</entry>
20862098
</row>
20872099
<row>
20882100
<entry><literal>z</literal></entry>
2089-
<entry>Short form of <literal>zulu</literal></entry>
2101+
<entry>Short form of <literal>zulu</literal> (also in ISO 8601)</entry>
20902102
</row>
20912103
</tbody>
20922104
</tgroup>
@@ -2437,6 +2449,24 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02'
24372449
</tgroup>
24382450
</table>
24392451

2452+
<para>
2453+
In the <acronym>ISO</acronym> style, the time zone is always shown as
2454+
a signed numeric offset from UTC, with positive sign used for zones
2455+
east of Greenwich. The offset will be shown
2456+
as <replaceable>hh</replaceable> (hours only) if it is an integral
2457+
number of hours, else
2458+
as <replaceable>hh</replaceable>:<replaceable>mm</replaceable> if it
2459+
is an integral number of minutes, else as
2460+
<replaceable>hh</replaceable>:<replaceable>mm</replaceable>:<replaceable>ss</replaceable>.
2461+
(The third case is not possible with any modern time zone standard,
2462+
but it can appear when working with timestamps that predate the
2463+
adoption of standardized time zones.)
2464+
In the other date styles, the time zone is shown as an alphabetic
2465+
abbreviation if one is in common use in the current zone. Otherwise
2466+
it appears as a signed numeric offset in ISO 8601 basic format
2467+
(<replaceable>hh</replaceable> or <replaceable>hhmm</replaceable>).
2468+
</para>
2469+
24402470
<para>
24412471
The date/time style can be selected by the user using the
24422472
<command>SET datestyle</command> command, the <xref

0 commit comments

Comments
 (0)