From 7489eb4d3b7fef2c2eaeb66e3bcb3fb74385b44d Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Tue, 3 Sep 2013 16:28:56 -0400
Subject: [PATCH] Docs: wording improvements in discussion of timestamp
arithmetic.
I started out just to fix the broken markup in commit
1c2085766187031eaeaae7db4785b9e1d4241988, but got distracted by
copy-editing. I see Bruce already fixed the markup, but I'll
commit the wordsmithing anyway.
---
doc/src/sgml/func.sgml | 29 ++++++++++++++++-------------
1 file changed, 16 insertions(+), 13 deletions(-)
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 00f8ffb38cb..ee1c957c737 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -6769,9 +6769,9 @@ SELECT (DATE '2001-10-30', DATE '2001-10-30') OVERLAPS
<para>
When adding an <type>interval</type> value to (or subtracting an
<type>interval</type> value from) a <type>timestamp with time zone</type>
- value, the days component advances (or decrements) the date of the
+ value, the days component advances or decrements the date of the
<type>timestamp with time zone</type> by the indicated number of days.
- Across daylight saving time changes (with the session time zone set to a
+ Across daylight saving time changes (when the session time zone is set to a
time zone that recognizes DST), this means <literal>interval '1 day'</literal>
does not necessarily equal <literal>interval '24 hours'</literal>.
For example, with the session time zone set to <literal>CST7CDT</literal>,
@@ -6785,8 +6785,8 @@ SELECT (DATE '2001-10-30', DATE '2001-10-30') OVERLAPS
</para>
<para>
- Note there can be ambiguity in the <literal>months</> returned by
- <function>age</> because different months have a different number of
+ Note there can be ambiguity in the <literal>months</> field returned by
+ <function>age</> because different months have different numbers of
days. <productname>PostgreSQL</>'s approach uses the month from the
earlier of the two dates when calculating partial months. For example,
<literal>age('2004-06-01', '2004-04-30')</> uses April to yield
@@ -6795,19 +6795,22 @@ SELECT (DATE '2001-10-30', DATE '2001-10-30') OVERLAPS
</para>
<para>
- 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 <literal>EXTRACT(EPOCH FROM ...)</> and compute the
+ Subtraction of dates and timestamps can also be complex. One conceptually
+ simple way to perform subtraction is to convert each value to a number
+ of seconds using <literal>EXTRACT(EPOCH FROM ...)</>, then subtract the
+ results; this produces the
number of <emphasis>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
+ saving time adjustments. Subtraction of date or timestamp
+ values with the <quote><literal>-</></quote> operator
+ returns the number of days (24-hours) and hours/minutes/seconds
between the values, making the same adjustments. The <function>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 <literal>timezone
- = 'US/Eastern'</> and including a daylight saving time change,
- illustrates these issues:
+ field values. The following queries illustrate the differences in these
+ approaches. The sample results were produced with <literal>timezone
+ = 'US/Eastern'</>; there is a daylight saving time change between the
+ two dates used:
</para>
<screen>
@@ -6815,7 +6818,7 @@ SELECT EXTRACT(EPOCH FROM timestamptz '2013-07-01 12:00:00') -
EXTRACT(EPOCH FROM timestamptz '2013-03-01 12:00:00');
<lineannotation>Result: </lineannotation><computeroutput>10537200</computeroutput>
SELECT (EXTRACT(EPOCH FROM timestamptz '2013-07-01 12:00:00') -
- EXTRACT(EPOCH FROM timestamptz '2013-03-01 12:00:00'))
+ EXTRACT(EPOCH FROM timestamptz '2013-03-01 12:00:00'))
/ 60 / 60 / 24;
<lineannotation>Result: </lineannotation><computeroutput>121.958333333333</computeroutput>
SELECT timestamptz '2013-07-01 12:00:00' - timestamptz '2013-03-01 12:00:00';
--
GitLab