From: Thomas Lockhart <Thomas.G.Lockhart@jpl.nasa.gov>

Subject: [HACKERS] More date time functions

Here are some additional patches mostly related to the date and time
data types. It includes some type conversion routines to move between
the different date types and some other date manipulation routines such
as date_part(units,datetime).

I noticed Edmund Mergl et al's neat trick for getting function overloading
for builtin functions, so started to use that for the date and time stuff.
Later, if someone figures out how to get function overloading directly
for internal C code, then we can move to that technique.

These patches include documentation updates (don't faint!) for the built-in
man page. Doesn't yet include mention of timestamp, since I don't know
much about it and since it may change a bit to become a _real_ ANSI timestamp
which would include parser support for the declaration syntax (what do you
think, Dan?).

The patches were developed on the 970330 release, but have been rebuilt
off of the 970402 release. The first patch below is to get libpq to compile,
on my Linux box, but is not related to the rest of the patches and you can
choose not to apply that one at this time. Thanks in advance, scrappy!

src/backend/utils/adt/date.c

@@ -9,7 +9,7 @@
  *
  *
  * IDENTIFICATION
- *    $Header: /cvsroot/pgsql/src/backend/utils/adt/date.c,v 1.6 1997/03/14 23:19:57 scrappy Exp $
+ *    $Header: /cvsroot/pgsql/src/backend/utils/adt/date.c,v 1.7 1997/04/02 18:33:09 scrappy Exp $
  *
  * NOTES
  *   This code is actually (almost) unused.
@@ -32,15 +32,14 @@
 
 #include "postgres.h"
 #include "miscadmin.h"
+#ifdef HAVE_LIMITS_H
+# include <limits.h>
+#endif
 #include "access/xact.h"
 #include "utils/builtins.h"	/* where function declarations go */
 #include "utils/palloc.h"
 #include "utils/dt.h"
 
-#ifndef USE_NEW_TIME_CODE
-#define USE_NEW_TIME_CODE 1
-#endif
-
 #define	INVALID_RELTIME_STR	"Undefined RelTime"
 #define	INVALID_RELTIME_STR_LEN (sizeof(INVALID_RELTIME_STR)-1)
 #define	RELTIME_LABEL		'@'
@@ -235,6 +234,55 @@ char *tintervalout(TimeInterval interval)
  *   PUBLIC ROUTINES                                                         *
  *****************************************************************************/
 
+RelativeTime
+timespan_reltime(TimeSpan *timespan)
+{
+    RelativeTime time;
+    double span;
+
+    if (!PointerIsValid(timespan))
+	time = INVALID_RELTIME;
+
+    if (TIMESPAN_IS_INVALID(*timespan)) {
+	time = INVALID_RELTIME;
+
+    } else {
+	span = ((((double) 30*86400)*timespan->month) + timespan->time);
+
+#ifdef DATEDEBUG
+printf( "timespan_reltime- convert m%d s%f to %f [%d %d]\n",
+ timespan->month, timespan->time, span, INT_MIN, INT_MAX);
+#endif
+
+	time = (((span > INT_MIN) && (span < INT_MAX))? span: INVALID_RELTIME);
+    };
+
+    return(time);
+} /* timespan_reltime() */
+
+
+TimeSpan *
+reltime_timespan(RelativeTime reltime)
+{
+    TimeSpan *result;
+
+    if (!PointerIsValid(result = PALLOCTYPE(TimeSpan)))
+        elog(WARN,"Memory allocation failed, can't convert reltime to timespan",NULL);
+
+    switch(reltime) {
+    case INVALID_RELTIME:
+	TIMESPAN_INVALID(*result);
+	break;
+
+    default:
+	result->time = reltime;
+	result->month = 0;
+    };
+
+    return(result);
+} /* reltime_timespan() */
+
+
 /*
  *	mktinterval	- creates a time interval with endpoints t1 and t2
  */

src/backend/utils/adt/nabstime.c

@@ -7,7 +7,7 @@
  *
  *
  * IDENTIFICATION
- *    $Header: /cvsroot/pgsql/src/backend/utils/adt/nabstime.c,v 1.21 1997/03/28 07:12:53 scrappy Exp $
+ *    $Header: /cvsroot/pgsql/src/backend/utils/adt/nabstime.c,v 1.22 1997/04/02 18:33:50 scrappy Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -27,6 +27,7 @@
 #ifndef USE_POSIX_TIME
 #include <sys/timeb.h>
 #endif
+#include "utils/builtins.h"
 #include "access/xact.h"
 
 
@@ -90,11 +91,19 @@ printf( "GetCurrentAbsoluteTime- timezone is %s -> %d seconds from UTC\n",
 void
 GetCurrentTime(struct tm *tm)
 {
-    time_t now;
+    abstime2tm( GetCurrentTransactionStartTime(), &CTimeZone, tm);
+
+    return;
+} /* GetCurrentTime() */
+
+
+void
+abstime2tm(AbsoluteTime time, int *tzp, struct tm *tm)
+{
     struct tm *tt;
 
-    now = GetCurrentTransactionStartTime()-CTimeZone;
-    tt = gmtime( &now);
+    if (tzp != NULL) time -= *tzp;
+    tt = gmtime((time_t *) &time);
 
     tm->tm_year = tt->tm_year+1900;
     tm->tm_mon = tt->tm_mon+1;
@@ -105,11 +114,13 @@ GetCurrentTime(struct tm *tm)
     tm->tm_isdst = tt->tm_isdst;
 
     return;
-} /* GetCurrentTime() */
+} /* abstime2tm() */
 
 
-AbsoluteTime tm2abstime( struct tm *tm, int tz);
-
+/* tm2abstime()
+ * Convert a tm structure to abstime.
+ * Note that tm has full year (not 1900-based) and 1-based month.
+ */
 AbsoluteTime
 tm2abstime( struct tm *tm, int tz)
 {
@@ -122,13 +133,13 @@ tm2abstime( struct tm *tm, int tz)
       || tm->tm_hour < 0 || tm->tm_hour >= 24
       || tm->tm_min < 0 || tm->tm_min > 59
       || tm->tm_sec < 0 || tm->tm_sec > 59)
-	return INVALID_ABSTIME;
+	return(INVALID_ABSTIME);
 
     day = (date2j( tm->tm_year, tm->tm_mon, tm->tm_mday) - date2j( 1970, 1, 1));
 
     /* check for time out of range */
     if ((day < MIN_DAYNUM) || (day > MAX_DAYNUM))
-	return INVALID_ABSTIME;
+	return(INVALID_ABSTIME);
 
     /* convert to seconds */
     sec = tm->tm_sec + tz + (tm->tm_min +(day*24 + tm->tm_hour)*60)*60;
@@ -136,7 +147,7 @@ tm2abstime( struct tm *tm, int tz)
     /* check for overflow */
     if ((day == MAX_DAYNUM && sec < 0) ||
       (day == MIN_DAYNUM && sec > 0))
-	return INVALID_ABSTIME;
+	return(INVALID_ABSTIME);
 
     /* daylight correction */
     if (tm->tm_isdst < 0) {		/* unknown; find out */
@@ -147,7 +158,7 @@ tm2abstime( struct tm *tm, int tz)
 
     /* check for reserved values (e.g. "current" on edge of usual range */
     if (!AbsoluteTimeIsReal(sec))
-	return INVALID_ABSTIME;
+	return(INVALID_ABSTIME);
 
     return sec;
 } /* tm2abstime() */
@@ -369,6 +380,16 @@ AbsoluteTimeIsAfter(AbsoluteTime time1, AbsoluteTime time2)
 }
 
 
