postgres.git / summary / log / commit / refs
commit 94911ec28f01d1babe61053977ca9f057983cb21
Author: Tom Lane <tgl@sss.pgh.pa.us>
Date: Tue Jul 06 14:34:51 2021 +0000
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
doc/src/sgml/datatype.sgml | 46 ++++++++++++++++++++++++++++++++++++++--------
1 file changed, 38 insertions(+), 8 deletions(-)
diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index c473d6a7461..e016f96fb4b 100644
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -2020,19 +2020,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>
@@ -2068,17 +2076,21 @@ 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>
@@ -2086,7 +2098,7 @@ MINUTE TO SECOND
</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>
@@ -2437,6 +2449,24 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02'
</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
[parent: 07f1e06964ad]