From f176e379754bc461dcf80a74eb269de339396665 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Mon, 8 Sep 2003 19:38:02 +0000 Subject: [PATCH] Document a bunch of formerly-undocumented date/time operators, including the SQL-spec OVERLAPS construct. --- doc/src/sgml/func.sgml | 139 +++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 118 insertions(+), 21 deletions(-) diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index 62f8ff6fd7..e53a9c2a94 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -1,5 +1,5 @@ @@ -4575,8 +4575,8 @@ substring('foobar' from 'o(.)b') o + - timestamp '2001-09-28 01:00' + interval '23 hours' - timestamp '2001-09-29 00:00' + date '2001-09-28' + integer '7' + date '2001-10-05' @@ -4587,14 +4587,56 @@ substring('foobar' from 'o(.)b') o + + date '2001-09-28' + time '03:00' + timestamp '2001-09-28 03:00' + + + + + + time '03:00' + date '2001-09-28' + timestamp '2001-09-28 03:00' + + + + + + interval '1 day' + interval '1 hour' + interval '1 day 01:00' + + + + + + timestamp '2001-09-28 01:00' + interval '23 hours' + timestamp '2001-09-29 00:00' + + + + + time '01:00' + interval '3 hours' time '04:00' + + + interval '3 hours' + time '01:00' + time '04:00' + + + - - timestamp '2001-09-28 23:00' - interval '23 hours' - timestamp '2001-09-28' + - interval '23 hours' + interval '-23:00' + + + + - + date '2001-10-01' - date '2001-09-28' + integer '3' + + + + - + date '2001-10-01' - integer '7' + date '2001-09-24' @@ -4605,26 +4647,56 @@ substring('foobar' from 'o(.)b') o - + time '05:00' - time '03:00' + interval '02:00' + + + + - time '05:00' - interval '2 hours' time '03:00' - + timestamp '2001-09-28 23:00' - interval '23 hours' + timestamp '2001-09-28 00:00' + + + + - + interval '1 day' - interval '1 hour' + interval '23:00' + + + + - interval '2 hours' - time '05:00' - time '03:00:00' + time '03:00' + + + + - + timestamp '2001-09-29 03:00' - timestamp '2001-09-27 12:00' + interval '1 day 15:00' + + + + * + double precision '3.5' * interval '1 hour' + interval '03:30' * - interval '1 hour' * int '3' - interval '03:00' + interval '1 hour' * double precision '3.5' + interval '03:30' / - interval '1 hour' / int '3' - interval '00:20' + interval '1 hour' / double precision '1.5' + interval '00:40' @@ -4714,7 +4786,7 @@ substring('foobar' from 'o(.)b') o linkend="functions-datetime-trunc"> date_trunc('hour', timestamp '2001-02-16 20:38:40') - 2001-02-16 20:00:00+00 + 2001-02-16 20:00:00 @@ -4788,14 +4860,36 @@ substring('foobar' from 'o(.)b') o Current date and time; see - timeofday() - Wed Feb 21 17:01:13.000126 2001 EST + + + + In addition to these functions, the SQL OVERLAPS keyword is + supported: + +( start1, end1 ) OVERLAPS ( start2, end2 ) +( start1, length1 ) OVERLAPS ( start2, length2 ) + + This expression yields true when two time periods (defined by their + endpoints) overlap, false when they do not overlap. The endpoints + can be specified as pairs of dates, times, or timestamps; or as + a date, time, or timestamp followed by an interval. + + + +SELECT (DATE '2001-02-16', DATE '2001-12-21') OVERLAPS + (DATE '2001-10-30', DATE '2002-10-30'); +Result: true +SELECT (DATE '2001-02-16', INTERVAL '100 days') OVERLAPS + (DATE '2001-10-30', DATE '2002-10-30'); +Result: false + + <function>EXTRACT</function>, <function>date_part</function> @@ -4906,8 +5000,8 @@ SELECT EXTRACT(DOY FROM TIMESTAMP '2001-02-16 20:38:40'); -SELECT EXTRACT(EPOCH FROM TIMESTAMP '2001-02-16 20:38:40'); -Result: 982352320 +SELECT EXTRACT(EPOCH FROM TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40-08'); +Result: 982384720 SELECT EXTRACT(EPOCH FROM INTERVAL '5 days 3 hours'); Result: 442800 @@ -5156,11 +5250,14 @@ SELECT date_part('hour', INTERVAL '4 hours 3 minutes'); date_trunc('field', source) source is a value expression of type - timestamp. (Values of type date and - time are cast automatically.) + timestamp or interval. + (Values of type date and + time are cast automatically, to timestamp or + interval respectively.) field selects to which precision to - truncate the time stamp value. The return value is of type - timestamp with all fields that are less than the + truncate the input value. The return value is of type + timestamp or interval + with all fields that are less significant than the selected one set to zero (or one, for day and month). @@ -5185,10 +5282,10 @@ date_trunc('field', source Examples: SELECT date_trunc('hour', TIMESTAMP '2001-02-16 20:38:40'); -Result: 2001-02-16 20:00:00+00 +Result: 2001-02-16 20:00:00 SELECT date_trunc('year', TIMESTAMP '2001-02-16 20:38:40'); -Result: 2001-01-01 00:00:00+00 +Result: 2001-01-01 00:00:00 -- 2.11.0