PostgreSQL Source Code  git master
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 date, and time.
7  *
8  *
9  * Portions Copyright (c) 1996-2024, 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 "utils/timestamp.h"
20 
21 /* this struct is declared in utils/tzparser.h: */
22 struct tzEntry;
23 
24 
25 /* ----------------------------------------------------------------
26  * time types + support macros
27  *
28  * String definitions for standard time quantities.
29  *
30  * These strings are the defaults used to form output time strings.
31  * Other alternative forms are hardcoded into token tables in datetime.c.
32  * ----------------------------------------------------------------
33  */
34 
35 #define DAGO "ago"
36 #define DCURRENT "current"
37 #define EPOCH "epoch"
38 #define INVALID "invalid"
39 #define EARLY "-infinity"
40 #define LATE "infinity"
41 #define NOW "now"
42 #define TODAY "today"
43 #define TOMORROW "tomorrow"
44 #define YESTERDAY "yesterday"
45 #define ZULU "zulu"
46 
47 #define DMICROSEC "usecond"
48 #define DMILLISEC "msecond"
49 #define DSECOND "second"
50 #define DMINUTE "minute"
51 #define DHOUR "hour"
52 #define DDAY "day"
53 #define DWEEK "week"
54 #define DMONTH "month"
55 #define DQUARTER "quarter"
56 #define DYEAR "year"
57 #define DDECADE "decade"
58 #define DCENTURY "century"
59 #define DMILLENNIUM "millennium"
60 #define DA_D "ad"
61 #define DB_C "bc"
62 #define DTIMEZONE "timezone"
63 
64 /*
65  * Fundamental time field definitions for parsing.
66  *
67  * Meridian: am, pm, or 24-hour style.
68  * Millennium: ad, bc
69  */
70 
71 #define AM 0
72 #define PM 1
73 #define HR24 2
74 
75 #define AD 0
76 #define BC 1
77 
78 /*
79  * Field types for time decoding.
80  *
81  * Can't have more of these than there are bits in an unsigned int
82  * since these are turned into bit masks during parsing and decoding.
83  *
84  * Furthermore, the values for YEAR, MONTH, DAY, HOUR, MINUTE, SECOND
85  * must be in the range 0..14 so that the associated bitmasks can fit
86  * into the left half of an INTERVAL's typmod value. Since those bits
87  * are stored in typmods, you can't change them without initdb!
88  */
89 
90 #define RESERV 0
91 #define MONTH 1
92 #define YEAR 2
93 #define DAY 3
94 #define JULIAN 4
95 #define TZ 5 /* fixed-offset timezone abbreviation */
96 #define DTZ 6 /* fixed-offset timezone abbrev, DST */
97 #define DYNTZ 7 /* dynamic timezone abbreviation */
98 #define IGNORE_DTF 8
99 #define AMPM 9
100 #define HOUR 10
101 #define MINUTE 11
102 #define SECOND 12
103 #define MILLISECOND 13
104 #define MICROSECOND 14
105 #define DOY 15
106 #define DOW 16
107 #define UNITS 17
108 #define ADBC 18
109 /* these are only for relative dates */
110 #define AGO 19
111 #define ABS_BEFORE 20
112 #define ABS_AFTER 21
113 /* generic fields to help with parsing */
114 #define ISODATE 22
115 #define ISOTIME 23
116 /* these are only for parsing intervals */
117 #define WEEK 24
118 #define DECADE 25
119 #define CENTURY 26
120 #define MILLENNIUM 27
121 /* hack for parsing two-word timezone specs "MET DST" etc */
122 #define DTZMOD 28 /* "DST" as a separate word */
123 /* reserved for unrecognized string values */
124 #define UNKNOWN_FIELD 31
125 
126 /*
127  * Token field definitions for time parsing and decoding.
128  *
129  * Some field type codes (see above) use these as the "value" in datetktbl[].
130  * These are also used for bit masks in DecodeDateTime and friends
131  * so actually restrict them to within [0,31] for now.
132  * - thomas 97/06/19
133  * Not all of these fields are used for masks in DecodeDateTime
134  * so allow some larger than 31. - thomas 1997-11-17
135  *
136  * Caution: there are undocumented assumptions in the code that most of these
137  * values are not equal to IGNORE_DTF nor RESERV. Be very careful when
138  * renumbering values in either of these apparently-independent lists :-(
139  */
140 
141 #define DTK_NUMBER 0
142 #define DTK_STRING 1
143 
144 #define DTK_DATE 2
145 #define DTK_TIME 3
146 #define DTK_TZ 4
147 #define DTK_AGO 5
148 
149 #define DTK_SPECIAL 6
150 #define DTK_EARLY 9
151 #define DTK_LATE 10
152 #define DTK_EPOCH 11
153 #define DTK_NOW 12
154 #define DTK_YESTERDAY 13
155 #define DTK_TODAY 14
156 #define DTK_TOMORROW 15
157 #define DTK_ZULU 16
158 
159 #define DTK_DELTA 17
160 #define DTK_SECOND 18
161 #define DTK_MINUTE 19
162 #define DTK_HOUR 20
163 #define DTK_DAY 21
164 #define DTK_WEEK 22
165 #define DTK_MONTH 23
166 #define DTK_QUARTER 24
167 #define DTK_YEAR 25
168 #define DTK_DECADE 26
169 #define DTK_CENTURY 27
170 #define DTK_MILLENNIUM 28
171 #define DTK_MILLISEC 29
172 #define DTK_MICROSEC 30
173 #define DTK_JULIAN 31
174 
175 #define DTK_DOW 32
176 #define DTK_DOY 33
177 #define DTK_TZ_HOUR 34
178 #define DTK_TZ_MINUTE 35
179 #define DTK_ISOYEAR 36
180 #define DTK_ISODOW 37
181 
182 
183 /*
184  * Bit mask definitions for time parsing.
185  */
186 
187 #define DTK_M(t) (0x01 << (t))
188 
189 /* Convenience: a second, plus any fractional component */
190 #define DTK_ALL_SECS_M (DTK_M(SECOND) | DTK_M(MILLISECOND) | DTK_M(MICROSECOND))
191 #define DTK_DATE_M (DTK_M(YEAR) | DTK_M(MONTH) | DTK_M(DAY))
192 #define DTK_TIME_M (DTK_M(HOUR) | DTK_M(MINUTE) | DTK_ALL_SECS_M)
193 
194 /*
195  * Working buffer size for input and output of interval, timestamp, etc.
196  * Inputs that need more working space will be rejected early. Longer outputs
197  * will overrun buffers, so this must suffice for all possible output. As of
198  * this writing, interval_out() needs the most space at ~90 bytes.
199  */
200 #define MAXDATELEN 128
201 /* maximum possible number of fields in a date string */
202 #define MAXDATEFIELDS 25
203 /* only this many chars are stored in datetktbl */
204 #define TOKMAXLEN 10
205 
206 /* keep this struct small; it gets used a lot */
207 typedef struct
208 {
209  char token[TOKMAXLEN + 1]; /* always NUL-terminated */
210  char type; /* see field type codes above */
211  int32 value; /* meaning depends on type */
212 } datetkn;
213 
214 /* one of its uses is in tables of time zone abbreviations */
215 typedef struct TimeZoneAbbrevTable
216 {
217  Size tblsize; /* size in bytes of TimeZoneAbbrevTable */
218  int numabbrevs; /* number of entries in abbrevs[] array */
220  /* DynamicZoneAbbrev(s) may follow the abbrevs[] array */
222 
223 /* auxiliary data for a dynamic time zone abbreviation (non-fixed-offset) */
224 typedef struct DynamicZoneAbbrev
225 {
226  pg_tz *tz; /* NULL if not yet looked up */
227  char zone[FLEXIBLE_ARRAY_MEMBER]; /* NUL-terminated zone name */
229 
230 
231 /* FMODULO()
232  * Macro to replace modf(), which is broken on some platforms.
233  * t = input and remainder
234  * q = integer part
235  * u = divisor
236  */
237 #define FMODULO(t,q,u) \
238 do { \
239  (q) = (((t) < 0) ? ceil((t) / (u)) : floor((t) / (u))); \
240  if ((q) != 0) (t) -= rint((q) * (u)); \
241 } while(0)
242 
243 /* TMODULO()
244  * Like FMODULO(), but work on the timestamp datatype (now always int64).
245  * We assume that int64 follows the C99 semantics for division (negative
246  * quotients truncate towards zero).
247  */
248 #define TMODULO(t,q,u) \
249 do { \
250  (q) = ((t) / (u)); \
251  if ((q) != 0) (t) -= ((q) * (u)); \
252 } while(0)
253 
254 /*
255  * Date/time validation
256  * Include check for leap year.
257  */
258 
259 extern PGDLLIMPORT const char *const months[]; /* months (3-char
260  * abbreviations) */
261 extern PGDLLIMPORT const char *const days[]; /* days (full names) */
262 extern PGDLLIMPORT const int day_tab[2][13];
263 
264 /*
265  * These are the rules for the Gregorian calendar, which was adopted in 1582.
266  * However, we use this calculation for all prior years as well because the
267  * SQL standard specifies use of the Gregorian calendar. This prevents the
268  * date 1500-02-29 from being stored, even though it is valid in the Julian
269  * calendar.
270  */
271 #define isleap(y) (((y) % 4) == 0 && (((y) % 100) != 0 || ((y) % 400) == 0))
272 
273 
274 /*
275  * Datetime input parsing routines (ParseDateTime, DecodeDateTime, etc)
276  * return zero or a positive value on success. On failure, they return
277  * one of these negative code values. DateTimeParseError may be used to
278  * produce a suitable error report. For some of these codes,
279  * DateTimeParseError requires additional information, which is carried
280  * in struct DateTimeErrorExtra.
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 #define DTERR_BAD_TIMEZONE (-6)
288 #define DTERR_BAD_ZONE_ABBREV (-7)
289 
290 typedef struct DateTimeErrorExtra
291 {
292  /* Needed for DTERR_BAD_TIMEZONE and DTERR_BAD_ZONE_ABBREV: */
293  const char *dtee_timezone; /* incorrect time zone name */
294  /* Needed for DTERR_BAD_ZONE_ABBREV: */
295  const char *dtee_abbrev; /* relevant time zone abbreviation */
297 
298 /* Result codes for DecodeTimezoneName() */
299 #define TZNAME_FIXED_OFFSET 0
300 #define TZNAME_DYNTZ 1
301 #define TZNAME_ZONE 2
302 
303 
304 extern void GetCurrentDateTime(struct pg_tm *tm);
305 extern void GetCurrentTimeUsec(struct pg_tm *tm, fsec_t *fsec, int *tzp);
306 extern void j2date(int jd, int *year, int *month, int *day);
307 extern int date2j(int year, int month, int day);
308 
309 extern int ParseDateTime(const char *timestr, char *workbuf, size_t buflen,
310  char **field, int *ftype,
311  int maxfields, int *numfields);
312 extern int DecodeDateTime(char **field, int *ftype, int nf,
313  int *dtype, struct pg_tm *tm, fsec_t *fsec, int *tzp,
314  DateTimeErrorExtra *extra);
315 extern int DecodeTimezone(const char *str, int *tzp);
316 extern int DecodeTimeOnly(char **field, int *ftype, int nf,
317  int *dtype, struct pg_tm *tm, fsec_t *fsec, int *tzp,
318  DateTimeErrorExtra *extra);
319 extern int DecodeInterval(char **field, int *ftype, int nf, int range,
320  int *dtype, struct pg_itm_in *itm_in);
321 extern int DecodeISO8601Interval(char *str,
322  int *dtype, struct pg_itm_in *itm_in);
323 
324 extern void DateTimeParseError(int dterr, DateTimeErrorExtra *extra,
325  const char *str, const char *datatype,
326  struct Node *escontext);
327 
328 extern int DetermineTimeZoneOffset(struct pg_tm *tm, pg_tz *tzp);
329 extern int DetermineTimeZoneAbbrevOffset(struct pg_tm *tm, const char *abbr, pg_tz *tzp);
330 extern int DetermineTimeZoneAbbrevOffsetTS(TimestampTz ts, const char *abbr,
331  pg_tz *tzp, int *isdst);
332 
333 extern void EncodeDateOnly(struct pg_tm *tm, int style, char *str);
334 extern void EncodeTimeOnly(struct pg_tm *tm, fsec_t fsec, bool print_tz, int tz, int style, char *str);
335 extern void EncodeDateTime(struct pg_tm *tm, fsec_t fsec, bool print_tz, int tz, const char *tzn, int style, char *str);
336 extern void EncodeInterval(struct pg_itm *itm, int style, char *str);
337 extern void EncodeSpecialTimestamp(Timestamp dt, char *str);
338 
339 extern int ValidateDate(int fmask, bool isjulian, bool is2digits, bool bc,
340  struct pg_tm *tm);
341 
342 extern int DecodeTimezoneAbbrev(int field, const char *lowtoken,
343  int *ftype, int *offset, pg_tz **tz,
344  DateTimeErrorExtra *extra);
345 extern int DecodeSpecial(int field, const char *lowtoken, int *val);
346 extern int DecodeUnits(int field, const char *lowtoken, int *val);
347 
348 extern int DecodeTimezoneName(const char *tzname, int *offset, pg_tz **tz);
349 extern pg_tz *DecodeTimezoneNameToTz(const char *tzname);
350 
351 extern int DecodeTimezoneAbbrevPrefix(const char *str,
352  int *offset, pg_tz **tz);
353 
354 extern int j2day(int date);
355 
356 extern struct Node *TemporalSimplify(int32 max_precis, struct Node *node);
357 
358 extern bool CheckDateTokenTables(void);
359 
360 extern TimeZoneAbbrevTable *ConvertTimeZoneAbbrevs(struct tzEntry *abbrevs,
361  int n);
363 
364 extern bool AdjustTimestampForTypmod(Timestamp *time, int32 typmod,
365  struct Node *escontext);
366 
367 #endif /* DATETIME_H */
#define PGDLLIMPORT
Definition: c.h:1303
signed int int32
Definition: c.h:481
#define FLEXIBLE_ARRAY_MEMBER
Definition: c.h:385
size_t Size
Definition: c.h:592
int64 Timestamp
Definition: timestamp.h:38
int64 TimestampTz
Definition: timestamp.h:39
int32 fsec_t
Definition: timestamp.h:41
pg_tz * DecodeTimezoneNameToTz(const char *tzname)
Definition: datetime.c:3234
int DetermineTimeZoneAbbrevOffsetTS(TimestampTz ts, const char *abbr, pg_tz *tzp, int *isdst)
Definition: datetime.c:1784
PGDLLIMPORT const char *const months[]
Definition: datetime.c:81
void InstallTimeZoneAbbrevs(TimeZoneAbbrevTable *tbl)
Definition: datetime.c:4946
int DecodeUnits(int field, const char *lowtoken, int *val)
Definition: datetime.c:4036
int DecodeTimeOnly(char **field, int *ftype, int nf, int *dtype, struct pg_tm *tm, fsec_t *fsec, int *tzp, DateTimeErrorExtra *extra)
Definition: datetime.c:1864
int j2day(int date)
Definition: datetime.c:344
int ParseDateTime(const char *timestr, char *workbuf, size_t buflen, char **field, int *ftype, int maxfields, int *numfields)
Definition: datetime.c:754
bool AdjustTimestampForTypmod(Timestamp *time, int32 typmod, struct Node *escontext)
Definition: timestamp.c:366
void EncodeInterval(struct pg_itm *itm, int style, char *str)
Definition: datetime.c:4574
struct DateTimeErrorExtra DateTimeErrorExtra
int DetermineTimeZoneOffset(struct pg_tm *tm, pg_tz *tzp)
Definition: datetime.c:1585
int DecodeInterval(char **field, int *ftype, int nf, int range, int *dtype, struct pg_itm_in *itm_in)
Definition: datetime.c:3353
PGDLLIMPORT const int day_tab[2][13]
Definition: datetime.c:75
void EncodeSpecialTimestamp(Timestamp dt, char *str)
Definition: timestamp.c:1596
bool CheckDateTokenTables(void)
Definition: datetime.c:4800
int DecodeTimezoneAbbrev(int field, const char *lowtoken, int *ftype, int *offset, pg_tz **tz, DateTimeErrorExtra *extra)
Definition: datetime.c:3080
void EncodeTimeOnly(struct pg_tm *tm, fsec_t fsec, bool print_tz, int tz, int style, char *str)
Definition: datetime.c:4301
int DecodeISO8601Interval(char *str, int *dtype, struct pg_itm_in *itm_in)
Definition: datetime.c:3818
int ValidateDate(int fmask, bool isjulian, bool is2digits, bool bc, struct pg_tm *tm)
Definition: datetime.c:2497
struct TimeZoneAbbrevTable TimeZoneAbbrevTable
int DecodeSpecial(int field, const char *lowtoken, int *val)
Definition: datetime.c:3137
void j2date(int jd, int *year, int *month, int *day)
Definition: datetime.c:311
void GetCurrentDateTime(struct pg_tm *tm)
Definition: datetime.c:366
PGDLLIMPORT const char *const days[]
Definition: datetime.c:84
TimeZoneAbbrevTable * ConvertTimeZoneAbbrevs(struct tzEntry *abbrevs, int n)
Definition: datetime.c:4862
void EncodeDateTime(struct pg_tm *tm, fsec_t fsec, bool print_tz, int tz, const char *tzn, int style, char *str)
Definition: datetime.c:4331
int DecodeTimezone(const char *str, int *tzp)
Definition: datetime.c:2996
void EncodeDateOnly(struct pg_tm *tm, int style, char *str)
Definition: datetime.c:4216
struct DynamicZoneAbbrev DynamicZoneAbbrev
int DecodeDateTime(char **field, int *ftype, int nf, int *dtype, struct pg_tm *tm, fsec_t *fsec, int *tzp, DateTimeErrorExtra *extra)
Definition: datetime.c:978
int date2j(int year, int month, int day)
Definition: datetime.c:286
void GetCurrentTimeUsec(struct pg_tm *tm, fsec_t *fsec, int *tzp)
Definition: datetime.c:387
void DateTimeParseError(int dterr, DateTimeErrorExtra *extra, const char *str, const char *datatype, struct Node *escontext)
Definition: datetime.c:4081
#define TOKMAXLEN
Definition: datetime.h:204
int DecodeTimezoneName(const char *tzname, int *offset, pg_tz **tz)
Definition: datetime.c:3179
struct Node * TemporalSimplify(int32 max_precis, struct Node *node)
Definition: datetime.c:4829
int DecodeTimezoneAbbrevPrefix(const char *str, int *offset, pg_tz **tz)
Definition: datetime.c:3262
int DetermineTimeZoneAbbrevOffset(struct pg_tm *tm, const char *abbr, pg_tz *tzp)
Definition: datetime.c:1746
#define token
Definition: indent_globs.h:126
long val
Definition: informix.c:664
static struct pg_tm tm
Definition: localtime.c:104
long date
Definition: pgtypes_date.h:9
static struct cvec * range(struct vars *v, chr a, chr b, int cases)
Definition: regc_locale.c:412
const char * dtee_timezone
Definition: datetime.h:293
const char * dtee_abbrev
Definition: datetime.h:295
Definition: nodes.h:129
datetkn abbrevs[FLEXIBLE_ARRAY_MEMBER]
Definition: datetime.h:219
int32 value
Definition: datetime.h:211
char type
Definition: datetime.h:210
Definition: pgtime.h:35
Definition: pgtz.h:66
Definition: zic.c:94