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-2025, 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: */
22struct 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 */
207typedef 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 */
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) */
224typedef 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) \
238do { \
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) \
249do { \
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
259extern PGDLLIMPORT const char *const months[]; /* months (3-char
260 * abbreviations) */
261extern PGDLLIMPORT const char *const days[]; /* days (full names) */
262extern 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
290typedef 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
304extern void GetCurrentDateTime(struct pg_tm *tm);
305extern void GetCurrentTimeUsec(struct pg_tm *tm, fsec_t *fsec, int *tzp);
306extern void j2date(int jd, int *year, int *month, int *day);
307extern int date2j(int year, int month, int day);
308
309extern int ParseDateTime(const char *timestr, char *workbuf, size_t buflen,
310 char **field, int *ftype,
311 int maxfields, int *numfields);
312extern int DecodeDateTime(char **field, int *ftype, int nf,
313 int *dtype, struct pg_tm *tm, fsec_t *fsec, int *tzp,
314 DateTimeErrorExtra *extra);
315extern int DecodeTimezone(const char *str, int *tzp);
316extern int DecodeTimeOnly(char **field, int *ftype, int nf,
317 int *dtype, struct pg_tm *tm, fsec_t *fsec, int *tzp,
318 DateTimeErrorExtra *extra);
319extern int DecodeInterval(char **field, int *ftype, int nf, int range,
320 int *dtype, struct pg_itm_in *itm_in);
321extern int DecodeISO8601Interval(char *str,
322 int *dtype, struct pg_itm_in *itm_in);
323
324extern void DateTimeParseError(int dterr, DateTimeErrorExtra *extra,
325 const char *str, const char *datatype,
326 struct Node *escontext);
327
328extern int DetermineTimeZoneOffset(struct pg_tm *tm, pg_tz *tzp);
329extern int DetermineTimeZoneAbbrevOffset(struct pg_tm *tm, const char *abbr, pg_tz *tzp);
330extern int DetermineTimeZoneAbbrevOffsetTS(TimestampTz ts, const char *abbr,
331 pg_tz *tzp, int *isdst);
332
333extern void EncodeDateOnly(struct pg_tm *tm, int style, char *str);
334extern void EncodeTimeOnly(struct pg_tm *tm, fsec_t fsec, bool print_tz, int tz, int style, char *str);
335extern void EncodeDateTime(struct pg_tm *tm, fsec_t fsec, bool print_tz, int tz, const char *tzn, int style, char *str);
336extern void EncodeInterval(struct pg_itm *itm, int style, char *str);
337extern void EncodeSpecialTimestamp(Timestamp dt, char *str);
338
339extern int ValidateDate(int fmask, bool isjulian, bool is2digits, bool bc,
340 struct pg_tm *tm);
341
342extern int DecodeTimezoneAbbrev(int field, const char *lowtoken,
343 int *ftype, int *offset, pg_tz **tz,
344 DateTimeErrorExtra *extra);
345extern int DecodeSpecial(int field, const char *lowtoken, int *val);
346extern int DecodeUnits(int field, const char *lowtoken, int *val);
347
348extern int DecodeTimezoneName(const char *tzname, int *offset, pg_tz **tz);
349extern pg_tz *DecodeTimezoneNameToTz(const char *tzname);
350
351extern int DecodeTimezoneAbbrevPrefix(const char *str,
352 int *offset, pg_tz **tz);
353
354extern void ClearTimeZoneAbbrevCache(void);
355
356extern int j2day(int date);
357
358extern struct Node *TemporalSimplify(int32 max_precis, struct Node *node);
359
360extern bool CheckDateTokenTables(void);
361
363 int n);
365
366extern bool AdjustTimestampForTypmod(Timestamp *time, int32 typmod,
367 struct Node *escontext);
368
369#endif /* DATETIME_H */
#define PGDLLIMPORT
Definition: c.h:1291
#define FLEXIBLE_ARRAY_MEMBER
Definition: c.h:434
int32_t int32
Definition: c.h:498
size_t Size
Definition: c.h:576
int64 Timestamp
Definition: timestamp.h:38
int64 TimestampTz
Definition: timestamp.h:39
int32 fsec_t
Definition: timestamp.h:41
const char * str
struct Node * TemporalSimplify(int32 max_precis, struct Node *node)
Definition: datetime.c:4956
pg_tz * DecodeTimezoneNameToTz(const char *tzname)
Definition: datetime.c:3337
int DetermineTimeZoneAbbrevOffsetTS(TimestampTz ts, const char *abbr, pg_tz *tzp, int *isdst)
Definition: datetime.c:1794
PGDLLIMPORT const char *const months[]
Definition: datetime.c:81
void InstallTimeZoneAbbrevs(TimeZoneAbbrevTable *tbl)
Definition: datetime.c:5073
int DecodeUnits(int field, const char *lowtoken, int *val)
Definition: datetime.c:4163
int DecodeTimeOnly(char **field, int *ftype, int nf, int *dtype, struct pg_tm *tm, fsec_t *fsec, int *tzp, DateTimeErrorExtra *extra)
Definition: datetime.c:1908
int j2day(int date)
Definition: datetime.c:354
int ParseDateTime(const char *timestr, char *workbuf, size_t buflen, char **field, int *ftype, int maxfields, int *numfields)
Definition: datetime.c:764
bool AdjustTimestampForTypmod(Timestamp *time, int32 typmod, struct Node *escontext)
Definition: timestamp.c:367
void EncodeInterval(struct pg_itm *itm, int style, char *str)
Definition: datetime.c:4701
struct DateTimeErrorExtra DateTimeErrorExtra
int DetermineTimeZoneOffset(struct pg_tm *tm, pg_tz *tzp)
Definition: datetime.c:1595
int DecodeInterval(char **field, int *ftype, int nf, int range, int *dtype, struct pg_itm_in *itm_in)
Definition: datetime.c:3480
PGDLLIMPORT const int day_tab[2][13]
Definition: datetime.c:75
void EncodeSpecialTimestamp(Timestamp dt, char *str)
Definition: timestamp.c:1586
bool CheckDateTokenTables(void)
Definition: datetime.c:4927
int DecodeTimezoneAbbrev(int field, const char *lowtoken, int *ftype, int *offset, pg_tz **tz, DateTimeErrorExtra *extra)
Definition: datetime.c:3135
void EncodeTimeOnly(struct pg_tm *tm, fsec_t fsec, bool print_tz, int tz, int style, char *str)
Definition: datetime.c:4428
int DecodeISO8601Interval(char *str, int *dtype, struct pg_itm_in *itm_in)
Definition: datetime.c:3945
int ValidateDate(int fmask, bool isjulian, bool is2digits, bool bc, struct pg_tm *tm)
Definition: datetime.c:2552
struct TimeZoneAbbrevTable TimeZoneAbbrevTable
int DecodeSpecial(int field, const char *lowtoken, int *val)
Definition: datetime.c:3240
void j2date(int jd, int *year, int *month, int *day)
Definition: datetime.c:321
void GetCurrentDateTime(struct pg_tm *tm)
Definition: datetime.c:376
PGDLLIMPORT const char *const days[]
Definition: datetime.c:84
void EncodeDateTime(struct pg_tm *tm, fsec_t fsec, bool print_tz, int tz, const char *tzn, int style, char *str)
Definition: datetime.c:4458
int DecodeTimezone(const char *str, int *tzp)
Definition: datetime.c:3051
TimeZoneAbbrevTable * ConvertTimeZoneAbbrevs(struct tzEntry *abbrevs, int n)
Definition: datetime.c:4989
void EncodeDateOnly(struct pg_tm *tm, int style, char *str)
Definition: datetime.c:4343
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:988
int date2j(int year, int month, int day)
Definition: datetime.c:296
void GetCurrentTimeUsec(struct pg_tm *tm, fsec_t *fsec, int *tzp)
Definition: datetime.c:397
void DateTimeParseError(int dterr, DateTimeErrorExtra *extra, const char *str, const char *datatype, struct Node *escontext)
Definition: datetime.c:4208
#define TOKMAXLEN
Definition: datetime.h:204
void ClearTimeZoneAbbrevCache(void)
Definition: datetime.c:3221
int DecodeTimezoneName(const char *tzname, int *offset, pg_tz **tz)
Definition: datetime.c:3282
int DecodeTimezoneAbbrevPrefix(const char *str, int *offset, pg_tz **tz)
Definition: datetime.c:3365
int DetermineTimeZoneAbbrevOffset(struct pg_tm *tm, const char *abbr, pg_tz *tzp)
Definition: datetime.c:1756
long val
Definition: informix.c:689
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:131
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