+/* abstime_finite()
+ */
+bool
+abstime_finite(AbsoluteTime abstime)
+{
+    return((abstime != INVALID_ABSTIME)
+      && (abstime != NOSTART_ABSTIME) && (abstime != NOEND_ABSTIME));
+} /* abstime_datetime() */
+
+
 /*
  *	abstimeeq	- returns 1, iff arguments are equal
  *	abstimene	- returns 1, iff arguments are not equal
@@ -381,7 +402,7 @@ bool
 abstimeeq(AbsoluteTime t1, AbsoluteTime t2)
 {
     if (t1 == INVALID_ABSTIME || t2 == INVALID_ABSTIME)
-	return 0;
+	return(FALSE);
     if (t1 == CURRENT_ABSTIME)
 	t1 = GetCurrentTransactionStartTime();
     if (t2 == CURRENT_ABSTIME)
@@ -394,7 +415,7 @@ bool
 abstimene(AbsoluteTime t1, AbsoluteTime t2)
 { 
     if (t1 == INVALID_ABSTIME || t2 == INVALID_ABSTIME)
-	return 0;
+	return(FALSE);
     if (t1 == CURRENT_ABSTIME)
 	t1 = GetCurrentTransactionStartTime();
     if (t2 == CURRENT_ABSTIME)
@@ -407,7 +428,7 @@ bool
 abstimelt(AbsoluteTime t1, AbsoluteTime t2)
 { 
     if (t1 == INVALID_ABSTIME || t2 == INVALID_ABSTIME)
-	return 0;
+	return(FALSE);
     if (t1 == CURRENT_ABSTIME)
 	t1 = GetCurrentTransactionStartTime();
     if (t2 == CURRENT_ABSTIME)
@@ -420,7 +441,7 @@ bool
 abstimegt(AbsoluteTime t1, AbsoluteTime t2)
 { 
     if (t1 == INVALID_ABSTIME || t2 == INVALID_ABSTIME)
-	return 0;
+	return(FALSE);
     if (t1 == CURRENT_ABSTIME)
 	t1 = GetCurrentTransactionStartTime();
     if (t2 == CURRENT_ABSTIME)
@@ -433,7 +454,7 @@ bool
 abstimele(AbsoluteTime t1, AbsoluteTime t2)
 { 
     if (t1 == INVALID_ABSTIME || t2 == INVALID_ABSTIME)
-	return 0;
+	return(FALSE);
     if (t1 == CURRENT_ABSTIME)
 	t1 = GetCurrentTransactionStartTime();
     if (t2 == CURRENT_ABSTIME)
@@ -446,7 +467,7 @@ bool
 abstimege(AbsoluteTime t1, AbsoluteTime t2)
 { 
     if (t1 == INVALID_ABSTIME || t2 == INVALID_ABSTIME)
-	return 0;
+	return(FALSE);
     if (t1 == CURRENT_ABSTIME)
 	t1 = GetCurrentTransactionStartTime();
     if (t2 == CURRENT_ABSTIME)
@@ -455,6 +476,7 @@ abstimege(AbsoluteTime t1, AbsoluteTime t2)
     return(t1 >= t2);
 }
 
+
 /* datetime_abstime()
  * Convert datetime to abstime.
  */
