docs: improve AT TIME ZONE description

The previous description was unclear.  Also add a third example, change
use of time zone acronyms to more verbose descriptions, and add a
mention that using 'time' with AT TIME ZONE uses the current time zone
rules.

Backpatch-through: 9.3

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index bb794e044f469f494d7900b386e8b1a0e259deab..df847c0df6c531195106daaa0f2b81b34d371855 100644 (file)
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -8082,10 +8082,11 @@ SELECT date_trunc('year', TIMESTAMP '2001-02-16 20:38:40');
    
 
    
-    The AT TIME ZONE construct allows conversions
-    of time stamps to different time zones.  
-    linkend="functions-datetime-zoneconvert-table"/> shows its
-    variants.
+    The AT TIME ZONE converts time
+    stamp without time zone to/from
+    time stamp with time zone, and
+    time values to different time zones. 
+    linkend="functions-datetime-zoneconvert-table"/> shows its variants.
    
 
     
@@ -8130,24 +8131,33 @@ SELECT date_trunc('year', TIMESTAMP '2001-02-16 20:38:40');
 
    
     In these expressions, the desired time zone zone can be
-    specified either as a text string (e.g., 'PST')
+    specified either as a text string (e.g., 'America/Los_Angeles')
     or as an interval (e.g., INTERVAL '-08:00').
     In the text case, a time zone name can be specified in any of the ways
     described in .
    
 
    
-    Examples (assuming the local time zone is PST8PDT):
+    Examples (assuming the local time zone is America/Los_Angeles):
 
-SELECT TIMESTAMP '2001-02-16 20:38:40' AT TIME ZONE 'MST';
+SELECT TIMESTAMP '2001-02-16 20:38:40' AT TIME ZONE 'America/Denver';
 Result: 2001-02-16 19:38:40-08
 
-SELECT TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40-05' AT TIME ZONE 'MST';
+SELECT TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40-05' AT TIME ZONE 'America/Denver';
 Result: 2001-02-16 18:38:40
+
+SELECT TIMESTAMP '2001-02-16 20:38:40-05' AT TIME ZONE 'Asia/Tokyo' AT TIME ZONE 'America/Chicago';
+Result: 2001-02-16 05:38:40
 
-    The first example takes a time stamp without time zone and interprets it as MST time
-    (UTC-7), which is then converted to PST (UTC-8) for display.  The second example takes
-    a time stamp specified in EST (UTC-5) and converts it to local time in MST (UTC-7).
+    The first example adds a time zone to a value that lacks it, and
+    displays the value using the current TimeZone
+    setting.  The second example shifts the time stamp with time zone value
+    to the specified time zone, and returns the value without a time zone.
+    This allows storage and display of values different from the current
+    TimeZone setting.  The third example converts
+    Tokyo time to Chicago time.   Converting time
+    values to other time zones uses the currently active time zone rules
+    since no date is supplied.