granicus.if.org Git - postgresql/blob - src/include/utils/datetime.h

   1 /*-------------------------------------------------------------------------
   2  *
   3  * datetime.h
   4  *        Definitions for date/time support code.
   5  *        The support code is shared with other date data types,
   6  *         including abstime, reltime, date, and time.
   7  *
   8  *
   9  * Portions Copyright (c) 1996-2014, PostgreSQL Global Development Group
  10  * Portions Copyright (c) 1994, Regents of the University of California
  11  *
  12  * src/include/utils/datetime.h
  13  *
  14  *-------------------------------------------------------------------------
  15  */
  16 #ifndef DATETIME_H
  17 #define DATETIME_H
  18
  19 #include "nodes/nodes.h"
  20 #include "utils/timestamp.h"
  21
  22 /* this struct is declared in utils/tzparser.h: */
  23 struct tzEntry;
  24
  25
  26 /* ----------------------------------------------------------------
  27  *                              time types + support macros
  28  *
  29  * String definitions for standard time quantities.
  30  *
  31  * These strings are the defaults used to form output time strings.
  32  * Other alternative forms are hardcoded into token tables in datetime.c.
  33  * ----------------------------------------------------------------
  34  */
  35
  36 #define DAGO                    "ago"
  37 #define DCURRENT                "current"
  38 #define EPOCH                   "epoch"
  39 #define INVALID                 "invalid"
  40 #define EARLY                   "-infinity"
  41 #define LATE                    "infinity"
  42 #define NOW                             "now"
  43 #define TODAY                   "today"
  44 #define TOMORROW                "tomorrow"
  45 #define YESTERDAY               "yesterday"
  46 #define ZULU                    "zulu"
  47
  48 #define DMICROSEC               "usecond"
  49 #define DMILLISEC               "msecond"
  50 #define DSECOND                 "second"
  51 #define DMINUTE                 "minute"
  52 #define DHOUR                   "hour"
  53 #define DDAY                    "day"
  54 #define DWEEK                   "week"
  55 #define DMONTH                  "month"
  56 #define DQUARTER                "quarter"
  57 #define DYEAR                   "year"
  58 #define DDECADE                 "decade"
  59 #define DCENTURY                "century"
  60 #define DMILLENNIUM             "millennium"
  61 #define DA_D                    "ad"
  62 #define DB_C                    "bc"
  63 #define DTIMEZONE               "timezone"
  64
  65 /*
  66  * Fundamental time field definitions for parsing.
  67  *
  68  *      Meridian:  am, pm, or 24-hour style.
  69  *      Millennium: ad, bc
  70  */
  71
  72 #define AM              0
  73 #define PM              1
  74 #define HR24    2
  75
  76 #define AD              0
  77 #define BC              1
  78
  79 /*
  80  * Fields for time decoding.
  81  *
  82  * Can't have more of these than there are bits in an unsigned int
  83  * since these are turned into bit masks during parsing and decoding.
  84  *
  85  * Furthermore, the values for YEAR, MONTH, DAY, HOUR, MINUTE, SECOND
  86  * must be in the range 0..14 so that the associated bitmasks can fit
  87  * into the left half of an INTERVAL's typmod value.  Since those bits
  88  * are stored in typmods, you can't change them without initdb!
  89  */
  90
  91 #define RESERV  0
  92 #define MONTH   1
  93 #define YEAR    2
  94 #define DAY             3
  95 #define JULIAN  4
  96 #define TZ              5
  97 #define DTZ             6
  98 #define DTZMOD  7
  99 #define IGNORE_DTF      8
 100 #define AMPM    9
 101 #define HOUR    10
 102 #define MINUTE  11
 103 #define SECOND  12
 104 #define MILLISECOND 13
 105 #define MICROSECOND 14
 106 #define DOY             15
 107 #define DOW             16
 108 #define UNITS   17
 109 #define ADBC    18
 110 /* these are only for relative dates */
 111 #define AGO             19
 112 #define ABS_BEFORE              20
 113 #define ABS_AFTER               21
 114 /* generic fields to help with parsing */
 115 #define ISODATE 22
 116 #define ISOTIME 23
 117 /* these are only for parsing intervals */
 118 #define WEEK            24
 119 #define DECADE          25
 120 #define CENTURY         26
 121 #define MILLENNIUM      27
 122 /* reserved for unrecognized string values */
 123 #define UNKNOWN_FIELD   31
 124
 125 /*
 126  * Token field definitions for time parsing and decoding.
 127  * These need to fit into the datetkn table type.
 128  * At the moment, that means keep them within [-127,127].
 129  * These are also used for bit masks in DecodeDateDelta()
 130  *      so actually restrict them to within [0,31] for now.
 131  * - thomas 97/06/19
 132  * Not all of these fields are used for masks in DecodeDateDelta
 133  *      so allow some larger than 31. - thomas 1997-11-17
 134  */
 135
 136 #define DTK_NUMBER              0
 137 #define DTK_STRING              1
 138
 139 #define DTK_DATE                2
 140 #define DTK_TIME                3
 141 #define DTK_TZ                  4
 142 #define DTK_AGO                 5
 143
 144 #define DTK_SPECIAL             6
 145 #define DTK_INVALID             7
 146 #define DTK_CURRENT             8
 147 #define DTK_EARLY               9
 148 #define DTK_LATE                10
 149 #define DTK_EPOCH               11
 150 #define DTK_NOW                 12
 151 #define DTK_YESTERDAY   13
 152 #define DTK_TODAY               14
 153 #define DTK_TOMORROW    15
 154 #define DTK_ZULU                16
 155
 156 #define DTK_DELTA               17
 157 #define DTK_SECOND              18
 158 #define DTK_MINUTE              19
 159 #define DTK_HOUR                20
 160 #define DTK_DAY                 21
 161 #define DTK_WEEK                22
 162 #define DTK_MONTH               23
 163 #define DTK_QUARTER             24
 164 #define DTK_YEAR                25
 165 #define DTK_DECADE              26
 166 #define DTK_CENTURY             27
 167 #define DTK_MILLENNIUM  28
 168 #define DTK_MILLISEC    29
 169 #define DTK_MICROSEC    30
 170 #define DTK_JULIAN              31
 171
 172 #define DTK_DOW                 32
 173 #define DTK_DOY                 33
 174 #define DTK_TZ_HOUR             34
 175 #define DTK_TZ_MINUTE   35
 176 #define DTK_ISOYEAR             36
 177 #define DTK_ISODOW              37
 178
 179
 180 /*
 181  * Bit mask definitions for time parsing.
 182  */
 183
 184 #define DTK_M(t)                (0x01 << (t))
 185
 186 /* Convenience: a second, plus any fractional component */
 187 #define DTK_ALL_SECS_M  (DTK_M(SECOND) | DTK_M(MILLISECOND) | DTK_M(MICROSECOND))
 188 #define DTK_DATE_M              (DTK_M(YEAR) | DTK_M(MONTH) | DTK_M(DAY))
 189 #define DTK_TIME_M              (DTK_M(HOUR) | DTK_M(MINUTE) | DTK_ALL_SECS_M)
 190
 191 /*
 192  * Working buffer size for input and output of interval, timestamp, etc.
 193  * Inputs that need more working space will be rejected early.  Longer outputs
 194  * will overrun buffers, so this must suffice for all possible output.  As of
 195  * this writing, interval_out() needs the most space at ~90 bytes.
 196  */
 197 #define MAXDATELEN              128
 198 /* maximum possible number of fields in a date string */
 199 #define MAXDATEFIELDS   25
 200 /* only this many chars are stored in datetktbl */
 201 #define TOKMAXLEN               10
 202
 203 /* keep this struct small; it gets used a lot */
 204 typedef struct
 205 {
 206         char            token[TOKMAXLEN];
 207         char            type;
 208         char            value;                  /* this may be unsigned, alas */
 209 } datetkn;
 210
 211 /* one of its uses is in tables of time zone abbreviations */
 212 typedef struct TimeZoneAbbrevTable
 213 {
 214         int                     numabbrevs;
 215         datetkn         abbrevs[1];             /* VARIABLE LENGTH ARRAY */
 216 } TimeZoneAbbrevTable;
 217
 218
 219 /* FMODULO()
 220  * Macro to replace modf(), which is broken on some platforms.
 221  * t = input and remainder
 222  * q = integer part
 223  * u = divisor
 224  */
 225 #define FMODULO(t,q,u) \
 226 do { \
 227         (q) = (((t) < 0) ? ceil((t) / (u)) : floor((t) / (u))); \
 228         if ((q) != 0) (t) -= rint((q) * (u)); \
 229 } while(0)
 230
 231 /* TMODULO()
 232  * Like FMODULO(), but work on the timestamp datatype (either int64 or float8).
 233  * We assume that int64 follows the C99 semantics for division (negative
 234  * quotients truncate towards zero).
 235  */
 236 #ifdef HAVE_INT64_TIMESTAMP
 237 #define TMODULO(t,q,u) \
 238 do { \
 239         (q) = ((t) / (u)); \
 240         if ((q) != 0) (t) -= ((q) * (u)); \
 241 } while(0)
 242 #else
 243 #define TMODULO(t,q,u) \
 244 do { \
 245         (q) = (((t) < 0) ? ceil((t) / (u)) : floor((t) / (u))); \
 246         if ((q) != 0) (t) -= rint((q) * (u)); \
 247 } while(0)
 248 #endif
 249
 250 /*
 251  * Date/time validation
 252  * Include check for leap year.
 253  */
 254
 255 extern const char *const months[];              /* months (3-char abbreviations) */
 256 extern const char *const days[];        /* days (full names) */
 257 extern const int day_tab[2][13];
 258
 259 #define isleap(y) (((y) % 4) == 0 && (((y) % 100) != 0 || ((y) % 400) == 0))
 260
 261
 262 /*
 263  * Datetime input parsing routines (ParseDateTime, DecodeDateTime, etc)
 264  * return zero or a positive value on success.  On failure, they return
 265  * one of these negative code values.  DateTimeParseError may be used to
 266  * produce a correct ereport.
 267  */
 268 #define DTERR_BAD_FORMAT                (-1)
 269 #define DTERR_FIELD_OVERFLOW    (-2)
 270 #define DTERR_MD_FIELD_OVERFLOW (-3)    /* triggers hint about DateStyle */
 271 #define DTERR_INTERVAL_OVERFLOW (-4)
 272 #define DTERR_TZDISP_OVERFLOW   (-5)
 273
 274
 275 extern void GetCurrentDateTime(struct pg_tm * tm);
 276 extern void GetCurrentTimeUsec(struct pg_tm * tm, fsec_t *fsec, int *tzp);
 277 extern void j2date(int jd, int *year, int *month, int *day);
 278 extern int      date2j(int year, int month, int day);
 279
 280 extern int ParseDateTime(const char *timestr, char *workbuf, size_t buflen,
 281                           char **field, int *ftype,
 282                           int maxfields, int *numfields);
 283 extern int DecodeDateTime(char **field, int *ftype,
 284                            int nf, int *dtype,
 285                            struct pg_tm * tm, fsec_t *fsec, int *tzp);
 286 extern int      DecodeTimezone(char *str, int *tzp);
 287 extern int DecodeTimeOnly(char **field, int *ftype,
 288                            int nf, int *dtype,
 289                            struct pg_tm * tm, fsec_t *fsec, int *tzp);
 290 extern int DecodeInterval(char **field, int *ftype, int nf, int range,
 291                            int *dtype, struct pg_tm * tm, fsec_t *fsec);
 292 extern int DecodeISO8601Interval(char *str,
 293                                           int *dtype, struct pg_tm * tm, fsec_t *fsec);
 294
 295 extern void DateTimeParseError(int dterr, const char *str,
 296                                    const char *datatype) __attribute__((noreturn));
 297
 298 extern int      DetermineTimeZoneOffset(struct pg_tm * tm, pg_tz *tzp);
 299
 300 extern void EncodeDateOnly(struct pg_tm * tm, int style, char *str);
 301 extern void EncodeTimeOnly(struct pg_tm * tm, fsec_t fsec, bool print_tz, int tz, int style, char *str);
 302 extern void EncodeDateTime(struct pg_tm * tm, fsec_t fsec, bool print_tz, int tz, const char *tzn, int style, char *str);
 303 extern void EncodeInterval(struct pg_tm * tm, fsec_t fsec, int style, char *str);
 304
 305 extern int ValidateDate(int fmask, bool isjulian, bool is2digits, bool bc,
 306                          struct pg_tm * tm);
 307
 308 extern int      DecodeSpecial(int field, char *lowtoken, int *val);
 309 extern int      DecodeUnits(int field, char *lowtoken, int *val);
 310
 311 extern int      j2day(int jd);
 312
 313 extern Node *TemporalTransform(int32 max_precis, Node *node);
 314
 315 extern bool CheckDateTokenTables(void);
 316
 317 extern void ConvertTimeZoneAbbrevs(TimeZoneAbbrevTable *tbl,
 318                                            struct tzEntry *abbrevs, int n);
 319 extern void InstallTimeZoneAbbrevs(TimeZoneAbbrevTable *tbl);
 320
 321 extern Datum pg_timezone_abbrevs(PG_FUNCTION_ARGS);
 322 extern Datum pg_timezone_names(PG_FUNCTION_ARGS);
 323
 324 #endif   /* DATETIME_H */