coreutils: Relative items in date strings

1 
1 29.7 Relative items in date strings
1 ===================================
1 
1 “Relative items” adjust a date (or the current date if none) forward or
1 backward.  The effects of relative items accumulate.  Here are some
1 examples:
1 
1      1 year
1      1 year ago
1      3 years
1      2 days
1 
1    The unit of time displacement may be selected by the string ‘year’ or
1 ‘month’ for moving by whole years or months.  These are fuzzy units, as
1 years and months are not all of equal duration.  More precise units are
1 ‘fortnight’ which is worth 14 days, ‘week’ worth 7 days, ‘day’ worth 24
1 hours, ‘hour’ worth 60 minutes, ‘minute’ or ‘min’ worth 60 seconds, and
1 ‘second’ or ‘sec’ worth one second.  An ‘s’ suffix on these units is
1 accepted and ignored.
1 
1    The unit of time may be preceded by a multiplier, given as an
1 optionally signed number.  Unsigned numbers are taken as positively
1 signed.  No number at all implies 1 for a multiplier.  Following a
1 relative item by the string ‘ago’ is equivalent to preceding the unit by
1 a multiplier with value -1.
1 
1    The string ‘tomorrow’ is worth one day in the future (equivalent to
1 ‘day’), the string ‘yesterday’ is worth one day in the past (equivalent
1 to ‘day ago’).
1 
1    The strings ‘now’ or ‘today’ are relative items corresponding to
1 zero-valued time displacement, these strings come from the fact a
1 zero-valued time displacement represents the current time when not
1 otherwise changed by previous items.  They may be used to stress other
1 items, like in ‘12:00 today’.  The string ‘this’ also has the meaning of
1 a zero-valued time displacement, but is preferred in date strings like
1 ‘this thursday’.
1 
1    When a relative item causes the resulting date to cross a boundary
1 where the clocks were adjusted, typically for daylight saving time, the
1 resulting date and time are adjusted accordingly.
1 
1    The fuzz in units can cause problems with relative items.  For
1 example, ‘2003-07-31 -1 month’ might evaluate to 2003-07-01, because
1 2003-06-31 is an invalid date.  To determine the previous month more
1 reliably, you can ask for the month before the 15th of the current
1 month.  For example:
1 
1      $ date -R
1      Thu, 31 Jul 2003 13:02:39 -0700
1      $ date --date='-1 month' +'Last month was %B?'
1      Last month was July?
1      $ date --date="$(date +%Y-%m-15) -1 month" +'Last month was %B!'
1      Last month was June!
1 
1    Also, take care when manipulating dates around clock changes such as
1 daylight saving leaps.  In a few cases these have added or subtracted as
1 much as 24 hours from the clock, so it is often wise to adopt universal
1 time by setting the ‘TZ’ environment variable to ‘UTC0’ before embarking
1 on calendrical calculations.
1