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-2016, 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 * Field types 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 /* fixed-offset timezone abbreviation */ 97 #define DTZ 6 /* fixed-offset timezone abbrev, DST */ 98 #define DYNTZ 7 /* dynamic timezone abbreviation */ 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 /* hack for parsing two-word timezone specs "MET DST" etc */ 123 #define DTZMOD 28 /* "DST" as a separate word */ 124 /* reserved for unrecognized string values */ 125 #define UNKNOWN_FIELD 31 126 127 /* 128 * Token field definitions for time parsing and decoding. 129 * 130 * Some field type codes (see above) use these as the "value" in datetktbl[]. 131 * These are also used for bit masks in DecodeDateTime and friends 132 * so actually restrict them to within [0,31] for now. 133 * - thomas 97/06/19 134 * Not all of these fields are used for masks in DecodeDateTime 135 * so allow some larger than 31. - thomas 1997-11-17 136 * 137 * Caution: there are undocumented assumptions in the code that most of these 138 * values are not equal to IGNORE_DTF nor RESERV. Be very careful when 139 * renumbering values in either of these apparently-independent lists :-( 140 */ 141 142 #define DTK_NUMBER 0 143 #define DTK_STRING 1 144 145 #define DTK_DATE 2 146 #define DTK_TIME 3 147 #define DTK_TZ 4 148 #define DTK_AGO 5 149 150 #define DTK_SPECIAL 6 151 #define DTK_INVALID 7 152 #define DTK_CURRENT 8 153 #define DTK_EARLY 9 154 #define DTK_LATE 10 155 #define DTK_EPOCH 11 156 #define DTK_NOW 12 157 #define DTK_YESTERDAY 13 158 #define DTK_TODAY 14 159 #define DTK_TOMORROW 15 160 #define DTK_ZULU 16 161 162 #define DTK_DELTA 17 163 #define DTK_SECOND 18 164 #define DTK_MINUTE 19 165 #define DTK_HOUR 20 166 #define DTK_DAY 21 167 #define DTK_WEEK 22 168 #define DTK_MONTH 23 169 #define DTK_QUARTER 24 170 #define DTK_YEAR 25 171 #define DTK_DECADE 26 172 #define DTK_CENTURY 27 173 #define DTK_MILLENNIUM 28 174 #define DTK_MILLISEC 29 175 #define DTK_MICROSEC 30 176 #define DTK_JULIAN 31 177 178 #define DTK_DOW 32 179 #define DTK_DOY 33 180 #define DTK_TZ_HOUR 34 181 #define DTK_TZ_MINUTE 35 182 #define DTK_ISOYEAR 36 183 #define DTK_ISODOW 37 184 185 186 /* 187 * Bit mask definitions for time parsing. 188 */ 189 190 #define DTK_M(t) (0x01 << (t)) 191 192 /* Convenience: a second, plus any fractional component */ 193 #define DTK_ALL_SECS_M (DTK_M(SECOND) | DTK_M(MILLISECOND) | DTK_M(MICROSECOND)) 194 #define DTK_DATE_M (DTK_M(YEAR) | DTK_M(MONTH) | DTK_M(DAY)) 195 #define DTK_TIME_M (DTK_M(HOUR) | DTK_M(MINUTE) | DTK_ALL_SECS_M) 196 197 /* 198 * Working buffer size for input and output of interval, timestamp, etc. 199 * Inputs that need more working space will be rejected early. Longer outputs 200 * will overrun buffers, so this must suffice for all possible output. As of 201 * this writing, interval_out() needs the most space at ~90 bytes. 202 */ 203 #define MAXDATELEN 128 204 /* maximum possible number of fields in a date string */ 205 #define MAXDATEFIELDS 25 206 /* only this many chars are stored in datetktbl */ 207 #define TOKMAXLEN 10 208 209 /* keep this struct small; it gets used a lot */ 210 typedef struct 211 { 212 char token[TOKMAXLEN + 1]; /* always NUL-terminated */ 213 char type; /* see field type codes above */ 214 int32 value; /* meaning depends on type */ 215 } datetkn; 216 217 /* one of its uses is in tables of time zone abbreviations */ 218 typedef struct TimeZoneAbbrevTable 219 { 220 Size tblsize; /* size in bytes of TimeZoneAbbrevTable */ 221 int numabbrevs; /* number of entries in abbrevs[] array */ 222 datetkn abbrevs[FLEXIBLE_ARRAY_MEMBER]; 223 /* DynamicZoneAbbrev(s) may follow the abbrevs[] array */ 224 } TimeZoneAbbrevTable; 225 226 /* auxiliary data for a dynamic time zone abbreviation (non-fixed-offset) */ 227 typedef struct DynamicZoneAbbrev 228 { 229 pg_tz *tz; /* NULL if not yet looked up */ 230 char zone[FLEXIBLE_ARRAY_MEMBER]; /* NUL-terminated zone name */ 231 } DynamicZoneAbbrev; 232 233 234 /* FMODULO() 235 * Macro to replace modf(), which is broken on some platforms. 236 * t = input and remainder 237 * q = integer part 238 * u = divisor 239 */ 240 #define FMODULO(t,q,u) \ 241 do { \ 242 (q) = (((t) < 0) ? ceil((t) / (u)) : floor((t) / (u))); \ 243 if ((q) != 0) (t) -= rint((q) * (u)); \ 244 } while(0) 245 246 /* TMODULO() 247 * Like FMODULO(), but work on the timestamp datatype (either int64 or float8). 248 * We assume that int64 follows the C99 semantics for division (negative 249 * quotients truncate towards zero). 250 */ 251 #ifdef HAVE_INT64_TIMESTAMP 252 #define TMODULO(t,q,u) \ 253 do { \ 254 (q) = ((t) / (u)); \ 255 if ((q) != 0) (t) -= ((q) * (u)); \ 256 } while(0) 257 #else 258 #define TMODULO(t,q,u) \ 259 do { \ 260 (q) = (((t) < 0) ? ceil((t) / (u)) : floor((t) / (u))); \ 261 if ((q) != 0) (t) -= rint((q) * (u)); \ 262 } while(0) 263 #endif 264 265 /* 266 * Date/time validation 267 * Include check for leap year. 268 */ 269 270 extern const char *const months[]; /* months (3-char abbreviations) */ 271 extern const char *const days[]; /* days (full names) */ 272 extern const int day_tab[2][13]; 273 274 /* 275 * These are the rules for the Gregorian calendar, which was adopted in 1582. 276 * However, we use this calculation for all prior years as well because the 277 * SQL standard specifies use of the Gregorian calendar. This prevents the 278 * date 1500-02-29 from being stored, even though it is valid in the Julian 279 * calendar. 280 */ 281 #define isleap(y) (((y) % 4) == 0 && (((y) % 100) != 0 || ((y) % 400) == 0)) 282 283 284 /* 285 * Datetime input parsing routines (ParseDateTime, DecodeDateTime, etc) 286 * return zero or a positive value on success. On failure, they return 287 * one of these negative code values. DateTimeParseError may be used to 288 * produce a correct ereport. 289 */ 290 #define DTERR_BAD_FORMAT (-1) 291 #define DTERR_FIELD_OVERFLOW (-2) 292 #define DTERR_MD_FIELD_OVERFLOW (-3) /* triggers hint about DateStyle */ 293 #define DTERR_INTERVAL_OVERFLOW (-4) 294 #define DTERR_TZDISP_OVERFLOW (-5) 295 296 297 extern void GetCurrentDateTime(struct pg_tm * tm); 298 extern void GetCurrentTimeUsec(struct pg_tm * tm, fsec_t *fsec, int *tzp); 299 extern void j2date(int jd, int *year, int *month, int *day); 300 extern int date2j(int year, int month, int day); 301 302 extern int ParseDateTime(const char *timestr, char *workbuf, size_t buflen, 303 char **field, int *ftype, 304 int maxfields, int *numfields); 305 extern int DecodeDateTime(char **field, int *ftype, 306 int nf, int *dtype, 307 struct pg_tm * tm, fsec_t *fsec, int *tzp); 308 extern int DecodeTimezone(char *str, int *tzp); 309 extern int DecodeTimeOnly(char **field, int *ftype, 310 int nf, int *dtype, 311 struct pg_tm * tm, fsec_t *fsec, int *tzp); 312 extern int DecodeInterval(char **field, int *ftype, int nf, int range, 313 int *dtype, struct pg_tm * tm, fsec_t *fsec); 314 extern int DecodeISO8601Interval(char *str, 315 int *dtype, struct pg_tm * tm, fsec_t *fsec); 316 317 extern void DateTimeParseError(int dterr, const char *str, 318 const char *datatype) pg_attribute_noreturn(); 319 320 extern int DetermineTimeZoneOffset(struct pg_tm * tm, pg_tz *tzp); 321 extern int DetermineTimeZoneAbbrevOffset(struct pg_tm * tm, const char *abbr, pg_tz *tzp); 322 extern int DetermineTimeZoneAbbrevOffsetTS(TimestampTz ts, const char *abbr, 323 pg_tz *tzp, int *isdst); 324 325 extern void EncodeDateOnly(struct pg_tm * tm, int style, char *str); 326 extern void EncodeTimeOnly(struct pg_tm * tm, fsec_t fsec, bool print_tz, int tz, int style, char *str); 327 extern void EncodeDateTime(struct pg_tm * tm, fsec_t fsec, bool print_tz, int tz, const char *tzn, int style, char *str); 328 extern void EncodeInterval(struct pg_tm * tm, fsec_t fsec, int style, char *str); 329 extern void EncodeSpecialTimestamp(Timestamp dt, char *str); 330 331 extern int ValidateDate(int fmask, bool isjulian, bool is2digits, bool bc, 332 struct pg_tm * tm); 333 334 extern int DecodeTimezoneAbbrev(int field, char *lowtoken, 335 int *offset, pg_tz **tz); 336 extern int DecodeSpecial(int field, char *lowtoken, int *val); 337 extern int DecodeUnits(int field, char *lowtoken, int *val); 338 339 extern int j2day(int jd); 340 341 extern Node *TemporalTransform(int32 max_precis, Node *node); 342 343 extern bool CheckDateTokenTables(void); 344 345 extern TimeZoneAbbrevTable *ConvertTimeZoneAbbrevs(struct tzEntry *abbrevs, 346 int n); 347 extern void InstallTimeZoneAbbrevs(TimeZoneAbbrevTable *tbl); 348 349 extern Datum pg_timezone_abbrevs(PG_FUNCTION_ARGS); 350 extern Datum pg_timezone_names(PG_FUNCTION_ARGS); 351 352 #endif /* DATETIME_H */ 353