Mercurial > hg > octave-kai > gnulib-hg

annotate doc/parse-datetime.texi @ 16416:7d97985fae86

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Tests for module 'remainderl'. * modules/remainderl-tests: New file. * tests/test-remainderl.c: New file. * tests/test-math-c++.cc: Check the declaration of remainderl.
author Bruno Haible <bruno@clisp.org>
date Sat, 25 Feb 2012 20:40:44 +0100
parents 8250f2777afc
children 20011163d6c7
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
13769
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
1 @c GNU date syntax documentation
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
2
16201
8250f2777afc maint: update all copyright year number ranges
Jim Meyering <meyering@redhat.com>
parents: 15580
diff changeset
3 @c Copyright (C) 1994-2006, 2009-2012 Free Software Foundation, Inc.
13769
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
4
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
5 @c Permission is granted to copy, distribute and/or modify this document
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
6 @c under the terms of the GNU Free Documentation License, Version 1.3 or
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
7 @c any later version published by the Free Software Foundation; with no
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
8 @c Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
9 @c Texts. A copy of the license is included in the ``GNU Free
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
10 @c Documentation License'' file as part of this distribution.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
11
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
12 @node Date input formats
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
13 @chapter Date input formats
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
14
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
15 @cindex date input formats
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
16 @findex parse_datetime
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
17
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
18 First, a quote:
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
19
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
20 @quotation
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
21 Our units of temporal measurement, from seconds on up to months, are so
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
22 complicated, asymmetrical and disjunctive so as to make coherent mental
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
23 reckoning in time all but impossible. Indeed, had some tyrannical god
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
24 contrived to enslave our minds to time, to make it all but impossible
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
25 for us to escape subjection to sodden routines and unpleasant surprises,
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
26 he could hardly have done better than handing down our present system.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
27 It is like a set of trapezoidal building blocks, with no vertical or
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
28 horizontal surfaces, like a language in which the simplest thought
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
29 demands ornate constructions, useless particles and lengthy
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
30 circumlocutions. Unlike the more successful patterns of language and
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
31 science, which enable us to face experience boldly or at least
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
32 level-headedly, our system of temporal calculation silently and
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
33 persistently encourages our terror of time.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
34
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
35 @dots{} It is as though architects had to measure length in feet, width
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
36 in meters and height in ells; as though basic instruction manuals
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
37 demanded a knowledge of five different languages. It is no wonder then
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
38 that we often look into our own immediate past or future, last Tuesday
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
39 or a week from Sunday, with feelings of helpless confusion. @dots{}
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
40
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
41 --- Robert Grudin, @cite{Time and the Art of Living}.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
42 @end quotation
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
43
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
44 This section describes the textual date representations that @sc{gnu}
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
45 programs accept. These are the strings you, as a user, can supply as
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
46 arguments to the various programs. The C interface (via the
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
47 @code{parse_datetime} function) is not described here.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
48
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
49 @menu
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
50 * General date syntax:: Common rules.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
51 * Calendar date items:: 19 Dec 1994.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
52 * Time of day items:: 9:20pm.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
53 * Time zone items:: @sc{est}, @sc{pdt}, @sc{gmt}.
15580
6ed6226ab0af parse-datetime: document the newly accepted format
J.T. Conklin <jtc@acorntoolworks.com>
parents: 15542
diff changeset
54 * Combined date and time of day items:: 1972-09-24T20:02:00,000000-0500
13769
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
55 * Day of week items:: Monday and others.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
56 * Relative items in date strings:: next tuesday, 2 years ago.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
57 * Pure numbers in date strings:: 19931219, 1440.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
58 * Seconds since the Epoch:: @@1078100502.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
59 * Specifying time zone rules:: TZ="America/New_York", TZ="UTC0".
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
60 * Authors of parse_datetime:: Bellovin, Eggert, Salz, Berets, et al.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
61 @end menu
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
62
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
63
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
64 @node General date syntax
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
65 @section General date syntax
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
66
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
67 @cindex general date syntax
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
68
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
69 @cindex items in date strings
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
70 A @dfn{date} is a string, possibly empty, containing many items
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
71 separated by whitespace. The whitespace may be omitted when no
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
72 ambiguity arises. The empty string means the beginning of today (i.e.,
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
73 midnight). Order of the items is immaterial. A date string may contain
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
74 many flavors of items:
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
75
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
76 @itemize @bullet
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
77 @item calendar date items
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
78 @item time of day items
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
79 @item time zone items
15580
6ed6226ab0af parse-datetime: document the newly accepted format
J.T. Conklin <jtc@acorntoolworks.com>
parents: 15542
diff changeset
80 @item combined date and time of day items
13769
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
81 @item day of the week items
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
82 @item relative items
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
83 @item pure numbers.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
84 @end itemize
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
85
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
86 @noindent We describe each of these item types in turn, below.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
87
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
88 @cindex numbers, written-out
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
89 @cindex ordinal numbers
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
90 @findex first @r{in date strings}
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
91 @findex next @r{in date strings}
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
92 @findex last @r{in date strings}
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
93 A few ordinal numbers may be written out in words in some contexts. This is
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
94 most useful for specifying day of the week items or relative items (see
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
95 below). Among the most commonly used ordinal numbers, the word
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
96 @samp{last} stands for @math{-1}, @samp{this} stands for 0, and
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
97 @samp{first} and @samp{next} both stand for 1. Because the word
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
98 @samp{second} stands for the unit of time there is no way to write the
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
99 ordinal number 2, but for convenience @samp{third} stands for 3,
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
100 @samp{fourth} for 4, @samp{fifth} for 5,
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
101 @samp{sixth} for 6, @samp{seventh} for 7, @samp{eighth} for 8,
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
102 @samp{ninth} for 9, @samp{tenth} for 10, @samp{eleventh} for 11 and
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
103 @samp{twelfth} for 12.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
104
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
105 @cindex months, written-out
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
106 When a month is written this way, it is still considered to be written
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
107 numerically, instead of being ``spelled in full''; this changes the
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
108 allowed strings.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
109
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
110 @cindex language, in dates
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
111 In the current implementation, only English is supported for words and
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
112 abbreviations like @samp{AM}, @samp{DST}, @samp{EST}, @samp{first},
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
113 @samp{January}, @samp{Sunday}, @samp{tomorrow}, and @samp{year}.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
114
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
115 @cindex language, in dates
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
116 @cindex time zone item
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
117 The output of the @command{date} command
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
118 is not always acceptable as a date string,
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
119 not only because of the language problem, but also because there is no
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
120 standard meaning for time zone items like @samp{IST}. When using
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
121 @command{date} to generate a date string intended to be parsed later,
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
122 specify a date format that is independent of language and that does not
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
123 use time zone items other than @samp{UTC} and @samp{Z}. Here are some
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
124 ways to do this:
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
125
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
126 @example
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
127 $ LC_ALL=C TZ=UTC0 date
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
128 Mon Mar 1 00:21:42 UTC 2004
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
129 $ TZ=UTC0 date +'%Y-%m-%d %H:%M:%SZ'
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
130 2004-03-01 00:21:42Z
15542
9ad43fa113ac parse-datetime: accept ISO 8601 date and time rep with "T" separator
J.T. Conklin <jtc@acorntoolworks.com>
parents: 14079
diff changeset
131 $ date --rfc-3339=ns # --rfc-3339 is a GNU extension.
9ad43fa113ac parse-datetime: accept ISO 8601 date and time rep with "T" separator
J.T. Conklin <jtc@acorntoolworks.com>
parents: 14079
diff changeset
132 2004-02-29 16:21:42.692722128-08:00
13769
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
133 $ date --rfc-2822 # a GNU extension
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
134 Sun, 29 Feb 2004 16:21:42 -0800
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
135 $ date +'%Y-%m-%d %H:%M:%S %z' # %z is a GNU extension.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
136 2004-02-29 16:21:42 -0800
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
137 $ date +'@@%s.%N' # %s and %N are GNU extensions.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
138 @@1078100502.692722128
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
139 @end example
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
140
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
141 @cindex case, ignored in dates
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
142 @cindex comments, in dates
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
143 Alphabetic case is completely ignored in dates. Comments may be introduced
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
144 between round parentheses, as long as included parentheses are properly
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
145 nested. Hyphens not followed by a digit are currently ignored. Leading
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
146 zeros on numbers are ignored.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
147
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
148 Invalid dates like @samp{2005-02-29} or times like @samp{24:00} are
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
149 rejected. In the typical case of a host that does not support leap
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
150 seconds, a time like @samp{23:59:60} is rejected even if it
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
151 corresponds to a valid leap second.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
152
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
153
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
154 @node Calendar date items
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
155 @section Calendar date items
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
156
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
157 @cindex calendar date item
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
158
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
159 A @dfn{calendar date item} specifies a day of the year. It is
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
160 specified differently, depending on whether the month is specified
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
161 numerically or literally. All these strings specify the same calendar date:
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
162
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
163 @example
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
164 1972-09-24 # @sc{iso} 8601.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
165 72-9-24 # Assume 19xx for 69 through 99,
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
166 # 20xx for 00 through 68.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
167 72-09-24 # Leading zeros are ignored.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
168 9/24/72 # Common U.S. writing.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
169 24 September 1972
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
170 24 Sept 72 # September has a special abbreviation.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
171 24 Sep 72 # Three-letter abbreviations always allowed.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
172 Sep 24, 1972
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
173 24-sep-72
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
174 24sep72
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
175 @end example
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
176
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
177 The year can also be omitted. In this case, the last specified year is
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
178 used, or the current year if none. For example:
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
179
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
180 @example
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
181 9/24
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
182 sep 24
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
183 @end example
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
184
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
185 Here are the rules.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
186
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
187 @cindex @sc{iso} 8601 date format
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
188 @cindex date format, @sc{iso} 8601
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
189 For numeric months, the @sc{iso} 8601 format
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
190 @samp{@var{year}-@var{month}-@var{day}} is allowed, where @var{year} is
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
191 any positive number, @var{month} is a number between 01 and 12, and
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
192 @var{day} is a number between 01 and 31. A leading zero must be present
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
193 if a number is less than ten. If @var{year} is 68 or smaller, then 2000
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
194 is added to it; otherwise, if @var{year} is less than 100,
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
195 then 1900 is added to it. The construct
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
196 @samp{@var{month}/@var{day}/@var{year}}, popular in the United States,
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
197 is accepted. Also @samp{@var{month}/@var{day}}, omitting the year.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
198
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
199 @cindex month names in date strings
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
200 @cindex abbreviations for months
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
201 Literal months may be spelled out in full: @samp{January},
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
202 @samp{February}, @samp{March}, @samp{April}, @samp{May}, @samp{June},
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
203 @samp{July}, @samp{August}, @samp{September}, @samp{October},
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
204 @samp{November} or @samp{December}. Literal months may be abbreviated
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
205 to their first three letters, possibly followed by an abbreviating dot.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
206 It is also permitted to write @samp{Sept} instead of @samp{September}.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
207
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
208 When months are written literally, the calendar date may be given as any
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
209 of the following:
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
210
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
211 @example
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
212 @var{day} @var{month} @var{year}
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
213 @var{day} @var{month}
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
214 @var{month} @var{day} @var{year}
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
215 @var{day}-@var{month}-@var{year}
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
216 @end example
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
217
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
218 Or, omitting the year:
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
219
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
220 @example
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
221 @var{month} @var{day}
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
222 @end example
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
223
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
224
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
225 @node Time of day items
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
226 @section Time of day items
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
227
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
228 @cindex time of day item
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
229
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
230 A @dfn{time of day item} in date strings specifies the time on a given
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
231 day. Here are some examples, all of which represent the same time:
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
232
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
233 @example
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
234 20:02:00.000000
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
235 20:02
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
236 8:02pm
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
237 20:02-0500 # In @sc{est} (U.S. Eastern Standard Time).
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
238 @end example
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
239
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
240 More generally, the time of day may be given as
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
241 @samp{@var{hour}:@var{minute}:@var{second}}, where @var{hour} is
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
242 a number between 0 and 23, @var{minute} is a number between 0 and
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
243 59, and @var{second} is a number between 0 and 59 possibly followed by
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
244 @samp{.} or @samp{,} and a fraction containing one or more digits.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
245 Alternatively,
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
246 @samp{:@var{second}} can be omitted, in which case it is taken to
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
247 be zero. On the rare hosts that support leap seconds, @var{second}
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
248 may be 60.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
249
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
250 @findex am @r{in date strings}
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
251 @findex pm @r{in date strings}
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
252 @findex midnight @r{in date strings}
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
253 @findex noon @r{in date strings}
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
254 If the time is followed by @samp{am} or @samp{pm} (or @samp{a.m.}
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
255 or @samp{p.m.}), @var{hour} is restricted to run from 1 to 12, and
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
256 @samp{:@var{minute}} may be omitted (taken to be zero). @samp{am}
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
257 indicates the first half of the day, @samp{pm} indicates the second
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
258 half of the day. In this notation, 12 is the predecessor of 1:
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
259 midnight is @samp{12am} while noon is @samp{12pm}.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
260 (This is the zero-oriented interpretation of @samp{12am} and @samp{12pm},
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
261 as opposed to the old tradition derived from Latin
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
262 which uses @samp{12m} for noon and @samp{12pm} for midnight.)
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
263
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
264 @cindex time zone correction
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
265 @cindex minutes, time zone correction by
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
266 The time may alternatively be followed by a time zone correction,
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
267 expressed as @samp{@var{s}@var{hh}@var{mm}}, where @var{s} is @samp{+}
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
268 or @samp{-}, @var{hh} is a number of zone hours and @var{mm} is a number
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
269 of zone minutes.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
270 The zone minutes term, @var{mm}, may be omitted, in which case
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
271 the one- or two-digit correction is interpreted as a number of hours.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
272 You can also separate @var{hh} from @var{mm} with a colon.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
273 When a time zone correction is given this way, it
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
274 forces interpretation of the time relative to
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
275 Coordinated Universal Time (@sc{utc}), overriding any previous
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
276 specification for the time zone or the local time zone. For example,
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
277 @samp{+0530} and @samp{+05:30} both stand for the time zone 5.5 hours
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
278 ahead of @sc{utc} (e.g., India).
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
279 This is the best way to
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
280 specify a time zone correction by fractional parts of an hour.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
281 The maximum zone correction is 24 hours.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
282
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
283 Either @samp{am}/@samp{pm} or a time zone correction may be specified,
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
284 but not both.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
285
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
286
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
287 @node Time zone items
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
288 @section Time zone items
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
289
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
290 @cindex time zone item
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
291
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
292 A @dfn{time zone item} specifies an international time zone, indicated
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
293 by a small set of letters, e.g., @samp{UTC} or @samp{Z}
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
294 for Coordinated Universal
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
295 Time. Any included periods are ignored. By following a
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
296 non-daylight-saving time zone by the string @samp{DST} in a separate
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
297 word (that is, separated by some white space), the corresponding
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
298 daylight saving time zone may be specified.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
299 Alternatively, a non-daylight-saving time zone can be followed by a
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
300 time zone correction, to add the two values. This is normally done
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
301 only for @samp{UTC}; for example, @samp{UTC+05:30} is equivalent to
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
302 @samp{+05:30}.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
303
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
304 Time zone items other than @samp{UTC} and @samp{Z}
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
305 are obsolescent and are not recommended, because they
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
306 are ambiguous; for example, @samp{EST} has a different meaning in
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
307 Australia than in the United States. Instead, it's better to use
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
308 unambiguous numeric time zone corrections like @samp{-0500}, as
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
309 described in the previous section.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
310
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
311 If neither a time zone item nor a time zone correction is supplied,
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
312 time stamps are interpreted using the rules of the default time zone
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
313 (@pxref{Specifying time zone rules}).
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
314
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
315
15580
6ed6226ab0af parse-datetime: document the newly accepted format
J.T. Conklin <jtc@acorntoolworks.com>
parents: 15542
diff changeset
316 @node Combined date and time of day items
6ed6226ab0af parse-datetime: document the newly accepted format
J.T. Conklin <jtc@acorntoolworks.com>
parents: 15542
diff changeset
317 @section Combined date and time of day items
6ed6226ab0af parse-datetime: document the newly accepted format
J.T. Conklin <jtc@acorntoolworks.com>
parents: 15542
diff changeset
318
6ed6226ab0af parse-datetime: document the newly accepted format
J.T. Conklin <jtc@acorntoolworks.com>
parents: 15542
diff changeset
319 @cindex combined date and time of day item
6ed6226ab0af parse-datetime: document the newly accepted format
J.T. Conklin <jtc@acorntoolworks.com>
parents: 15542
diff changeset
320
6ed6226ab0af parse-datetime: document the newly accepted format
J.T. Conklin <jtc@acorntoolworks.com>
parents: 15542
diff changeset
321 A @dfn{combined date and time of day item} specifies the time on a
6ed6226ab0af parse-datetime: document the newly accepted format
J.T. Conklin <jtc@acorntoolworks.com>
parents: 15542
diff changeset
322 specific day of the year. This type is needed for formats that cannot
6ed6226ab0af parse-datetime: document the newly accepted format
J.T. Conklin <jtc@acorntoolworks.com>
parents: 15542
diff changeset
323 be represented by individual calendar date (@pxref{Calendar date items})
6ed6226ab0af parse-datetime: document the newly accepted format
J.T. Conklin <jtc@acorntoolworks.com>
parents: 15542
diff changeset
324 and time of day (@pxref{Time of day items}) items due to ambiguity.
6ed6226ab0af parse-datetime: document the newly accepted format
J.T. Conklin <jtc@acorntoolworks.com>
parents: 15542
diff changeset
325
6ed6226ab0af parse-datetime: document the newly accepted format
J.T. Conklin <jtc@acorntoolworks.com>
parents: 15542
diff changeset
326 @example
6ed6226ab0af parse-datetime: document the newly accepted format
J.T. Conklin <jtc@acorntoolworks.com>
parents: 15542
diff changeset
327 # ISO 8601 extended date and time of day format
6ed6226ab0af parse-datetime: document the newly accepted format
J.T. Conklin <jtc@acorntoolworks.com>
parents: 15542
diff changeset
328 1972-09-24T20:02:00,000000-0500
6ed6226ab0af parse-datetime: document the newly accepted format
J.T. Conklin <jtc@acorntoolworks.com>
parents: 15542
diff changeset
329 @end example
6ed6226ab0af parse-datetime: document the newly accepted format
J.T. Conklin <jtc@acorntoolworks.com>
parents: 15542
diff changeset
330
6ed6226ab0af parse-datetime: document the newly accepted format
J.T. Conklin <jtc@acorntoolworks.com>
parents: 15542
diff changeset
331 @cindex @sc{iso} 8601 date and time of day format
6ed6226ab0af parse-datetime: document the newly accepted format
J.T. Conklin <jtc@acorntoolworks.com>
parents: 15542
diff changeset
332 @cindex date and time of day format, @sc{iso} 8601
6ed6226ab0af parse-datetime: document the newly accepted format
J.T. Conklin <jtc@acorntoolworks.com>
parents: 15542
diff changeset
333
6ed6226ab0af parse-datetime: document the newly accepted format
J.T. Conklin <jtc@acorntoolworks.com>
parents: 15542
diff changeset
334 The @sc{iso} 8601 extended date and time of day format is an @sc{iso}
6ed6226ab0af parse-datetime: document the newly accepted format
J.T. Conklin <jtc@acorntoolworks.com>
parents: 15542
diff changeset
335 8601 date, a @samp{T} character separator, followed by an @sc{iso} 8601 time
6ed6226ab0af parse-datetime: document the newly accepted format
J.T. Conklin <jtc@acorntoolworks.com>
parents: 15542
diff changeset
336 of day.
6ed6226ab0af parse-datetime: document the newly accepted format
J.T. Conklin <jtc@acorntoolworks.com>
parents: 15542
diff changeset
337
6ed6226ab0af parse-datetime: document the newly accepted format
J.T. Conklin <jtc@acorntoolworks.com>
parents: 15542
diff changeset
338
13769
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
339 @node Day of week items
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
340 @section Day of week items
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
341
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
342 @cindex day of week item
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
343
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
344 The explicit mention of a day of the week will forward the date
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
345 (only if necessary) to reach that day of the week in the future.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
346
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
347 Days of the week may be spelled out in full: @samp{Sunday},
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
348 @samp{Monday}, @samp{Tuesday}, @samp{Wednesday}, @samp{Thursday},
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
349 @samp{Friday} or @samp{Saturday}. Days may be abbreviated to their
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
350 first three letters, optionally followed by a period. The special
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
351 abbreviations @samp{Tues} for @samp{Tuesday}, @samp{Wednes} for
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
352 @samp{Wednesday} and @samp{Thur} or @samp{Thurs} for @samp{Thursday} are
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
353 also allowed.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
354
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
355 @findex next @var{day}
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
356 @findex last @var{day}
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
357 A number may precede a day of the week item to move forward
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
358 supplementary weeks. It is best used in expression like @samp{third
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
359 monday}. In this context, @samp{last @var{day}} or @samp{next
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
360 @var{day}} is also acceptable; they move one week before or after
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
361 the day that @var{day} by itself would represent.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
362
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
363 A comma following a day of the week item is ignored.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
364
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
365
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
366 @node Relative items in date strings
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
367 @section Relative items in date strings
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
368
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
369 @cindex relative items in date strings
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
370 @cindex displacement of dates
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
371
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
372 @dfn{Relative items} adjust a date (or the current date if none) forward
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
373 or backward. The effects of relative items accumulate. Here are some
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
374 examples:
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
375
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
376 @example
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
377 1 year
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
378 1 year ago
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
379 3 years
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
380 2 days
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
381 @end example
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
382
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
383 @findex year @r{in date strings}
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
384 @findex month @r{in date strings}
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
385 @findex fortnight @r{in date strings}
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
386 @findex week @r{in date strings}
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
387 @findex day @r{in date strings}
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
388 @findex hour @r{in date strings}
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
389 @findex minute @r{in date strings}
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
390 The unit of time displacement may be selected by the string @samp{year}
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
391 or @samp{month} for moving by whole years or months. These are fuzzy
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
392 units, as years and months are not all of equal duration. More precise
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
393 units are @samp{fortnight} which is worth 14 days, @samp{week} worth 7
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
394 days, @samp{day} worth 24 hours, @samp{hour} worth 60 minutes,
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
395 @samp{minute} or @samp{min} worth 60 seconds, and @samp{second} or
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
396 @samp{sec} worth one second. An @samp{s} suffix on these units is
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
397 accepted and ignored.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
398
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
399 @findex ago @r{in date strings}
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
400 The unit of time may be preceded by a multiplier, given as an optionally
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
401 signed number. Unsigned numbers are taken as positively signed. No
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
402 number at all implies 1 for a multiplier. Following a relative item by
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
403 the string @samp{ago} is equivalent to preceding the unit by a
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
404 multiplier with value @math{-1}.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
405
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
406 @findex day @r{in date strings}
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
407 @findex tomorrow @r{in date strings}
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
408 @findex yesterday @r{in date strings}
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
409 The string @samp{tomorrow} is worth one day in the future (equivalent
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
410 to @samp{day}), the string @samp{yesterday} is worth
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
411 one day in the past (equivalent to @samp{day ago}).
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
412
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
413 @findex now @r{in date strings}
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
414 @findex today @r{in date strings}
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
415 @findex this @r{in date strings}
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
416 The strings @samp{now} or @samp{today} are relative items corresponding
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
417 to zero-valued time displacement, these strings come from the fact
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
418 a zero-valued time displacement represents the current time when not
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
419 otherwise changed by previous items. They may be used to stress other
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
420 items, like in @samp{12:00 today}. The string @samp{this} also has
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
421 the meaning of a zero-valued time displacement, but is preferred in
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
422 date strings like @samp{this thursday}.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
423
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
424 When a relative item causes the resulting date to cross a boundary
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
425 where the clocks were adjusted, typically for daylight saving time,
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
426 the resulting date and time are adjusted accordingly.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
427
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
428 The fuzz in units can cause problems with relative items. For
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
429 example, @samp{2003-07-31 -1 month} might evaluate to 2003-07-01,
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
430 because 2003-06-31 is an invalid date. To determine the previous
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
431 month more reliably, you can ask for the month before the 15th of the
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
432 current month. For example:
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
433
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
434 @example
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
435 $ date -R
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
436 Thu, 31 Jul 2003 13:02:39 -0700
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
437 $ date --date='-1 month' +'Last month was %B?'
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
438 Last month was July?
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
439 $ date --date="$(date +%Y-%m-15) -1 month" +'Last month was %B!'
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
440 Last month was June!
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
441 @end example
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
442
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
443 Also, take care when manipulating dates around clock changes such as
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
444 daylight saving leaps. In a few cases these have added or subtracted
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
445 as much as 24 hours from the clock, so it is often wise to adopt
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
446 universal time by setting the @env{TZ} environment variable to
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
447 @samp{UTC0} before embarking on calendrical calculations.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
448
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
449 @node Pure numbers in date strings
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
450 @section Pure numbers in date strings
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
451
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
452 @cindex pure numbers in date strings
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
453
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
454 The precise interpretation of a pure decimal number depends
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
455 on the context in the date string.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
456
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
457 If the decimal number is of the form @var{yyyy}@var{mm}@var{dd} and no
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
458 other calendar date item (@pxref{Calendar date items}) appears before it
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
459 in the date string, then @var{yyyy} is read as the year, @var{mm} as the
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
460 month number and @var{dd} as the day of the month, for the specified
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
461 calendar date.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
462
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
463 If the decimal number is of the form @var{hh}@var{mm} and no other time
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
464 of day item appears before it in the date string, then @var{hh} is read
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
465 as the hour of the day and @var{mm} as the minute of the hour, for the
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
466 specified time of day. @var{mm} can also be omitted.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
467
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
468 If both a calendar date and a time of day appear to the left of a number
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
469 in the date string, but no relative item, then the number overrides the
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
470 year.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
471
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
472
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
473 @node Seconds since the Epoch
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
474 @section Seconds since the Epoch
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
475
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
476 If you precede a number with @samp{@@}, it represents an internal time
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
477 stamp as a count of seconds. The number can contain an internal
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
478 decimal point (either @samp{.} or @samp{,}); any excess precision not
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
479 supported by the internal representation is truncated toward minus
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
480 infinity. Such a number cannot be combined with any other date
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
481 item, as it specifies a complete time stamp.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
482
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
483 @cindex beginning of time, for @acronym{POSIX}
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
484 @cindex epoch, for @acronym{POSIX}
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
485 Internally, computer times are represented as a count of seconds since
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
486 an epoch---a well-defined point of time. On @acronym{GNU} and
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
487 @acronym{POSIX} systems, the epoch is 1970-01-01 00:00:00 @sc{utc}, so
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
488 @samp{@@0} represents this time, @samp{@@1} represents 1970-01-01
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
489 00:00:01 @sc{utc}, and so forth. @acronym{GNU} and most other
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
490 @acronym{POSIX}-compliant systems support such times as an extension
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
491 to @acronym{POSIX}, using negative counts, so that @samp{@@-1}
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
492 represents 1969-12-31 23:59:59 @sc{utc}.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
493
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
494 Traditional Unix systems count seconds with 32-bit two's-complement
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
495 integers and can represent times from 1901-12-13 20:45:52 through
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
496 2038-01-19 03:14:07 @sc{utc}. More modern systems use 64-bit counts
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
497 of seconds with nanosecond subcounts, and can represent all the times
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
498 in the known lifetime of the universe to a resolution of 1 nanosecond.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
499
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
500 On most hosts, these counts ignore the presence of leap seconds.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
501 For example, on most hosts @samp{@@915148799} represents 1998-12-31
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
502 23:59:59 @sc{utc}, @samp{@@915148800} represents 1999-01-01 00:00:00
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
503 @sc{utc}, and there is no way to represent the intervening leap second
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
504 1998-12-31 23:59:60 @sc{utc}.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
505
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
506 @node Specifying time zone rules
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
507 @section Specifying time zone rules
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
508
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
509 @vindex TZ
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
510 Normally, dates are interpreted using the rules of the current time
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
511 zone, which in turn are specified by the @env{TZ} environment
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
512 variable, or by a system default if @env{TZ} is not set. To specify a
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
513 different set of default time zone rules that apply just to one date,
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
514 start the date with a string of the form @samp{TZ="@var{rule}"}. The
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
515 two quote characters (@samp{"}) must be present in the date, and any
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
516 quotes or backslashes within @var{rule} must be escaped by a
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
517 backslash.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
518
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
519 For example, with the @acronym{GNU} @command{date} command you can
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
520 answer the question ``What time is it in New York when a Paris clock
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
521 shows 6:30am on October 31, 2004?'' by using a date beginning with
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
522 @samp{TZ="Europe/Paris"} as shown in the following shell transcript:
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
523
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
524 @example
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
525 $ export TZ="America/New_York"
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
526 $ date --date='TZ="Europe/Paris" 2004-10-31 06:30'
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
527 Sun Oct 31 01:30:00 EDT 2004
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
528 @end example
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
529
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
530 In this example, the @option{--date} operand begins with its own
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
531 @env{TZ} setting, so the rest of that operand is processed according
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
532 to @samp{Europe/Paris} rules, treating the string @samp{2004-10-31
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
533 06:30} as if it were in Paris. However, since the output of the
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
534 @command{date} command is processed according to the overall time zone
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
535 rules, it uses New York time. (Paris was normally six hours ahead of
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
536 New York in 2004, but this example refers to a brief Halloween period
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
537 when the gap was five hours.)
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
538
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
539 A @env{TZ} value is a rule that typically names a location in the
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
540 @uref{http://www.twinsun.com/tz/tz-link.htm, @samp{tz} database}.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
541 A recent catalog of location names appears in the
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
542 @uref{http://twiki.org/cgi-bin/xtra/tzdate, TWiki Date and Time
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
543 Gateway}. A few non-@acronym{GNU} hosts require a colon before a
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
544 location name in a @env{TZ} setting, e.g.,
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
545 @samp{TZ=":America/New_York"}.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
546
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
547 The @samp{tz} database includes a wide variety of locations ranging
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
548 from @samp{Arctic/Longyearbyen} to @samp{Antarctica/South_Pole}, but
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
549 if you are at sea and have your own private time zone, or if you are
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
550 using a non-@acronym{GNU} host that does not support the @samp{tz}
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
551 database, you may need to use a @acronym{POSIX} rule instead. Simple
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
552 @acronym{POSIX} rules like @samp{UTC0} specify a time zone without
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
553 daylight saving time; other rules can specify simple daylight saving
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
554 regimes. @xref{TZ Variable,, Specifying the Time Zone with @code{TZ},
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
555 libc, The GNU C Library}.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
556
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
557 @node Authors of parse_datetime
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
558 @section Authors of @code{parse_datetime}
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
559 @c the anchor keeps the old node name, to try to avoid breaking links
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
560 @anchor{Authors of get_date}
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
561
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
562 @cindex authors of @code{parse_datetime}
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
563
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
564 @cindex Bellovin, Steven M.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
565 @cindex Salz, Rich
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
566 @cindex Berets, Jim
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
567 @cindex MacKenzie, David
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
568 @cindex Meyering, Jim
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
569 @cindex Eggert, Paul
13775
2654d3d40f47 docs: update parse-datetime history
Eric Blake <eblake@redhat.com>
parents: 13770
diff changeset
570 @code{parse_datetime} started life as @code{getdate}, as originally
2654d3d40f47 docs: update parse-datetime history
Eric Blake <eblake@redhat.com>
parents: 13770
diff changeset
571 implemented by Steven M. Bellovin
13769
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
572 (@email{smb@@research.att.com}) while at the University of North Carolina
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
573 at Chapel Hill. The code was later tweaked by a couple of people on
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
574 Usenet, then completely overhauled by Rich $alz (@email{rsalz@@bbn.com})
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
575 and Jim Berets (@email{jberets@@bbn.com}) in August, 1990. Various
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
576 revisions for the @sc{gnu} system were made by David MacKenzie, Jim Meyering,
13775
2654d3d40f47 docs: update parse-datetime history
Eric Blake <eblake@redhat.com>
parents: 13770
diff changeset
577 Paul Eggert and others, including renaming it to @code{get_date} to
2654d3d40f47 docs: update parse-datetime history
Eric Blake <eblake@redhat.com>
parents: 13770
diff changeset
578 avoid a conflict with the alternative Posix function @code{getdate},
2654d3d40f47 docs: update parse-datetime history
Eric Blake <eblake@redhat.com>
parents: 13770
diff changeset
579 and a later rename to @code{parse_datetime}. The Posix function
2654d3d40f47 docs: update parse-datetime history
Eric Blake <eblake@redhat.com>
parents: 13770
diff changeset
580 @code{getdate} can parse more locale-specific dates using
2654d3d40f47 docs: update parse-datetime history
Eric Blake <eblake@redhat.com>
parents: 13770
diff changeset
581 @code{strptime}, but relies on an environment variable and external
2654d3d40f47 docs: update parse-datetime history
Eric Blake <eblake@redhat.com>
parents: 13770
diff changeset
582 file, and lacks the thread-safety of @code{parse_datetime}.
13769
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
583
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
584 @cindex Pinard, F.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
585 @cindex Berry, K.
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
586 This chapter was originally produced by Fran@,{c}ois Pinard
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
587 (@email{pinard@@iro.umontreal.ca}) from the @file{parse_datetime.y} source code,
896628c568fa parse-datetime: better name than get_date
Eric Blake <eblake@redhat.com>
parents:
diff changeset
588 and then edited by K.@: Berry (@email{kb@@cs.umb.edu}).