1 @node Date input formats
2 @chapter Date input formats
4 @cindex date input formats
10 Our units of temporal measurement, from seconds on up to months, are so
11 complicated, asymmetrical and disjunctive so as to make coherent mental
12 reckoning in time all but impossible. Indeed, had some tyrannical god
13 contrived to enslave our minds to time, to make it all but impossible
14 for us to escape subjection to sodden routines and unpleasant surprises,
15 he could hardly have done better than handing down our present system.
16 It is like a set of trapezoidal building blocks, with no vertical or
17 horizontal surfaces, like a language in which the simplest thought
18 demands ornate constructions, useless particles and lengthy
19 circumlocutions. Unlike the more successful patterns of language and
20 science, which enable us to face experience boldly or at least
21 level-headedly, our system of temporal calculation silently and
22 persistently encourages our terror of time.
24 @dots{} It is as though architects had to measure length in feet, width
25 in meters and height in ells; as though basic instruction manuals
26 demanded a knowledge of five different languages. It is no wonder then
27 that we often look into our own immediate past or future, last Tuesday
28 or a week from Sunday, with feelings of helpless confusion. @dots{}
30 --- Robert Grudin, @cite{Time and the Art of Living}.
33 This section describes the textual date representations that GNU
34 programs accept. These are the strings you, as a user, can supply as
35 arguments to the various programs. The C interface (via the
36 @code{getdate} function) is not described here.
38 @cindex beginning of time, for Unix
39 @cindex epoch, for Unix
40 Although the date syntax here can represent any possible time since zero
41 A.D., computer integers are not big enough for such a (comparatively)
42 long time. The earliest date semantically allowed on Unix systems is
43 midnight, 1 January 1970 UCT.
46 * General date syntax:: Common rules.
47 * Calendar date items:: 19 Dec 1994.
48 * Time of day items:: 9:20pm.
49 * Time zone items:: EST, DST, BST, UTC, ...
50 * Day of week items:: Monday and others.
51 * Relative items in date strings:: next tuesday, 2 years ago.
52 * Pure numbers in date strings:: 19931219, 1440.
53 * Authors of getdate:: Bellovin, Salz, Berets, et al.
57 @node General date syntax
58 @section General date syntax
60 @cindex general date syntax
62 @cindex items in date strings
63 A @dfn{date} is a string, possibly empty, containing many items
64 separated by whitespace. The whitespace may be omitted when no
65 ambiguity arises. The empty string means the beginning of today (i.e.,
66 midnight). Order of the items is immaterial. A date string may contain
67 many flavors of items:
70 @item calendar date items
71 @item time of the day items
73 @item day of the week items
78 @noindent We describe each of these item types in turn, below.
80 @cindex numbers, written-out
81 @cindex ordinal numbers
82 @findex first @r{in date strings}
83 @findex next @r{in date strings}
84 @findex last @r{in date strings}
85 A few numbers may be written out in words in most contexts. This is
86 most useful for specifying day of the week items or relative items (see
87 below). Here is the list: @samp{first} for 1, @samp{next} for 2,
88 @samp{third} for 3, @samp{fourth} for 4, @samp{fifth} for 5,
89 @samp{sixth} for 6, @samp{seventh} for 7, @samp{eighth} for 8,
90 @samp{ninth} for 9, @samp{tenth} for 10, @samp{eleventh} for 11 and
91 @samp{twelfth} for 12. Also, @samp{last} means exactly @math{-1}.
93 @cindex months, written-out
94 When a month is written this way, it is still considered to be written
95 numerically, instead of being ``spelled in full''; this changes the
98 @cindex case, ignored in dates
99 @cindex comments, in dates
100 Alphabetic case is completely ignored in dates. Comments may be introduced
101 between round parentheses, as long as included parentheses are properly
102 nested. Hyphens not followed by a digit are currently ignored. Leading
103 zeros on numbers are ignored.
106 @node Calendar date items
107 @section Calendar date items
109 @cindex calendar date item
111 A @dfn{calendar date item} specifies a day of the year. It is
112 specified differently, depending on whether the month is specified
113 numerically or literally. All these strings specify the same calendar date:
116 1972-09-24 # ISO 8601.
117 72-9-24 # Assume 19xx for 69 through 99,
118 # 20xx for 00 through 68.
119 72-09-24 # Leading zeros are ignored.
120 9/24/72 # Common U.S. writing.
122 24 Sept 72 # September has a special abbreviation.
123 24 Sep 72 # Three-letter abbreviations always allowed.
129 The year can also be omitted. In this case, the last specified year is
130 used, or the current year if none. For example:
139 @cindex ISO 8601 date format
140 @cindex date format, ISO 8601
141 For numeric months, the ISO 8601 format
142 @samp{@var{year}-@var{month}-@var{day}} is allowed, where @var{year} is
143 any positive number, @var{month} is a number between 01 and 12, and
144 @var{day} is a number between 01 and 31. A leading zero must be present
145 if a number is less than ten. If @var{year} is 68 or smaller, then 2000
146 is added to it; otherwise, if @var{year} is less than 100,
147 then 1900 is added to it. The construct
148 @samp{@var{month}/@var{day}/@var{year}}, popular in the United States,
149 is accepted. Also @samp{@var{month}/@var{day}}, omitting the year.
151 @cindex month names in date strings
152 @cindex abbreviations for months
153 Literal months may be spelled out in full: @samp{January},
154 @samp{February}, @samp{March}, @samp{April}, @samp{May}, @samp{June},
155 @samp{July}, @samp{August}, @samp{September}, @samp{October},
156 @samp{November} or @samp{December}. Literal months may be abbreviated
157 to their first three letters, possibly followed by an abbreviating dot.
158 It is also permitted to write @samp{Sept} instead of @samp{September}.
160 When months are written literally, the calendar date may be given as any
164 @var{day} @var{month} @var{year}
165 @var{day} @var{month}
166 @var{month} @var{day} @var{year}
167 @var{day}-@var{month}-@var{year}
170 Or, omitting the year:
173 @var{month} @var{day}
177 @node Time of day items
178 @section Time of day items
180 @cindex time of day item
182 A @dfn{time of day item} in date strings specifies the time on a given
183 day. Here are some examples, all of which represent the same time:
189 20:02-0500 # In EST (Eastern U.S. Standard Time).
192 More generally, the time of the day may be given as
193 @samp{@var{hour}:@var{minute}:@var{second}}, where @var{hour} is
194 a number between 0 and 23, @var{minute} is a number between 0 and
195 59, and @var{second} is a number between 0 and 59. Alternatively,
196 @samp{:@var{second}} can be omitted, in which case it is taken to
199 @findex am @r{in date strings}
200 @findex pm @r{in date strings}
201 @findex midnight @r{in date strings}
202 @findex noon @r{in date strings}
203 If the time is followed by @samp{am} or @samp{pm} (or @samp{a.m.}
204 or @samp{p.m.}), @var{hour} is restricted to run from 1 to 12, and
205 @samp{:@var{minute}} may be omitted (taken to be zero). @samp{am}
206 indicates the first half of the day, @samp{pm} indicates the second
207 half of the day. In this notation, 12 is the predecessor of 1:
208 midnight is @samp{12am} while noon is @samp{12pm}.
210 @cindex time zone correction
211 @cindex minutes, time zone correction by
212 The time may alternatively be followed by a time zone correction,
213 expressed as @samp{@var{s}@var{hh}@var{mm}}, where @var{s} is @samp{+}
214 or @samp{-}, @var{hh} is a number of zone hours and @var{mm} is a number
215 of zone minutes. When a time zone correction is given this way, it
216 forces interpretation of the time relative to
217 Coordinated Universal Time (UTC), overriding any previous
218 specification for the time zone or the local time zone. The @var{minute}
219 part of the time of the day may not be elided when a time zone correction
220 is used. This is the only way to specify a time zone correction by
221 fractional parts of an hour.
223 Either @samp{am}/@samp{pm} or a time zone correction may be specified,
227 @node Time zone items
228 @section Time zone items
230 @cindex time zone item
232 A @dfn{time zone item} specifies an international time zone, indicated by
233 a small set of letters. They are supported for backward compatibility reasons,
234 but they are not recommended because they are ambiguous in practice:
235 for example, the abbreviation @samp{EST} has different meanings in
236 Australia and the United States. Any included period is ignored. Military
237 time zone designations use a single letter. Currently, only integral
238 zone hours may be represented in a time zone item. See the previous
239 section for a finer control over the time zone correction.
241 Here are many non-daylight-saving-time time zones, indexed by the zone
246 @samp{Y} for militaries.
248 @samp{X} for militaries.
250 @samp{W} for militaries.
252 @samp{V} for militaries.
254 @samp{PST} for Pacific Standard, and
255 @samp{U} for militaries.
257 @samp{MST} for Mountain Standard, and
258 @samp{T} for militaries.
260 @samp{CST} for Central Standard, and
261 @samp{S} for militaries.
263 @samp{EST} for Eastern Standard, and
264 @samp{R} for militaries.
266 @samp{AST} for Atlantic Standard, and
267 @samp{Q} for militaries.
269 @samp{P} for militaries.
271 @samp{O} for militaries.
273 @samp{N} for militaries.
275 @cindex Greenwich Mean Time
276 @cindex Coordinated Universal Time
277 @cindex Universal Coordinated Time
278 @cindex Universal Time (Coordinated)
279 @samp{GMT} for Greenwich Mean,
280 @samp{UT} for Universal,
281 @samp{UTC} for Coordinated Universal,
282 @samp{WET} for Western European, and
283 @samp{Z} for ISO 8601 and militaries.
285 @samp{A} for militaries,
286 @samp{CET} for Central European,
287 @samp{MET} for Midden Europesche Tijd (Dutch), and
288 @samp{MEZ} for Mittel-Europ@"aische Zeit (German).
290 @samp{B} for militaries, and
291 @samp{EET} for Eastern European.
293 @samp{C} for militaries.
295 @samp{D} for militaries.
297 @samp{E} for militaries.
299 @samp{F} for militaries.
301 @samp{G} for militaries.
303 @samp{H} for militaries.
305 @samp{I} for militaries, and
306 @samp{JST} for Japan Standard.
308 @samp{GST} for Guam Standard, and
309 @samp{K} for militaries.
311 @samp{L} for militaries.
313 @samp{M} for militaries, and
314 @samp{NZST} for New Zealand Standard.
317 @cindex daylight-saving time
318 Here are many daylight-saving time (DST) time zones,
319 indexed by the zone hour value. Also, by
320 following a non-DST time zone by the string @samp{DST} in a separate word
321 (that is, separated by some whitespace), the corresponding DST time zone
326 @samp{PDT} for Pacific Daylight.
328 @samp{MDT} for Mountain Daylight.
330 @samp{CDT} for Central Daylight.
332 @samp{EDT} for Eastern Daylight.
334 @samp{ADT} for Atlantic Daylight.
336 @samp{BST} for British Summer, and
337 @samp{WEST} for Western European Summer.
339 @samp{CEST} for Central European Summer,
340 @samp{MEST} for Midden Europesche S. Tijd (Dutch), and
341 @samp{MESZ} for Mittel-Europ@"aische Sommerzeit (German).
343 @samp{NZDT} for New Zealand Daylight.
347 @node Day of week items
348 @section Day of week items
350 @cindex day of week item
352 The explicit mention of a day of the week will forward the date
353 (only if necessary) to reach that day of the week in the future.
355 Days of the week may be spelled out in full: @samp{Sunday},
356 @samp{Monday}, @samp{Tuesday}, @samp{Wednesday}, @samp{Thursday},
357 @samp{Friday} or @samp{Saturday}. Days may be abbreviated to their
358 first three letters, optionally followed by a period. The special
359 abbreviations @samp{Tues} for @samp{Tuesday}, @samp{Wednes} for
360 @samp{Wednesday} and @samp{Thur} or @samp{Thurs} for @samp{Thursday} are
363 @findex next @var{day}
364 @findex last @var{day}
365 A number may precede a day of the week item to move forward
366 supplementary weeks. It is best used in expression like @samp{third
367 monday}. In this context, @samp{last @var{day}} or @samp{next
368 @var{day}} is also acceptable; they move one week before or after
369 the day that @var{day} by itself would represent.
371 A comma following a day of the week item is ignored.
374 @node Relative items in date strings
375 @section Relative items in date strings
377 @cindex relative items in date strings
378 @cindex displacement of dates
380 @dfn{Relative items} adjust a date (or the current date if none) forward
381 or backward. The effects of relative items accumulate. Here are some
391 @findex year @r{in date strings}
392 @findex month @r{in date strings}
393 @findex fortnight @r{in date strings}
394 @findex week @r{in date strings}
395 @findex day @r{in date strings}
396 @findex hour @r{in date strings}
397 @findex minute @r{in date strings}
398 The unit of time displacement may be selected by the string @samp{year}
399 or @samp{month} for moving by whole years or months. These are fuzzy
400 units, as years and months are not all of equal duration. More precise
401 units are @samp{fortnight} which is worth 14 days, @samp{week} worth 7
402 days, @samp{day} worth 24 hours, @samp{hour} worth 60 minutes,
403 @samp{minute} or @samp{min} worth 60 seconds, and @samp{second} or
404 @samp{sec} worth one second. An @samp{s} suffix on these units is
405 accepted and ignored.
407 @findex ago @r{in date strings}
408 The unit of time may be preceded by a multiplier, given as an optionally
409 signed number. Unsigned numbers are taken as positively signed. No
410 number at all implies 1 for a multiplier. Following a relative item by
411 the string @samp{ago} is equivalent to preceding the unit by a
412 multiplicator with value @math{-1}.
414 @findex day @r{in date strings}
415 @findex tomorrow @r{in date strings}
416 @findex yesterday @r{in date strings}
417 The string @samp{tomorrow} is worth one day in the future (equivalent
418 to @samp{day}), the string @samp{yesterday} is worth
419 one day in the past (equivalent to @samp{day ago}).
421 @findex now @r{in date strings}
422 @findex today @r{in date strings}
423 @findex this @r{in date strings}
424 The strings @samp{now} or @samp{today} are relative items corresponding
425 to zero-valued time displacement, these strings come from the fact
426 a zero-valued time displacement represents the current time when not
427 otherwise changed by previous items. They may be used to stress other
428 items, like in @samp{12:00 today}. The string @samp{this} also has
429 the meaning of a zero-valued time displacement, but is preferred in
430 date strings like @samp{this thursday}.
432 When a relative item causes the resulting date to cross the boundary
433 between DST and non-DST (or vice-versa), the hour is adjusted according
437 @node Pure numbers in date strings
438 @section Pure numbers in date strings
440 @cindex pure numbers in date strings
442 The precise intepretation of a pure decimal number depends
443 the context in the date string.
445 If the decimal number is of the form @var{yyyy}@var{mm}@var{dd} and no
446 other calendar date item (@pxref{Calendar date items}) appears before it
447 in the date string, then @var{yyyy} is read as the year, @var{mm} as the
448 month number and @var{dd} as the day of the month, for the specified
451 If the decimal number is of the form @var{hh}@var{mm} and no other time
452 of day item appears before it in the date string, then @var{hh} is read
453 as the hour of the day and @var{mm} as the minute of the hour, for the
454 specified time of the day. @var{mm} can also be omitted.
456 If both a calendar date and a time of day appear to the left of a number
457 in the date string, but no relative item, then the number overrides the
461 @node Authors of getdate
462 @section Authors of @code{getdate}
464 @cindex authors of @code{getdate}
466 @cindex Bellovin, Steven M.
469 @cindex MacKenzie, David
470 @cindex Meyering, Jim
471 @code{getdate} was originally implemented by Steven M. Bellovin
472 (@email{smb@@research.att.com}) while at the University of North Carolina
473 at Chapel Hill. The code was later tweaked by a couple of people on
474 Usenet, then completely overhauled by Rich $alz (@email{rsalz@@bbn.com})
475 and Jim Berets (@email{jberets@@bbn.com}) in August, 1990. Various
476 revisions for the GNU system were made by David MacKenzie, Jim Meyering,
481 This chapter was originally produced by Fran@,{c}ois Pinard
482 (@email{pinard@@iro.umontreal.ca}) from the @file{getdate.y} source code,
483 and then edited by K.@: Berry (@email{kb@@cs.umb.edu}).