doc: add example of sign mismatch with POSIX/ISO-8601 time zones

Author: Laurenz Albe

Discussion: https://postgr.es/m/eb4d1e15c6822c1937be1491118500dd9201492f[email protected]

diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index b20241feb5022ef9030e314f455805c954ef44a7..87679dc4a11dd8375dfd45fed1709b8f7cdbb29b 100644 (file)
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -2682,6 +2682,14 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02'
      savings was nominally in effect on that date.
     </para>
 
+    <note>
+     <para>
+      The sign in POSIX-style time zone specifications has the opposite meaning
+      of the sign in ISO-8601 datetime values.  For example, the POSIX time zone
+      for <literal>2014-06-04 12:00+04</literal> would be UTC-4.
+     </para>
+    </note>
+
     <para>
      To complicate matters, some jurisdictions have used the same timezone
      abbreviation to mean different UTC offsets at different times; for

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 7efc81936ab647cf5fc4714c602c0bd655009a31..2548a57df31a415aa94115dee0a6b104613924ca 100644 (file)
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -11006,6 +11006,8 @@ SELECT TIMESTAMP '2001-02-16 20:38:40' AT TIME ZONE 'Asia/Tokyo' AT TIME ZONE 'A
 <lineannotation>Result: </lineannotation><computeroutput>2001-02-16 05:38:40</computeroutput>
 SELECT TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40-05' AT LOCAL;
 <lineannotation>Result: </lineannotation><computeroutput>2001-02-16 17:38:40</computeroutput>
+SELECT TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40-05' AT TIME ZONE '+05';
+<lineannotation>Result: </lineannotation><computeroutput>2001-02-16 20:38:40</computeroutput>
 SELECT TIME WITH TIME ZONE '20:38:40-05' AT LOCAL;
 <lineannotation>Result: </lineannotation><computeroutput>17:38:40</computeroutput>
 </screen>
@@ -11018,11 +11020,14 @@ SELECT TIME WITH TIME ZONE '20:38:40-05' AT LOCAL;
     Tokyo time to Chicago time.  The fourth example shifts the time stamp
     with time zone value to the time zone currently specified by the
     <varname>TimeZone</varname> setting and returns the value without a
-    time zone.
+    time zone.  The fifth example demonstrates that the sign in a POSIX-style
+    time zone specification has the opposite meaning of the sign in an
+    ISO-8601 datetime literal, as described in <xref linkend="datatype-timezones"/>
+    and <xref linkend="datetime-appendix"/>.
    </para>
 
    <para>
-    The fifth example is a cautionary tale. Due to the fact that there is no
+    The sixth example is a cautionary tale. Due to the fact that there is no
     date associated with the input value, the conversion is made using the
     current date of the session. Therefore, this static example may show a wrong
     result depending on the time of the year it is viewed because