@@ -480,10 +502,10 @@ datetime_abstime(DateTime *datetime)
 
     } else {
 	if (DATETIME_IS_RELATIVE(*datetime)) {
-	    datetime2tm( SetDateTime(*datetime), tm, &fsec);
+	    datetime2tm( SetDateTime(*datetime), &CTimeZone, tm, &fsec);
 	    result = tm2abstime( tm, 0);
 
-	} else if (datetime2tm( *datetime, tm, &fsec) == 0) {
+	} else if (datetime2tm( *datetime, &CTimeZone, tm, &fsec) == 0) {
 	    result = tm2abstime( tm, 0);
 
 	} else {
@@ -493,3 +515,42 @@ datetime_abstime(DateTime *datetime)
 
     return(result);
 } /* datetime_abstime() */
+
+/* abstime_datetime()
+ * Convert datetime to abstime.
+ */
+DateTime *
+abstime_datetime(AbsoluteTime abstime)
+{
+    DateTime *result;
+
+    if (!PointerIsValid(result = PALLOCTYPE(DateTime)))
+	elog(WARN,"Unable to allocate space to convert abstime to datetime",NULL);
+
+    switch (abstime) {
+    case INVALID_ABSTIME:
+        DATETIME_INVALID(*result);
+	break;
+
+    case NOSTART_ABSTIME:
+        DATETIME_NOBEGIN(*result);
+	break;
+
+    case NOEND_ABSTIME:
+        DATETIME_NOEND(*result);
+	break;
+
+    case EPOCH_ABSTIME:
+        DATETIME_EPOCH(*result);
+	break;
+
+    case CURRENT_ABSTIME:
+        DATETIME_CURRENT(*result);
+	break;
+
+    default:
+        *result = abstime + ((date2j( 1970, 1, 1) - date2j( 2000, 1, 1))*86400);
+    };
+
+    return(result);
+} /* abstime_datetime() */

src/backend/utils/adt/timestamp.c

@@ -88,3 +88,23 @@ timestampge(time_t t1, time_t t2)
 {
     return difftime(t1, t2) <= 0;
 }
+
+DateTime *
+timestamp_datetime(time_t timestamp)
+{
+    DateTime *result;
+
+    double fsec = 0;
+    struct tm *tm;
+
+    if (!PointerIsValid(result = PALLOCTYPE(DateTime)))
+	elog(WARN,"Memory allocation failed, can't convert timestamp to datetime",NULL);
+
+    tm = localtime((time_t *) &timestamp);
+    tm->tm_year += 1900;
+    tm->tm_mon += 1;
+
+    *result = tm2datetime(tm, fsec, NULL);
+
+    return(result);
+} /* timestamp_datetime() */

src/include/catalog/pg_aggregate.h

@@ -7,7 +7,7 @@
  *
  * Copyright (c) 1994, Regents of the University of California
  *
- * $Id: pg_aggregate.h,v 1.3 1996/11/14 21:39:07 scrappy Exp $
+ * $Id: pg_aggregate.h,v 1.4 1997/04/02 18:36:09 scrappy Exp $
  *
  * NOTES
  *    the genbki.sh script reads this file and generates .bki
@@ -101,13 +101,17 @@ DATA(insert OID = 0 ( max   PGUID int4larger   - -  23  23  0  23  _null_ _null_
 DATA(insert OID = 0 ( max   PGUID int2larger    - -   21   21 0   21 _null_ _null_ ));
 DATA(insert OID = 0 ( max   PGUID float4larger  - -  700  700 0  700 _null_ _null_ ));
 DATA(insert OID = 0 ( max   PGUID float8larger  - -  701  701 0  701 _null_ _null_ ));
+DATA(insert OID = 0 ( max   PGUID int4larger    - -  702  702 0  702 _null_ _null_ ));
 DATA(insert OID = 0 ( max   PGUID date_larger   - - 1082 1082 0 1082 _null_ _null_ ));
+DATA(insert OID = 0 ( max   PGUID float8larger  - - 1084 1084 0 1084 _null_ _null_ ));
 
 DATA(insert OID = 0 ( min   PGUID int4smaller   - -   23   23 0   23 _null_ _null_ ));
 DATA(insert OID = 0 ( min   PGUID int2smaller   - -   21   21 0   21 _null_ _null_ ));
 DATA(insert OID = 0 ( min   PGUID float4smaller - -  700  700 0  700 _null_ _null_ ));
 DATA(insert OID = 0 ( min   PGUID float8smaller - -  701  701 0  701 _null_ _null_ ));
+DATA(insert OID = 0 ( min   PGUID int4smaller   - -  702  702 0  702 _null_ _null_ ));
 DATA(insert OID = 0 ( min   PGUID date_smaller  - - 1082 1082 0 1082 _null_ _null_ ));
+DATA(insert OID = 0 ( min   PGUID float8smaller - - 1084 1084 0 1084 _null_ _null_ ));
 
 DATA(insert OID = 0 ( count PGUID - int4inc - 0 0 23 23  _null_ 0 ));
 

src/include/catalog/pg_operator.h

@@ -7,7 +7,7 @@
  *
  * Copyright (c) 1994, Regents of the University of California
  *
- * $Id: pg_operator.h,v 1.6 1997/03/25 08:10:37 scrappy Exp $
+ * $Id: pg_operator.h,v 1.7 1997/04/02 18:36:12 scrappy Exp $
  *
  * NOTES
  *    the genbki.sh script reads this file and generates .bki
@@ -413,6 +413,7 @@ DATA(insert OID = 1325 (  ">="     PGUID 0 b t f 1184 1184   16 1322 1322 0 0 da
 
 DATA(insert OID = 1327 (  "+"      PGUID 0 b t f 1184 1186 1184 1327    0 0 0 datetime_add_span - - ));
 DATA(insert OID = 1328 (  "-"      PGUID 0 b t f 1184 1184 1186    0    0 0 0 datetime_sub - - ));
+DATA(insert OID = 1329 (  "-"      PGUID 0 b t f 1184 1186 1184    0    0 0 0 datetime_sub_span - - ));
 
 /* timespan operators */
 DATA(insert OID = 1330 (  "="      PGUID 0 b t f 1186 1186   16 1330 1331 1332 1332 timespan_eq eqsel eqjoinsel ));
@@ -422,7 +423,7 @@ DATA(insert OID = 1333 (  "<="     PGUID 0 b t f 1186 1186   16 1334 1334 0 0 ti
 DATA(insert OID = 1334 (  ">"      PGUID 0 b t f 1186 1186   16 1333 1333 0 0 timespan_gt intltsel intltjoinsel ));
 DATA(insert OID = 1335 (  ">="     PGUID 0 b t f 1186 1186   16 1332 1332 0 0 timespan_ge intltsel intltjoinsel ));
 
-DATA(insert OID = 1336 (  "-"      PGUID 0 b t f    0 1186 1186    0    0 0 0 timespan_um 0 0 ));
+DATA(insert OID = 1336 (  "-"      PGUID 0 l t f    0 1186 1186    0    0 0 0 timespan_um 0 0 ));
 DATA(insert OID = 1337 (  "+"      PGUID 0 b t f 1186 1186 1186 1337    0 0 0 timespan_add - - ));
 DATA(insert OID = 1338 (  "-"      PGUID 0 b t f 1186 1186 1186    0    0 0 0 timespan_sub - - ));
 

src/include/utils/builtins.h

@@ -6,7 +6,7 @@
  *
  * Copyright (c) 1994, Regents of the University of California
  *
- * $Id: builtins.h,v 1.13 1997/03/25 09:25:33 scrappy Exp $
+ * $Id: builtins.h,v 1.14 1997/04/02 18:31:52 scrappy Exp $
  *
  * NOTES
  *    This should normally only be included by fmgr.h.
@@ -224,6 +224,8 @@ extern int32 reltimein(char *timestring);
 extern char *reltimeout(int32 timevalue);
 extern TimeInterval tintervalin(char *intervalstr);
 extern char *tintervalout(TimeInterval interval);
+extern RelativeTime timespan_reltime(TimeSpan *timespan);
+extern TimeSpan *reltime_timespan(RelativeTime reltime);
 extern TimeInterval mktinterval(AbsoluteTime t1, AbsoluteTime t2);
 extern AbsoluteTime timepl(AbsoluteTime t1, RelativeTime t2);
 extern AbsoluteTime timemi(AbsoluteTime t1, RelativeTime t2);
@@ -416,6 +418,7 @@ bool timestamplt(time_t t1, time_t t2);
 bool timestampgt(time_t t1, time_t t2);
 bool timestample(time_t t1, time_t t2);
 bool timestampge(time_t t1, time_t t2);
+DateTime *timestamp_datetime(time_t timestamp);
 
 /* varchar.c */
 extern char *bpcharin(char *s, int dummy, int typlen);
@@ -476,6 +479,10 @@ extern DateADT date_smaller(DateADT dateVal1, DateADT dateVal2);
 extern int32 date_mi(DateADT dateVal1, DateADT dateVal2);
 extern DateADT date_pli(DateADT dateVal, int32 days);
 extern DateADT date_mii(DateADT dateVal, int32 days);
+extern DateTime *date_datetime(DateADT date);
+extern DateADT datetime_date(DateTime *datetime);
+extern DateTime *datetime_datetime(DateADT date, TimeADT *time);
+extern DateADT abstime_date(AbsoluteTime abstime);
 
 #else
 
@@ -493,6 +500,10 @@ extern int4 date_smaller(int4 dateVal1, int4 dateVal2);
 extern int32 date_mi(int4 dateVal1, int4 dateVal2);
 extern int4 date_pli(int4 dateVal, int32 days);
 extern int4 date_mii(int4 dateVal, int32 days);
+extern DateTime *date_datetime(int4 date);
+extern int4 datetime_date(DateTime *datetime);
+extern DateTime *datetime_datetime(int4 date, TimeADT *time);
+extern int4 abstime_date(AbsoluteTime abstime);
 
 #endif
 

src/include/utils/dt.h

@@ -8,7 +8,7 @@
  *
  * Copyright (c) 1994, Regents of the University of California
  *
- * $Id: dt.h,v 1.4 1997/03/28 07:13:21 scrappy Exp $
+ * $Id: dt.h,v 1.5 1997/04/02 18:32:20 scrappy Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -36,10 +36,16 @@ typedef struct {
 } TimeSpan;
 
 
-#define USE_NEW_TIME_CODE	1
+/*
+ * USE_NEW_DATE enables a more efficient Julian day-based date type.
+ * USE_NEW_TIME enables a more efficient double-based time type.
+ * These have been tested in v6.1beta, but only by myself.
+ * These should be enabled for Postgres v7.0 - tgl 97/04/02
+ */
 #define USE_NEW_DATE		0
 #define USE_NEW_TIME		0
 
+
 /* ----------------------------------------------------------------
  *		time types + support macros
  *
@@ -225,12 +231,13 @@ typedef struct {
 				|| DATETIME_IS_NOBEGIN(j) || DATETIME_IS_NOEND(j))
 #define DATETIME_IS_RESERVED(j) (DATETIME_IS_RELATIVE(j) || DATETIME_NOT_FINITE(j))
 
-#define TIMESPAN_INVALID(j)	{j->time = DT_INVALID;}
+#define TIMESPAN_INVALID(j)	{(j).time = DT_INVALID;}
 #ifdef NAN
 #define TIMESPAN_IS_INVALID(j)	(isnan((j).time))
 #else
 #define TIMESPAN_IS_INVALID(j)	((j).time == DT_INVALID)
 #endif
+#define TIMESPAN_NOT_FINITE(j)	TIMESPAN_IS_INVALID(j)
 
 #define TIME_PREC 1e-6
 #define JROUND(j) (rint(((double) j)/TIME_PREC)*TIME_PREC)
@@ -247,6 +254,7 @@ extern bool datetime_lt(DateTime *dt1, DateTime *dt2);
 extern bool datetime_le(DateTime *dt1, DateTime *dt2);
 extern bool datetime_ge(DateTime *dt1, DateTime *dt2);
 extern bool datetime_gt(DateTime *dt1, DateTime *dt2);
+extern bool datetime_finite(DateTime *datetime);
 
 extern TimeSpan *timespan_in(char *str);
 extern char *timespan_out(TimeSpan *span);
@@ -256,9 +264,14 @@ extern bool timespan_lt(TimeSpan *span1, TimeSpan *span2);
 extern bool timespan_le(TimeSpan *span1, TimeSpan *span2);
 extern bool timespan_ge(TimeSpan *span1, TimeSpan *span2);
 extern bool timespan_gt(TimeSpan *span1, TimeSpan *span2);
+extern bool timespan_finite(TimeSpan *span);
 
-float64 datetime_part(text *units, DateTime *datetime);
-float64 timespan_part(text *units, TimeSpan *timespan);
+extern text *datetime_text(DateTime *datetime);
+extern DateTime *text_datetime(text *str);
+extern text *timespan_text(TimeSpan *timespan);
+extern TimeSpan *text_timespan(text *str);
+extern float64 datetime_part(text *units, DateTime *datetime);
+extern float64 timespan_part(text *units, TimeSpan *timespan);
 
 extern TimeSpan *timespan_um(TimeSpan *span);
 extern TimeSpan *timespan_add(TimeSpan *span1, TimeSpan *span2);
@@ -269,12 +282,12 @@ extern DateTime *datetime_add_span(DateTime *dt, TimeSpan *span);
 extern DateTime *datetime_sub_span(DateTime *dt, TimeSpan *span);
 
 extern void GetCurrentTime(struct tm *tm);
-DateTime SetDateTime(DateTime datetime);
-DateTime tm2datetime(struct tm *tm, double fsec, int tzp);
-int datetime2tm( DateTime dt, struct tm *tm, double *fsec);
+extern DateTime SetDateTime(DateTime datetime);
+extern DateTime tm2datetime(struct tm *tm, double fsec, int *tzp);
+extern int datetime2tm( DateTime dt, int *tzp, struct tm *tm, double *fsec);
 
-int timespan2tm(TimeSpan span, struct tm *tm, float8 *fsec);
-int tm2timespan(struct tm *tm, double fsec, TimeSpan *span);
+extern int timespan2tm(TimeSpan span, struct tm *tm, float8 *fsec);
+extern int tm2timespan(struct tm *tm, double fsec, TimeSpan *span);
 
 extern DateTime dt2local( DateTime dt, int timezone);
 

src/include/utils/nabstime.h

@@ -6,7 +6,7 @@
  *
  * Copyright (c) 1994, Regents of the University of California
  *
- * $Id: nabstime.h,v 1.6 1997/03/25 08:11:24 scrappy Exp $
+ * $Id: nabstime.h,v 1.7 1997/04/02 18:32:39 scrappy Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -84,17 +84,8 @@ typedef TimeIntervalData *TimeInterval;
 #define RelativeTimeIsValid(time) \
     ((bool) (((RelativeTime) time) != INVALID_RELTIME))
 
-#if USE_NEW_TIME_CODE
-
 extern AbsoluteTime GetCurrentAbsoluteTime(void);
 
-#else
-
-#define GetCurrentAbsoluteTime() \
-    ((AbsoluteTime) getSystemTime())
-
-#endif
-
 /*
  * getSystemTime --
  *	Returns system time.
@@ -121,11 +112,17 @@ extern bool abstimelt(AbsoluteTime t1, AbsoluteTime t2);
 extern bool abstimegt(AbsoluteTime t1, AbsoluteTime t2);
 extern bool abstimele(AbsoluteTime t1, AbsoluteTime t2);
 extern bool abstimege(AbsoluteTime t1, AbsoluteTime t2);
+extern bool abstime_finite(AbsoluteTime time);
 
 extern AbsoluteTime datetime_abstime(DateTime *datetime);
+extern DateTime *abstime_datetime(AbsoluteTime abstime);
 
 extern bool AbsoluteTimeIsBefore(AbsoluteTime time1, AbsoluteTime time2);
 extern bool AbsoluteTimeIsAfter(AbsoluteTime time1, AbsoluteTime time2);
+
+extern AbsoluteTime tm2abstime(struct tm *tm, int tz);
+extern void abstime2tm(AbsoluteTime time, int *tzp, struct tm *tm);
+
 extern AbsoluteTime dateconv(struct tm *tm, int zone);
 extern time_t qmktime(struct tm *tp);
 

src/man/built-in.3

 .\" This is -*-nroff-*-
 .\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/src/man/Attic/built-in.3,v 1.3 1996/12/11 00:27:02 momjian Exp $
-.TH BUILT-INS INTRO 11/05/95 PostgreSQL PostgreSQL
+.\" $Header: /cvsroot/pgsql/src/man/Attic/built-in.3,v 1.4 1997/04/02 18:31:22 scrappy Exp $
+.TH BUILT-INS INTRO 04/01/97 PostgreSQL PostgreSQL
 .SH "DESCRIPTION"
 This section describes the data types, functions and operators
 available to users in Postgres as it is distributed.
-.SH "Built-in and System Types"
 .SH "BUILT-IN TYPES"
-This section describes both 
+This section describes 
 .BR built-in
 data types.
-These Built-in types are 
-are installed in every database.
+These Built-in types are installed in every database.
 .PP
 Users may add new types to Postgres using the
 .IR "define type"
@@ -24,7 +22,7 @@ described in this section.
 .in 0
 .nf
 	\fBPOSTGRES Type\fP	\fBMeaning\fP
-	abstime	absolute date and time
+	abstime	(absolute) limited-range date and time
 	aclitem	access control list item
 	bool	boolean
 	box	2-dimensional rectangle
@@ -37,6 +35,7 @@ described in this section.
 	char16	array of 16 characters
 	cid	command identifier type
 	date	ANSI SQL date type
+	datetime	general-use date and time
 	filename	large object filename
 	int	alias for int4
 	integer	alias for int4
@@ -58,13 +57,15 @@ described in this section.
 	polygon	2-dimensional polygon
 	real	alias for float4
 	regproc	registered procedure
-	reltime	relative date and time
+	reltime	(relative) date and time span (duration)
 	smgr	storage manager
 	smallint	alias for int2
 	text	variable length array of characters
 	tid	tuple identifier type
 	time 	ANSI SQL time type
-	tinterval	time interval
+	timespan	general-use time span (duration)
+	timestamp	limited-range ISO-format date and time
+	tinterval	time interval (start and stop abstime)
 	varchar	variable-length characters
 	xid	transaction identifier type
 
@@ -73,11 +74,94 @@ described in this section.
 .PP
 As a rule, the built-in types are all either (1) internal types, in
 which case the user should not worry about their external format, or
-(2) have obvious formats.  The exceptions to this rule are the three
+(2) have obvious formats.  The exceptions to this rule are the date and
 time types.
+
 .SH "Syntax of date and time types"
+.SH "DATETIME"
+General-use date and time is input using a wide range of
+syntaxes, including ISO-compatible, SQL-compatible, traditional
+Postgres (see section on
+.IR "absolute time")
+and other permutations of date and time. Output styles can be ISO-compatible,
+SQL-compatible, or traditional Postgres, with the default set to be compatible
+with Postgres v6.0.
+.PP
+datetime is specified using the following syntax:
+.PP
+.nf
+Year-Month-Day [ Hour : Minute : Second ]      [AD,BC] [ Timezone ]
+.nf
+  YearMonthDay [ Hour : Minute : Second ]      [AD,BC] [ Timezone ]
+.nf
+     Month Day [ Hour : Minute : Second ] Year [AD,BC] [ Timezone ]
+.sp
+where	
+	Year is 4013 BC, ..., very large
+	Month is Jan, Feb, ..., Dec or 1, 2, ..., 12
+	Day is 1, 2, ..., 31
+	Hour is 00, 02, ..., 23
+	Minute is 00, 01, ..., 59
+	Second is 00, 01, ..., 59 (60 for leap second)
+	Timezone is 3 characters or ISO offset to GMT
+.fi
+.PP
+Valid dates are from Nov 13 00:00:00 4013 BC GMT to far into the future.
+Timezones are either three characters (e.g. "GMT" or "PST") or ISO-compatible
+offsets to GMT (e.g. "-08" or "-08:00" when in Pacific Standard Time).
+Dates are stored internally in Greenwich Mean Time. Input and output routines 
+translate time to the local time zone of the server.
+.PP
+All special values allowed for
+.IR "absolute time"
+are also allowed for
+.IR "datetime".
+The special values \*(lqcurrent\*(rq,
+\*(lqinfinity\*(rq and \*(lq-infinity\*(rq are provided.
+\*(lqinfinity\*(rq specifies a time later than any valid time, and
+\*(lq-infinity\*(rq specifies a time earlier than any valid time.
+\*(lqcurrent\*(rq indicates that the current time should be
+substituted whenever this value appears in a computation.
+.PP
+The strings \*(lqnow\*(rq and \*(lqepoch\*(rq can be used to specify
+time values.  \*(lqnow\*(rq means the current time, and differs from
+\*(lqcurrent\*(rq in that the current time is immediately substituted
+for it.  \*(lqepoch\*(rq means Jan 1 00:00:00 1970 GMT.
+
+
+.SH "TIMESPAN"
+General-use time span is input using a wide range of
+syntaxes, including ISO-compatible, SQL-compatible, traditional
+Postgres (see section on
+.IR "relative time"
+) and other permutations of time span. Output formats can be ISO-compatible,
+SQL-compatible, or traditional Postgres, with the default set to be Postgres-compatible.
+Months and years are a "qualitative" time interval, and are stored separately
+from the other "quantitative" time intervals such as day or hour. For date arithmetic,
+the qualitative time units are instantiated in the context of the relevant date or time.
+.PP
+Time span is specified with the following syntax:
+.PP
+.nf
+  Quantity Unit [Quantity Unit...] [Direction]
+.nf
+@ Quantity Unit [Direction]
+.sp
+where 	
+	Quantity is ..., '-1', '0', `1', `2', ...
+	Unit is `second', `minute', `hour', `day', `week', `month', `year',
+	or abbreviations or plurals of these units.
+	Direction is ``ago''
+.fi
 .SH "ABSOLUTE TIME"
+Absolute time (abstime) is a limited-range (+/- 68 years) and limited-precision (1 sec)
+date data type.
+.IR "datetime"
+may be preferred, since it
+covers a larger range with greater precision.
+.PP
 Absolute time is specified using the following syntax:
+.PP
 .nf
 Month  Day [ Hour : Minute : Second ]  Year [ Timezone ]
 .sp
@@ -89,6 +173,7 @@ where
 	Second is 00, 01, ..., 59
 	Year is 1901, 1902, ..., 2038
 .fi
+.PP
 Valid dates are from Dec 13 20:45:53 1901 GMT to Jan 19 03:14:04
 2038 GMT.  As of Version 3.0, times are no longer read and written
 using Greenwich Mean Time; the input and output routines default to
@@ -105,8 +190,19 @@ The strings \*(lqnow\*(rq and \*(lqepoch\*(rq can be used to specify
 time values.  \*(lqnow\*(rq means the current time, and differs from
 \*(lqcurrent\*(rq in that the current time is immediately substituted
 for it.  \*(lqepoch\*(rq means Jan 1 00:00:00 1970 GMT.
+
 .SH "RELATIVE TIME"
+Relative time (reltime) is a limited-range (+/- 68 years) and limited-precision (1 sec)
+time span data type.
+.IR "timespan"
+may be preferred, since it
+covers a larger range with greater precision, allows multiple units
+for an entry, and correctly handles qualitative time
+units such as year and month. For reltime, only one quantity and unit is allowed
+per entry, which can be inconvenient for complicated time spans.
+.PP
 Relative time is specified with the following syntax:
+.PP
 .nf
 @ Quantity Unit [Direction]
 .sp
@@ -124,6 +220,7 @@ In addition, the special relative time \*(lqUndefined RelTime\*(rq is
 provided.
 .SH "TIME RANGES"
 Time ranges are specified as:
+.PP
 .nf
 [ 'abstime' 'abstime']
 .fi
@@ -131,6 +228,7 @@ where
 .IR abstime
 is a time in the absolute time format.  Special abstime values such as 
 \*(lqcurrent\*(rq, \*(lqinfinity\*(rq and \*(lq-infinity\*(rq can be used.
+
 .SH "Built-in operators and functions"
 .SH OPERATORS
 Postgres provides a large number of built-in operators on system types.
@@ -151,31 +249,8 @@ select * from emp where int4lt(salary, 40000);
 The rest of this section provides a list of the built-in operators and
 the functions that implement them.  Binary operators are listed first,
 followed by unary operators.
-.SH "BINARY OPERATORS"
-This list was generated from the Postgres system catalogs with the
-query:
 
-.nf
-SELECT
-	t0.typname AS result,
-        t1.typname AS left_type,
-        t2.typname AS right_type,
-        o.oprname AS operatr,
-        p.proname AS func_name
-FROM 	pg_proc p, pg_type t0,
-        pg_type t1, pg_type t2,
-        pg_operator o
-WHERE 	p.prorettype = t0.oid AND
-        RegprocToOid(o.oprcode) = p.oid AND
-	p.pronargs = 2 AND
-	o.oprleft = t1.oid AND
-	o.oprright = t2.oid
-ORDER BY result, left_type, right_type, operatr;
-.fi
-
-These operations are cast in terms of SQL types and so are
-.BR not
-directly usable as C function prototypes.
+.SH "BINARY OPERATORS"
 
 .nf
 Operators:
@@ -262,6 +337,68 @@ tinterval
 	<?>	abstime in tinterval
 	|	start of interval
 	<#>	convert to interval
+.fi
+
+.SH "FUNCTIONS"
+Many data types have functions available for conversion to other related types.
+In addition, there are some type-specific functions.
+
+.nf
+Functions:
+
+abstime
+	datetime datetime(abstime)        convert to datetime
+	bool     isfinite(abstime)        TRUE if this is a finite time
+
+date
+	datetime datetime(date)           convert to datetime
+	datetime datetime(date,time)      convert to datetime
+
+datetime
+	abstime  abstime(datetime)        convert to abstime
+	float8   date_part(text,datetime) specified portion of date field
+	bool     isfinite(datetime)       TRUE if this is a finite time
+
+reltime
+	timespan timespan(reltime)        convert to timespan
+
+time
+	datetime datetime(date,time)      convert to datetime
+
+timespan
+	float8   date_part(text,timespan) specified portion of time field
+	bool     isfinite(timespan)       TRUE if this is a finite time
+	reltime  reltime(timespan)        convert to reltime
+.fi
+
+.PP
+This list was generated from the Postgres system catalogs with the
+query:
+
+.nf
+SELECT
+	t0.typname AS result,
+	t1.typname AS left_type,
+	t2.typname AS right_type,
+	o.oprname AS operatr,
+	p.proname AS func_name
+FROM
+ 	pg_proc p, pg_type t0,
+	pg_type t1, pg_type t2,
+	pg_operator o
+WHERE
+ 	p.prorettype = t0.oid AND
+	RegprocToOid(o.oprcode) = p.oid AND
+	p.pronargs = 2 AND
+	o.oprleft = t1.oid AND
+	o.oprright = t2.oid
+ORDER BY
+	result, left_type, right_type, operatr;
+.fi
+
+These operations are cast in terms of SQL types and so are
+.BR not
+directly usable as C function prototypes.
 
 result   |left_type |right_type|operatr|func_name      
 ---------+----------+----------+-------+---------------