Docs: add paragraph about date/timestamp subtraction

per suggestion from Francisco Olart

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 425544ae509f8bd88567a13627ebee6950f4f6d1..a411f866a041795df61a4e58c689582c3069a14c 100644 (file)
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -6431,7 +6431,7 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
         
         interval
         Subtract arguments, producing a symbolic result that
-        uses years and months
+        uses years and months, rather than just days
         age(timestamp '2001-04-10', timestamp '1957-06-13')
         43 years 9 mons 27 days
        
@@ -6794,6 +6794,36 @@ SELECT (DATE '2001-10-30', DATE '2001-10-30') OVERLAPS
    days because May has 31 days, while April has only 30.
   
 
+  
+   Subtraction of dates and timestamps can also be complex.  The most
+   accurate way to perform subtraction is to convert each value to a number
+   of seconds using EXTRACT(EPOCH FROM  ...) and compute the
+   number of seconds between the two values.  This will adjust
+   for the number of days in each month, timezone changes, and daylight
+   saving time adjustments.  Operator subtraction of date or timestamp
+   values returns the number of days (24-hours) and hours/minutes/seconds
+   between the values, making the same adjustments.  The age
+   function returns years, months, days, and hours/minutes/seconds,
+   performing field-by-field subtraction and then adjusting for negative
+   field values.  The following queries, produced with timezone
+   = 'US/Eastern' and including a daylight saving time change,
+   illustrates these issues:
+  
+
+
+SELECT EXTRACT(EPOCH FROM timestamptz '2013-07-01 12:00:00') -
+       EXTRACT(EPOCH FROM timestamptz '2013-03-01 12:00:00');
+Result: 10537200
+SELECT (EXTRACT(EPOCH FROM timestamptz '2013-07-01 12:00:00') -
+        EXTRACT(EPOCH FROM timestamptz '2013-03-01 12:00:00')) 
+        / 60 / 60 / 24;
+Result: 121.958333333333
+SELECT timestamptz '2013-07-01 12:00:00' - timestamptz '2013-03-01 12:00:00';
+Result: 121 days 23:00:00
+SELECT age(timestamptz '2013-07-01 12:00:00', timestamptz '2013-03-01 12:00:00');
+Result: 4 mons
+
+
   
    <function>EXTRACT</function>, <function>date_part</function>