General date syntax
===================
A "date" is a string, possibly empty, containing many items
separated by whitespace. The whitespace may be omitted when no
ambiguity arises. The empty string means the beginning of today (i.e.,
midnight). Order of the items is immaterial. A date string may contain
many flavors of items:
* calendar date items
* day of the week items
* relative items
* pure numbers.
We describe each of these item types in turn, below.
A few numbers may be written out in words in most contexts. This is
most useful for specifying day of the week items or relative items (see
below). Here is the list: `first' for 1, `next' for 2, `third' for 3,
`fourth' for 4, `fifth' for 5, `sixth' for 6, `seventh' for 7, `eighth'
for 8, `ninth' for 9, `tenth' for 10, `eleventh' for 11 and `twelfth'
for 12. Also, `last' means exactly -1.
When a month is written this way, it is still considered to be
written numerically, instead of being "spelled in full"; this changes
the allowed strings.
Alphabetic case is completely ignored in dates. Comments may be
introduced between round parentheses, as long as included parentheses
are properly nested. Hyphens not followed by a digit are currently
ignored. Leading zeros on numbers are ignored.
Calendar date item
==================
A "calendar date item" specifies a day of the year. It is specified
differently, depending on whether the month is specified numerically or
literally. All these strings specify the same calendar date:
1970-09-17 # ISO 8601.
70-9-17 # This century assumed by default.
70-09-17 # Leading zeros are ignored.
9/17/72 # Common U.S. writing.
24 September 1972
24 Sept 72 # September has a special abbreviation.
24 Sep 72 # Three-letter abbreviations always allowed.
Sep 24, 1972
24-sep-72
24sep72
The year can also be omitted. In this case, the last specified year
is used, or the current year if none. For example:
9/17
sep 17
Here are the rules.
For numeric months, the ISO 8601 format `YEAR-MONTH-DAY' is allowed,
where YEAR is any positive number, MONTH is a number between 01 and 12,
and DAY is a number between 01 and 31. A leading zero must be present
if a number is less than ten. If YEAR is less than 100, then 1900 is
added to it to force a date in this century. The construct
`MONTH/DAY/YEAR', popular in the United States, is accepted. Also
`MONTH/DAY', omitting the year.
Literal months may be spelled out in full: `January', `February',
`March', `April', `May', `June', `July', `August', `September',
`October', `November' or `December'. Literal months may be abbreviated
to their first three letters, possibly followed by an abbreviating dot.
It is also permitted to write `Sept' instead of `September'.
When months are written literally, the calendar date may be given as
any of the following:
DAY MONTH YEAR
DAY MONTH
MONTH DAY YEAR
DAY-MONTH-YEAR
Or, omitting the year:
MONTH DAY
Day of week item
================
The explicit mention of a day of the week will forward the date
(only if necessary) to reach that day of the week in the future.
Days of the week may be spelled out in full: `Sunday', `Monday',
`Tuesday', `Wednesday', `Thursday', `Friday' or `Saturday'. Days may
be abbreviated to their first three letters, optionally followed by a
period. The special abbreviations `Tues' for `Tuesday', `Wednes' for
`Wednesday' and `Thur' or `Thurs' for `Thursday' are also allowed.
A number may precede a day of the week item to move forward
supplementary weeks. It is best used in expression like `third
monday'. In this context, `last DAY' or `next DAY' is also acceptable;
they move one week before or after the day that DAY by itself would
represent.
A comma following a day of the week item is ignored.
Relative item in date strings
=============================
"Relative items" adjust a date (or the current date if none) forward
or backward. The effects of relative items accumulate. Here are some
examples:
1 year
1 year ago
3 years
2 days
The unit of time displacement may be selected by the string `year'
or `month' for moving by whole years or months. These are fuzzy units,
as years and months are not all of equal duration. More precise units
are `fortnight' which is worth 14 days, `week' worth 7 days, `day'
worth 24 hours, `hour' worth 60 minutes, `minute' or `min' worth 60
seconds, and `second' or `sec' worth one second. An `s' suffix on
these units is accepted and ignored.
The unit of time may be preceded by a multiplier, given as an
optionally signed number. Unsigned numbers are taken as positively
signed. No number at all implies 1 for a multiplier. Following a
relative item by the string `ago' is equivalent to preceding the unit
by a multiplicator with value -1.
The string `tomorrow' is worth one day in the future (equivalent to
`day'), the string `yesterday' is worth one day in the past (equivalent
to `day ago').
The strings `now' or `today' are relative items corresponding to
zero-valued time displacement, these strings come from the fact a
zero-valued time displacement represents the current time when not
otherwise change by previous items. They may be used to stress other
items, like in `12:00 today'. The string `this' also has the meaning
of a zero-valued time displacement, but is preferred in date strings
like `this thursday'.
When a relative item makes the resulting date to cross the boundary
between DST and non-DST (or vice-versa), the hour is adjusted according
to the local time.
Pure numbers in date strings
============================
The precise intepretation of a pure decimal number is dependent of
the context in the date string.
If the decimal number is of the form YYYYMMDD and no other calendar
date item (*note Calendar date item::.) appears before it in the date
string, then YYYY is read as the year, MM as the month number and DD as
the day of the month, for the specified calendar date.
If the decimal number is of the form HHMM and no other time of day
item appears before it in the date string, then HH is read as the hour
of the day and MM as the minute of the hour, for the specified time of
the day. MM can also be omitted.
If both a calendar date and a time of day appear to the left of a
number in the date string, but no relative item, then the number
overrides the year.