doc: show how interval's 3 unit buckets behave using EXTRACT()

This clarifies when justify_days() and justify_hours() are useful.
Paragraph moved too.

Reported-by: [email protected]
Discussion: https://postgr.es/m/152698651482.26744.15456677499485530703@wrigleys.postgresql.org

Backpatch-through: 9.3

diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index 67bae322878486345b9ae704e093e6c086b581ba..cc54cc8a583d06d3824afad861d0418eb508255b 100644 (file)
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -2670,19 +2670,6 @@ P  years-months-
      to each field if any field is negative.
     
 
-    
-     Internally interval values are stored as months, days,
-     and seconds. This is done because the number of days in a month
-     varies, and a day can have 23 or 25 hours if a daylight savings
-     time adjustment is involved.  The months and days fields are integers
-     while the seconds field can store fractions.  Because intervals are
-     usually created from constant strings or timestamp subtraction,
-     this storage method works well in most cases. Functions
-     justify_days and justify_hours are
-     available for adjusting days and hours that overflow their normal
-     ranges.
-    
-
     
      In the verbose input format, and in some fields of the more compact
      input formats, field values can have fractional parts; for example
@@ -2734,6 +2721,33 @@ P  years-months-
       
      
 
+    
+     Internally interval values are stored as months, days,
+     and seconds. This is done because the number of days in a month
+     varies, and a day can have 23 or 25 hours if a daylight savings
+     time adjustment is involved.  The months and days fields are integers
+     while the seconds field can store fractions.  Because intervals are
+     usually created from constant strings or timestamp subtraction,
+     this storage method works well in most cases, but can cause unexpected
+     results:
+
+
+SELECT EXTRACT(hours from '80 minutes'::interval);
+ date_part
+-----------
+         1
+
+SELECT EXTRACT(days from '80 hours'::interval);
+ date_part
+-----------
+         0
+
+
+     Functions justify_days and
+     justify_hours are available for adjusting days
+     and hours that overflow their normal ranges.
+    
+