From df7128bd34be68bccda90ab0ee011dffaccf0db0 Mon Sep 17 00:00:00 2001
From: Bruce Momjian <bruce@momjian.us>
Date: Wed, 18 Jul 2007 03:12:42 +0000
Subject: [PATCH] Document that age() adds days, then full months.

---
 doc/src/sgml/func.sgml | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 387c4e81c8f..5d5a86a0c7f 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.382 2007/06/06 23:00:35 tgl Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.383 2007/07/18 03:12:42 momjian Exp $ -->
 
  <chapter id="functions">
   <title>Functions and Operators</title>
@@ -5895,6 +5895,17 @@ SELECT (DATE '2001-02-16', INTERVAL '100 days') OVERLAPS
    <literal>CST7CDT</literal>.
   </para>
 
+  <para>
+   Note that when the <function>age</> function operates on multi-month
+   intervals, <productname>PostgreSQL</> adds days to the earlier date
+   until full months can be added.  This yields a different result than
+   adding full months first if the interval crosses from one month to the
+   next.  For example, <literal>age('2004-06-01', '2004-04-30')</> yeilds
+   <literal>1 mon 1 day</> using the <productname>PostgreSQL</> method,
+   while adding the month first would yield <literal>1 mon 2 days</>
+   because May has 31 days, while April has only 30.
+  </para>
+
   <sect2 id="functions-datetime-extract">
    <title><function>EXTRACT</function>, <function>date_part</function></title>