PostgreSQL Source Code  git master
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros
datetime.h
Go to the documentation of this file.
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-2017, 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 */
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 */
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 (now always int64).
248  * We assume that int64 follows the C99 semantics for division (negative
249  * quotients truncate towards zero).
250  */
251 #define TMODULO(t,q,u) \
252 do { \
253  (q) = ((t) / (u)); \
254  if ((q) != 0) (t) -= ((q) * (u)); \
255 } while(0)
256 
257 /*
258  * Date/time validation
259  * Include check for leap year.
260  */
261 
262 extern const char *const months[]; /* months (3-char abbreviations) */
263 extern const char *const days[]; /* days (full names) */
264 extern const int day_tab[2][13];
265 
266 /*
267  * These are the rules for the Gregorian calendar, which was adopted in 1582.
268  * However, we use this calculation for all prior years as well because the
269  * SQL standard specifies use of the Gregorian calendar. This prevents the
270  * date 1500-02-29 from being stored, even though it is valid in the Julian
271  * calendar.
272  */
273 #define isleap(y) (((y) % 4) == 0 && (((y) % 100) != 0 || ((y) % 400) == 0))
274 
275 
276 /*
277  * Datetime input parsing routines (ParseDateTime, DecodeDateTime, etc)
278  * return zero or a positive value on success. On failure, they return
279  * one of these negative code values. DateTimeParseError may be used to
280  * produce a correct ereport.
281  */
282 #define DTERR_BAD_FORMAT (-1)
283 #define DTERR_FIELD_OVERFLOW (-2)
284 #define DTERR_MD_FIELD_OVERFLOW (-3) /* triggers hint about DateStyle */
285 #define DTERR_INTERVAL_OVERFLOW (-4)
286 #define DTERR_TZDISP_OVERFLOW (-5)
287 
288 
289 extern void GetCurrentDateTime(struct pg_tm * tm);
290 extern void GetCurrentTimeUsec(struct pg_tm * tm, fsec_t *fsec, int *tzp);
291 extern void j2date(int jd, int *year, int *month, int *day);
292 extern int date2j(int year, int month, int day);
293 
294 extern int ParseDateTime(const char *timestr, char *workbuf, size_t buflen,
295  char **field, int *ftype,
296  int maxfields, int *numfields);
297 extern int DecodeDateTime(char **field, int *ftype,
298  int nf, int *dtype,
299  struct pg_tm * tm, fsec_t *fsec, int *tzp);
300 extern int DecodeTimezone(char *str, int *tzp);
301 extern int DecodeTimeOnly(char **field, int *ftype,
302  int nf, int *dtype,
303  struct pg_tm * tm, fsec_t *fsec, int *tzp);
304 extern int DecodeInterval(char **field, int *ftype, int nf, int range,
305  int *dtype, struct pg_tm * tm, fsec_t *fsec);
306 extern int DecodeISO8601Interval(char *str,
307  int *dtype, struct pg_tm * tm, fsec_t *fsec);
308 
309 extern void DateTimeParseError(int dterr, const char *str,
310  const char *datatype) pg_attribute_noreturn();
311 
312 extern int DetermineTimeZoneOffset(struct pg_tm * tm, pg_tz *tzp);
313 extern int DetermineTimeZoneAbbrevOffset(struct pg_tm * tm, const char *abbr, pg_tz *tzp);
314 extern int DetermineTimeZoneAbbrevOffsetTS(TimestampTz ts, const char *abbr,
315  pg_tz *tzp, int *isdst);
316 
317 extern void EncodeDateOnly(struct pg_tm * tm, int style, char *str);
318 extern void EncodeTimeOnly(struct pg_tm * tm, fsec_t fsec, bool print_tz, int tz, int style, char *str);
319 extern void EncodeDateTime(struct pg_tm * tm, fsec_t fsec, bool print_tz, int tz, const char *tzn, int style, char *str);
320 extern void EncodeInterval(struct pg_tm * tm, fsec_t fsec, int style, char *str);
321 extern void EncodeSpecialTimestamp(Timestamp dt, char *str);
322 
323 extern int ValidateDate(int fmask, bool isjulian, bool is2digits, bool bc,
324  struct pg_tm * tm);
325 
326 extern int DecodeTimezoneAbbrev(int field, char *lowtoken,
327  int *offset, pg_tz **tz);
328 extern int DecodeSpecial(int field, char *lowtoken, int *val);
329 extern int DecodeUnits(int field, char *lowtoken, int *val);
330 
331 extern int j2day(int jd);
332 
333 extern Node *TemporalTransform(int32 max_precis, Node *node);
334 
335 extern bool CheckDateTokenTables(void);
336 
337 extern TimeZoneAbbrevTable *ConvertTimeZoneAbbrevs(struct tzEntry *abbrevs,
338  int n);
340 
341 #endif /* DATETIME_H */
int j2day(int jd)
Definition: datetime.c:352
int DecodeISO8601Interval(char *str, int *dtype, struct pg_tm *tm, fsec_t *fsec)
Definition: datetime.c:3521
const char *const days[]
Definition: datetime.c:69
int DetermineTimeZoneOffset(struct pg_tm *tm, pg_tz *tzp)
Definition: datetime.c:1471
int64 TimestampTz
Definition: timestamp.h:39
void GetCurrentDateTime(struct pg_tm *tm)
Definition: datetime.c:370
void EncodeInterval(struct pg_tm *tm, fsec_t fsec, int style, char *str)
Definition: datetime.c:4241
Node * TemporalTransform(int32 max_precis, Node *node)
Definition: datetime.c:4486
void EncodeDateOnly(struct pg_tm *tm, int style, char *str)
Definition: datetime.c:3884
Definition: nodes.h:509
int DecodeTimeOnly(char **field, int *ftype, int nf, int *dtype, struct pg_tm *tm, fsec_t *fsec, int *tzp)
Definition: datetime.c:1744
void EncodeTimeOnly(struct pg_tm *tm, fsec_t fsec, bool print_tz, int tz, int style, char *str)
Definition: datetime.c:3969
int32 value
Definition: datetime.h:214
#define pg_attribute_noreturn()
Definition: c.h:649
Definition: pgtime.h:25
int DecodeDateTime(char **field, int *ftype, int nf, int *dtype, struct pg_tm *tm, fsec_t *fsec, int *tzp)
Definition: datetime.c:783
const char *const months[]
Definition: datetime.c:66
void EncodeSpecialTimestamp(Timestamp dt, char *str)
Definition: timestamp.c:1522
int date2j(int year, int month, int day)
Definition: datetime.c:292
signed int int32
Definition: c.h:253
static struct pg_tm tm
Definition: localtime.c:103
int ValidateDate(int fmask, bool isjulian, bool is2digits, bool bc, struct pg_tm *tm)
Definition: datetime.c:2479
datetkn abbrevs[FLEXIBLE_ARRAY_MEMBER]
Definition: datetime.h:222
const int day_tab[2][13]
Definition: datetime.c:60
void j2date(int jd, int *year, int *month, int *day)
Definition: datetime.c:317
TimeZoneAbbrevTable * ConvertTimeZoneAbbrevs(struct tzEntry *abbrevs, int n)
Definition: datetime.c:4519
int DecodeUnits(int field, char *lowtoken, int *val)
Definition: datetime.c:3728
int DecodeTimezoneAbbrev(int field, char *lowtoken, int *offset, pg_tz **tz)
Definition: datetime.c:2984
void GetCurrentTimeUsec(struct pg_tm *tm, fsec_t *fsec, int *tzp)
Definition: datetime.c:387
int ParseDateTime(const char *timestr, char *workbuf, size_t buflen, char **field, int *ftype, int maxfields, int *numfields)
Definition: datetime.c:562
int32 fsec_t
Definition: timestamp.h:41
int DetermineTimeZoneAbbrevOffsetTS(TimestampTz ts, const char *abbr, pg_tz *tzp, int *isdst)
Definition: datetime.c:1667
static struct cvec * range(struct vars *v, chr a, chr b, int cases)
Definition: regc_locale.c:416
void DateTimeParseError(int dterr, const char *str, const char *datatype) pg_attribute_noreturn()
Definition: datetime.c:3765
int64 Timestamp
Definition: timestamp.h:38
int DecodeSpecial(int field, char *lowtoken, int *val)
Definition: datetime.c:3039
Definition: pgtz.h:59
char type
Definition: datetime.h:213
struct DynamicZoneAbbrev DynamicZoneAbbrev
size_t Size
Definition: c.h:353
int DecodeTimezone(char *str, int *tzp)
Definition: datetime.c:2906
void InstallTimeZoneAbbrevs(TimeZoneAbbrevTable *tbl)
Definition: datetime.c:4603
int DecodeInterval(char **field, int *ftype, int nf, int range, int *dtype, struct pg_tm *tm, fsec_t *fsec)
Definition: datetime.c:3095
Definition: zic.c:90
int DetermineTimeZoneAbbrevOffset(struct pg_tm *tm, const char *abbr, pg_tz *tzp)
Definition: datetime.c:1629
#define TOKMAXLEN
Definition: datetime.h:207
struct TimeZoneAbbrevTable TimeZoneAbbrevTable
void EncodeDateTime(struct pg_tm *tm, fsec_t fsec, bool print_tz, int tz, const char *tzn, int style, char *str)
Definition: datetime.c:3999
long val
Definition: informix.c:689
bool CheckDateTokenTables(void)
Definition: datetime.c:4464