octave-jordi/gnulib-hg: doc/parse-datetime.texi annotate

annotate doc/parse-datetime.texi @ 18025:5201cc72e203

savedir: avoid undefined behavior in qsort call GCC 5.1.1 -fsanitize=undefined with glibc 2.21 is returning: "runtime error: null pointer passed as argument 1, which is declared to never be null" * lib/savedir.c (streamsavedir): Avoid the call with no entries.

author	Pádraig Brady <P@draigBrady.com>
date	Wed, 24 Jun 2015 19:08:08 +0100
parents	69801cc56551
children

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
17848 ab58d4870664 version-etc: new year Paul Eggert <eggert@cs.ucla.edu> parents: 17587 diff changeset	3 @c Copyright (C) 1994-2006, 2009-2015 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
17967 69801cc56551 doc: update FDL template to match FDL examples. Simon Josefsson <simon@josefsson.org> parents: 17848 diff changeset	8 @c Invariant Sections, no Front-Cover Texts, and no Back-Cover
13769 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
17223 4e33322b32f8 Hyphen and dash fixes. Paul Eggert <eggert@cs.ucla.edu> parents: 17060 diff changeset	41 ---Robert Grudin, @cite{Time and the Art of Living}.
13769 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
17274 69f030e5cec4 doc: avoid small caps Paul Eggert <eggert@cs.ucla.edu> parents: 17249 diff changeset	44 This section describes the textual date representations that GNU
13769 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.
17274 69f030e5cec4 doc: avoid small caps Paul Eggert <eggert@cs.ucla.edu> parents: 17249 diff changeset	53 * Time zone items:: EST, PDT, UTC, @dots{}
17275 ce300324a44c doc: improve ISO 8601 discussion Paul Eggert <eggert@cs.ucla.edu> parents: 17274 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
16968 20011163d6c7 parse-datetime: doc tuneup Paul Eggert <eggert@cs.ucla.edu> parents: 16201 diff changeset	120 standard meaning for time zone items like @samp{IST}@. When using
13769 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
16968 20011163d6c7 parse-datetime: doc tuneup Paul Eggert <eggert@cs.ucla.edu> parents: 16201 diff changeset	123 use time zone items other than @samp{UTC} and @samp{Z}@. Here are some
13769 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
16968 20011163d6c7 parse-datetime: doc tuneup Paul Eggert <eggert@cs.ucla.edu> parents: 16201 diff changeset	148 @cindex leap seconds
13769 896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	149 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	150 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	151 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	152 corresponds to a valid leap second.
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
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	155 @node Calendar date items
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	156 @section Calendar date items
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	157
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	158 @cindex calendar date item
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	159
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	160 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	161 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	162 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	163
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	164 @example
17274 69f030e5cec4 doc: avoid small caps Paul Eggert <eggert@cs.ucla.edu> parents: 17249 diff changeset	165 1972-09-24 # ISO 8601.
13769 896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	166 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	167 # 20xx for 00 through 68.
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	168 72-09-24 # Leading zeros are ignored.
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	169 9/24/72 # Common U.S. writing.
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	170 24 September 1972
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	171 24 Sept 72 # September has a special abbreviation.
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	172 24 Sep 72 # Three-letter abbreviations always allowed.
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	173 Sep 24, 1972
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	174 24-sep-72
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	175 24sep72
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	176 @end example
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	177
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	178 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	179 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	180
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	181 @example
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	182 9/24
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	183 sep 24
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	184 @end example
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	185
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	186 Here are the rules.
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	187
17274 69f030e5cec4 doc: avoid small caps Paul Eggert <eggert@cs.ucla.edu> parents: 17249 diff changeset	188 @cindex ISO 8601 date format
69f030e5cec4 doc: avoid small caps Paul Eggert <eggert@cs.ucla.edu> parents: 17249 diff changeset	189 @cindex date format, ISO 8601
69f030e5cec4 doc: avoid small caps Paul Eggert <eggert@cs.ucla.edu> parents: 17249 diff changeset	190 For numeric months, the ISO 8601 format
13769 896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	191 @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	192 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	193 @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	194 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	195 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	196 then 1900 is added to it. The construct
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	197 @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	198 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	199
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	200 @cindex month names in date strings
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	201 @cindex abbreviations for months
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	202 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	203 @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	204 @samp{July}, @samp{August}, @samp{September}, @samp{October},
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	205 @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	206 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	207 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	208
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	209 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	210 of the following:
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	211
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	212 @example
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	213 @var{day} @var{month} @var{year}
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	214 @var{day} @var{month}
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	215 @var{month} @var{day} @var{year}
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	216 @var{day}-@var{month}-@var{year}
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	217 @end example
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	218
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	219 Or, omitting the year:
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	220
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	221 @example
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	222 @var{month} @var{day}
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	223 @end example
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
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	226 @node Time of day items
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	227 @section Time of day items
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	228
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	229 @cindex time of day item
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	230
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	231 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	232 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	233
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	234 @example
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	235 20:02:00.000000
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	236 20:02
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	237 8:02pm
17274 69f030e5cec4 doc: avoid small caps Paul Eggert <eggert@cs.ucla.edu> parents: 17249 diff changeset	238 20:02-0500 # In EST (U.S. Eastern Standard Time).
13769 896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	239 @end example
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	240
16968 20011163d6c7 parse-datetime: doc tuneup Paul Eggert <eggert@cs.ucla.edu> parents: 16201 diff changeset	241 @cindex leap seconds
13769 896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	242 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	243 @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	244 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	245 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	246 @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	247 Alternatively,
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	248 @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	249 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	250 may be 60.
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	251
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	252 @findex am @r{in date strings}
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	253 @findex pm @r{in date strings}
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	254 @findex midnight @r{in date strings}
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	255 @findex noon @r{in date strings}
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	256 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	257 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	258 @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	259 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	260 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	261 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	262 (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	263 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	264 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	265
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	266 @cindex time zone correction
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	267 @cindex minutes, time zone correction by
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	268 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	269 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	270 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	271 of zone minutes.
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	272 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	273 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	274 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	275 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	276 forces interpretation of the time relative to
17274 69f030e5cec4 doc: avoid small caps Paul Eggert <eggert@cs.ucla.edu> parents: 17249 diff changeset	277 Coordinated Universal Time (UTC), overriding any previous
13769 896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	278 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	279 @samp{+0530} and @samp{+05:30} both stand for the time zone 5.5 hours
17274 69f030e5cec4 doc: avoid small caps Paul Eggert <eggert@cs.ucla.edu> parents: 17249 diff changeset	280 ahead of UTC (e.g., India).
13769 896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	281 This is the best way to
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	282 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	283 The maximum zone correction is 24 hours.
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	284
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	285 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	286 but not both.
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	287
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	288
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	289 @node Time zone items
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	290 @section Time zone items
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 @cindex time zone item
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	293
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	294 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	295 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	296 for Coordinated Universal
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	297 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	298 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	299 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	300 daylight saving time zone may be specified.
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	301 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	302 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	303 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	304 @samp{+05:30}.
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	305
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	306 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	307 are obsolescent and are not recommended, because they
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	308 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	309 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	310 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	311 described in the previous section.
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	312
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	313 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	314 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	315 (@pxref{Specifying time zone rules}).
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	316
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	317
15580 6ed6226ab0af parse-datetime: document the newly accepted format J.T. Conklin <jtc@acorntoolworks.com> parents: 15542 diff changeset	318 @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	319 @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	320
6ed6226ab0af parse-datetime: document the newly accepted format J.T. Conklin <jtc@acorntoolworks.com> parents: 15542 diff changeset	321 @cindex combined date and time of day item
17274 69f030e5cec4 doc: avoid small caps Paul Eggert <eggert@cs.ucla.edu> parents: 17249 diff changeset	322 @cindex ISO 8601 date and time of day format
69f030e5cec4 doc: avoid small caps Paul Eggert <eggert@cs.ucla.edu> parents: 17249 diff changeset	323 @cindex date and time of day format, ISO 8601
15580 6ed6226ab0af parse-datetime: document the newly accepted format J.T. Conklin <jtc@acorntoolworks.com> parents: 15542 diff changeset	324
17275 ce300324a44c doc: improve ISO 8601 discussion Paul Eggert <eggert@cs.ucla.edu> parents: 17274 diff changeset	325 The ISO 8601 date and time of day extended format consists of an ISO
ce300324a44c doc: improve ISO 8601 discussion Paul Eggert <eggert@cs.ucla.edu> parents: 17274 diff changeset	326 8601 date, a @samp{T} character separator, and an ISO 8601 time of
ce300324a44c doc: improve ISO 8601 discussion Paul Eggert <eggert@cs.ucla.edu> parents: 17274 diff changeset	327 day. This format is also recognized if the @samp{T} is replaced by a
ce300324a44c doc: improve ISO 8601 discussion Paul Eggert <eggert@cs.ucla.edu> parents: 17274 diff changeset	328 space.
15580 6ed6226ab0af parse-datetime: document the newly accepted format J.T. Conklin <jtc@acorntoolworks.com> parents: 15542 diff changeset	329
17275 ce300324a44c doc: improve ISO 8601 discussion Paul Eggert <eggert@cs.ucla.edu> parents: 17274 diff changeset	330 In this format, the time of day should use 24-hour notation.
ce300324a44c doc: improve ISO 8601 discussion Paul Eggert <eggert@cs.ucla.edu> parents: 17274 diff changeset	331 Fractional seconds are allowed, with either comma or period preceding
ce300324a44c doc: improve ISO 8601 discussion Paul Eggert <eggert@cs.ucla.edu> parents: 17274 diff changeset	332 the fraction. ISO 8601 fractional minutes and hours are not
ce300324a44c doc: improve ISO 8601 discussion Paul Eggert <eggert@cs.ucla.edu> parents: 17274 diff changeset	333 supported. Typically, hosts support nanosecond timestamp resolution;
ce300324a44c doc: improve ISO 8601 discussion Paul Eggert <eggert@cs.ucla.edu> parents: 17274 diff changeset	334 excess precision is silently discarded.
ce300324a44c doc: improve ISO 8601 discussion Paul Eggert <eggert@cs.ucla.edu> parents: 17274 diff changeset	335
ce300324a44c doc: improve ISO 8601 discussion Paul Eggert <eggert@cs.ucla.edu> parents: 17274 diff changeset	336 Here are some examples:
ce300324a44c doc: improve ISO 8601 discussion Paul Eggert <eggert@cs.ucla.edu> parents: 17274 diff changeset	337
ce300324a44c doc: improve ISO 8601 discussion Paul Eggert <eggert@cs.ucla.edu> parents: 17274 diff changeset	338 @example
ce300324a44c doc: improve ISO 8601 discussion Paul Eggert <eggert@cs.ucla.edu> parents: 17274 diff changeset	339 2012-09-24T20:02:00.052-0500
ce300324a44c doc: improve ISO 8601 discussion Paul Eggert <eggert@cs.ucla.edu> parents: 17274 diff changeset	340 2012-12-31T23:59:59,999999999+1100
ce300324a44c doc: improve ISO 8601 discussion Paul Eggert <eggert@cs.ucla.edu> parents: 17274 diff changeset	341 1970-01-01 00:00Z
ce300324a44c doc: improve ISO 8601 discussion Paul Eggert <eggert@cs.ucla.edu> parents: 17274 diff changeset	342 @end example
15580 6ed6226ab0af parse-datetime: document the newly accepted format J.T. Conklin <jtc@acorntoolworks.com> parents: 15542 diff changeset	343
13769 896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	344 @node Day of week items
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	345 @section Day of week items
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 @cindex day of week item
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	348
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	349 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	350 (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	351
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	352 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	353 @samp{Monday}, @samp{Tuesday}, @samp{Wednesday}, @samp{Thursday},
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	354 @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	355 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	356 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	357 @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	358 also allowed.
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	359
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	360 @findex next @var{day}
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	361 @findex last @var{day}
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	362 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	363 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	364 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	365 @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	366 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	367
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	368 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	369
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	370
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	371 @node Relative items in date strings
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	372 @section Relative items in date strings
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	373
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	374 @cindex relative items in date strings
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	375 @cindex displacement of dates
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	376
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	377 @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	378 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	379 examples:
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	380
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	381 @example
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	382 1 year
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	383 1 year ago
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	384 3 years
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	385 2 days
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	386 @end example
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	387
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	388 @findex year @r{in date strings}
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	389 @findex month @r{in date strings}
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	390 @findex fortnight @r{in date strings}
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	391 @findex week @r{in date strings}
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	392 @findex day @r{in date strings}
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	393 @findex hour @r{in date strings}
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	394 @findex minute @r{in date strings}
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	395 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	396 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	397 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	398 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	399 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	400 @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	401 @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	402 accepted and ignored.
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	403
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	404 @findex ago @r{in date strings}
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	405 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	406 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	407 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	408 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	409 multiplier with value @math{-1}.
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	410
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	411 @findex day @r{in date strings}
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	412 @findex tomorrow @r{in date strings}
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	413 @findex yesterday @r{in date strings}
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	414 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	415 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	416 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	417
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	418 @findex now @r{in date strings}
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	419 @findex today @r{in date strings}
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	420 @findex this @r{in date strings}
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	421 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	422 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	423 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	424 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	425 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	426 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	427 date strings like @samp{this thursday}.
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	428
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	429 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	430 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	431 the resulting date and time are adjusted accordingly.
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	432
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	433 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	434 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	435 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	436 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	437 current month. For example:
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	438
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	439 @example
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	440 $ date -R
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	441 Thu, 31 Jul 2003 13:02:39 -0700
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	442 $ date --date='-1 month' +'Last month was %B?'
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	443 Last month was July?
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	444 $ 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	445 Last month was June!
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	446 @end example
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	447
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	448 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	449 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	450 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	451 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	452 @samp{UTC0} before embarking on calendrical calculations.
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 @node Pure numbers in date strings
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	455 @section Pure numbers in date strings
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 @cindex pure numbers in date strings
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	458
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	459 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	460 on the context in the date string.
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	461
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	462 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	463 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	464 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	465 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	466 calendar date.
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 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	469 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	470 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	471 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	472
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	473 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	474 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	475 year.
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	476
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	477
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	478 @node Seconds since the Epoch
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	479 @section Seconds since the Epoch
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	480
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	481 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	482 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	483 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	484 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	485 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	486 item, as it specifies a complete time stamp.
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	487
17060 4c9ad7a11699 doc: do not use @acronym Paul Eggert <eggert@cs.ucla.edu> parents: 16968 diff changeset	488 @cindex beginning of time, for POSIX
4c9ad7a11699 doc: do not use @acronym Paul Eggert <eggert@cs.ucla.edu> parents: 16968 diff changeset	489 @cindex epoch, for POSIX
13769 896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	490 Internally, computer times are represented as a count of seconds since
17060 4c9ad7a11699 doc: do not use @acronym Paul Eggert <eggert@cs.ucla.edu> parents: 16968 diff changeset	491 an epoch---a well-defined point of time. On GNU and
17274 69f030e5cec4 doc: avoid small caps Paul Eggert <eggert@cs.ucla.edu> parents: 17249 diff changeset	492 POSIX systems, the epoch is 1970-01-01 00:00:00 UTC, so
13769 896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	493 @samp{@@0} represents this time, @samp{@@1} represents 1970-01-01
17274 69f030e5cec4 doc: avoid small caps Paul Eggert <eggert@cs.ucla.edu> parents: 17249 diff changeset	494 00:00:01 UTC, and so forth. GNU and most other
17060 4c9ad7a11699 doc: do not use @acronym Paul Eggert <eggert@cs.ucla.edu> parents: 16968 diff changeset	495 POSIX-compliant systems support such times as an extension
4c9ad7a11699 doc: do not use @acronym Paul Eggert <eggert@cs.ucla.edu> parents: 16968 diff changeset	496 to POSIX, using negative counts, so that @samp{@@-1}
17274 69f030e5cec4 doc: avoid small caps Paul Eggert <eggert@cs.ucla.edu> parents: 17249 diff changeset	497 represents 1969-12-31 23:59:59 UTC.
13769 896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	498
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	499 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	500 integers and can represent times from 1901-12-13 20:45:52 through
17274 69f030e5cec4 doc: avoid small caps Paul Eggert <eggert@cs.ucla.edu> parents: 17249 diff changeset	501 2038-01-19 03:14:07 UTC@. More modern systems use 64-bit counts
13769 896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	502 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	503 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	504
16968 20011163d6c7 parse-datetime: doc tuneup Paul Eggert <eggert@cs.ucla.edu> parents: 16201 diff changeset	505 @cindex leap seconds
13769 896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	506 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	507 For example, on most hosts @samp{@@915148799} represents 1998-12-31
17274 69f030e5cec4 doc: avoid small caps Paul Eggert <eggert@cs.ucla.edu> parents: 17249 diff changeset	508 23:59:59 UTC, @samp{@@915148800} represents 1999-01-01 00:00:00
69f030e5cec4 doc: avoid small caps Paul Eggert <eggert@cs.ucla.edu> parents: 17249 diff changeset	509 UTC, and there is no way to represent the intervening leap second
69f030e5cec4 doc: avoid small caps Paul Eggert <eggert@cs.ucla.edu> parents: 17249 diff changeset	510 1998-12-31 23:59:60 UTC.
13769 896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	511
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	512 @node Specifying time zone rules
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	513 @section Specifying time zone rules
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	514
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	515 @vindex TZ
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	516 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	517 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	518 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	519 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	520 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	521 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	522 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	523 backslash.
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	524
17060 4c9ad7a11699 doc: do not use @acronym Paul Eggert <eggert@cs.ucla.edu> parents: 16968 diff changeset	525 For example, with the GNU @command{date} command you can
13769 896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	526 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	527 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	528 @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	529
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	530 @example
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	531 $ export TZ="America/New_York"
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	532 $ 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	533 Sun Oct 31 01:30:00 EDT 2004
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	534 @end example
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	535
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	536 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	537 @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	538 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	539 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	540 @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	541 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	542 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	543 when the gap was five hours.)
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	544
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	545 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	546 @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	547 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	548 @uref{http://twiki.org/cgi-bin/xtra/tzdate, TWiki Date and Time
17060 4c9ad7a11699 doc: do not use @acronym Paul Eggert <eggert@cs.ucla.edu> parents: 16968 diff changeset	549 Gateway}. A few non-GNU hosts require a colon before a
13769 896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	550 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	551 @samp{TZ=":America/New_York"}.
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	552
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	553 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	554 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	555 if you are at sea and have your own private time zone, or if you are
17060 4c9ad7a11699 doc: do not use @acronym Paul Eggert <eggert@cs.ucla.edu> parents: 16968 diff changeset	556 using a non-GNU host that does not support the @samp{tz}
4c9ad7a11699 doc: do not use @acronym Paul Eggert <eggert@cs.ucla.edu> parents: 16968 diff changeset	557 database, you may need to use a POSIX rule instead. Simple
4c9ad7a11699 doc: do not use @acronym Paul Eggert <eggert@cs.ucla.edu> parents: 16968 diff changeset	558 POSIX rules like @samp{UTC0} specify a time zone without
13769 896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	559 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	560 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	561 libc, The GNU C Library}.
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	562
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	563 @node Authors of parse_datetime
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	564 @section Authors of @code{parse_datetime}
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	565 @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	566 @anchor{Authors of get_date}
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	567
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	568 @cindex authors of @code{parse_datetime}
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	569
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	570 @cindex Bellovin, Steven M.
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	571 @cindex Salz, Rich
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	572 @cindex Berets, Jim
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	573 @cindex MacKenzie, David
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	574 @cindex Meyering, Jim
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	575 @cindex Eggert, Paul
13775 2654d3d40f47 docs: update parse-datetime history Eric Blake <eblake@redhat.com> parents: 13770 diff changeset	576 @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	577 implemented by Steven M. Bellovin
13769 896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	578 (@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	579 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	580 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	581 and Jim Berets (@email{jberets@@bbn.com}) in August, 1990. Various
17274 69f030e5cec4 doc: avoid small caps Paul Eggert <eggert@cs.ucla.edu> parents: 17249 diff changeset	582 revisions for the 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	583 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	584 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	585 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	586 @code{getdate} can parse more locale-specific dates using
2654d3d40f47 docs: update parse-datetime history Eric Blake <eblake@redhat.com> parents: 13770 diff changeset	587 @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	588 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	589
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	590 @cindex Pinard, F.
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	591 @cindex Berry, K.
896628c568fa parse-datetime: better name than get_date Eric Blake <eblake@redhat.com> parents: diff changeset	592 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	593 (@email{pinard@@iro.umontreal.ca}) from the @file{parse_datetime.y} source code,
16968 20011163d6c7 parse-datetime: doc tuneup Paul Eggert <eggert@cs.ucla.edu> parents: 16201 diff changeset	594 and then edited by K. Berry (@email{kb@@cs.umb.edu}).

Mercurial > hg > octave-jordi > gnulib-hg

annotate doc/parse-datetime.texi @ 18025:5201cc72e203