28.7 Relative items 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
multiplier 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 changed 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 causes the resulting date to cross a boundary
where the clocks were adjusted, typically for daylight saving time,
the resulting date and time are adjusted accordingly.

The fuzz in units can cause problems with relative items. For
example, ‘2003-07-31-1 month’ might evaluate to 2003-07-01,
because 2003-06-31 is an invalid date. To determine the previous
month more reliably, you can ask for the month before the 15th of the
current month. For example:

Also, take care when manipulating dates around clock changes such as
daylight saving leaps. In a few cases these have added or subtracted
as much as 24 hours from the clock, so it is often wise to adopt
universal time by setting the TZ environment variable to
‘UTC0’ before embarking on calendrical calculations.