This is dateutils.info, produced by makeinfo version 6.1 from
dateutils.texi.

INFO-DIR-SECTION Miscellaneous
START-INFO-DIR-ENTRY
* dateutils: (dateutils).	Command line tools to fiddle with dates.
END-INFO-DIR-ENTRY

INFO-DIR-SECTION Individual utilities
START-INFO-DIR-ENTRY
* dateadd: (dateutils)dateadd.          Add durations to dates or times.
* dateconv: (dateutils)dateconv.        Convert dates between
                                          calendars or time zones.
* datediff: (dateutils)datediff.        Compute durations between dates
                                          and times.
* dategrep: (dateutils)dategrep.        Find date or time matches in
                                          input stream.
* dateround: (dateutils)dateround.      Round dates or times to
                                          designated values.
* dateseq: (dateutils)dateseq.          Sequences of dates or times.
* datesort: (dateutils)datesort.        Sort chronologically.
* datetest: (dateutils)datetest.        Compare dates or times.
* datezone: (dateutils)datezone.        Convert date/times to
                                          different timezones in bulk.
* strptime: (dateutils)strptime.        Command line version
                                          of the C function.
END-INFO-DIR-ENTRY

This manual documents the dateutils package.

   Copyright (C) 2011-2016 Sebastian Freundt.

   Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts.  A copy of the license is included in the section entitled "GNU
Free Documentation License".


File: dateutils.info,  Node: Top,  Next: Introduction,  Up: (dir)

dateutils
*********

dateutils are a bunch of tools that revolve around fiddling with dates
and times in the command line with a strong focus on use cases that
arise when dealing with large amounts of financial data.

* Menu:

* Introduction::        Motivation, background, etc.
* Calendars::           Calendar concepts and format specs
* Format specifiers and units:: How to control input and output
* Localised input and output::  Date/times specific to regions
* Algorithms::          Some notes on the algorithms used
* dateadd::             Add durations to dates or times
* dateconv::            Convert dates between calendars or time zones
* datediff::            Compute durations between dates and times
* dategrep::            Find date or time matches in input stream
* dateround::           Round dates or times to designated values
* dateseq::             Generate sequences of dates or times
* datesort::            Sort the contents of files chronologically
* datetest::            Compare dates or times
* datezone::            Convert date/times to timezones in bulk
* strptime::            Command line version of the C function


File: dateutils.info,  Node: Introduction,  Next: Calendars,  Prev: Top,  Up: Top

1 Introduction
**************

The dateutils package is an attempt to provide a comprehensive set of
command line tools that behave intuitively, support a similar variety of
inputs, allow for normalised output and, most importantly, cover nearly
all tasks that arise whilst dealing with huge amounts of dates and
unusual calendars.

   In day to day business, the authors have run across a plethora of
approaches to tackle seemingly simple problems.  When the command line
is a necessity most of these involve perl or awk, which suffer from bad
maintainability simply because those tools weren't made to process dates
and times in particular, and for the same reason those approaches are
anything but fast.

   And conversely, good maintainability and fast processing is often
seen in integrated systems, such as R or database solutions but they
come at a price: little flexibility.  It's very uncommon to import
billions of dates into a database just to compare if they are greater
than or equal to a given date.  Besides, most of the time those billions
of dates come from external sources and have to be brought into shape
before or whilst importing them into an integrated system.


File: dateutils.info,  Node: Calendars,  Next: Format specifiers and units,  Prev: Introduction,  Up: Top

2 Calendars
***********

All of the dateutils command line apps are built around a library,
libdut.  The textual representation of dates is converted to an internal
one first, then the date operation is performed and the internal
representation in the end is converted back to a textual one.

   While many of the tools that provide date arithmetic or conversions
employ a single standard internal representation (mostly days since a
reference date, or seconds since the epoch), the date-core library
provides a variety of calendars, each suitable for one or more specific
tasks.

   Usually it's the tool's task to find out which calendar is the best
for the task at hand, but to use the library directly we give an
overview of the supported calendars here along with some of their
properties.

2.1 ymd, aka gregorian
======================

This is the 'ordinary' calendar, holding a year, a month and the day of
the month.  Years are subdivided into 12 months, months are subdivided
into 28 to 31 days.

   The canonical input and output format is '%Y-%m-%d' (ISO 8601).  For
outputs the format string 'ymd' can be used as well.

2.2 ymcw
========

This is a calendric system used at some security exchanges, and can be
thought of as a mixture of the year-month-day and year-week-day
calendars.  It holds a year, a month, a weekday and the count of the
weekday within the month.  So dates like the third Thursday in March
2011 can be expressed trivially in this system.  Years are subdivided
into months as in the ymd calendar, months consist of at least 4 and up
to 5 weeks and weeks are subdivided into weekdays, Monday, Tuesday,
Wednesday, Thursday, Friday, Saturday and Sunday.

   The canonical input and output format is '%Y-%m-%c-%w'.  The week is
enumerated by 01 for Monday, 02 for Tuesday, ..., 07 for Sunday, as
mandated by ISO 8601.  For outputs the format string 'ymcw' can be used
as well.

2.3 ywd
=======

This calendar is ISO's 8601 year-week-day calendar.  Every year is
divided into 52 weeks.  Every week is divided into 7 days, starting with
Monday.  To make up for "missing days" a leap week is introduced every
now and again, i.e.  years with leap weeks are 53 weeks long and called
leap years (note: ISO does not use the term leap year or leap week).

   The canonical input and output format is '%rY-W%V-%u', so e.g.
2012-W04-02.  Note that ywd years don't necessarily correspond to
Gregorian/ymd years, hence the 'r' modifier in the spec ('%rY' is used
in calendars to select the "real" calendar year).  The format string
'ywd' can be used as well.

2.4 daisy
=========

This is one of the most common calendric systems, it counts the days
since a given reference date (we originally went for daysi, short for
days since, but after the 100th spelling mistake, because daisy is so
much more natural, we decided to stick with daisy).  In the Julian
calendar this was the founding of Rome, in many database systems this is
the 1st Jan 1, or other convenient dates like the 1st Jan 1970 or 1st
Jan 1900.

   The (internal) dateutils reference day is the 31st Dec 1600, or
equivalently the Naught-th of Jan 1601.  This may look like an arbitrary
date but it has some interesting properties: - it is a Sunday, so
weekday computation is easy as it is a mod 7 operation only - the year
is 1 mod 4, so the number of leap years between the reference year and
any other year Y is simply Y div 4.

   In earlier versions we used 1917 for the reference year because it's
the first year after 1900 that meets the conditions above.  But then we
relaxed leap year rules to support dates beyond 2100 (2100 isn't a leap
year) so for symmetry reasons we should support years before 1917 in a
similar fashion.

   The daisy calendar has no notion of years or months.

   The daisy calendar as such has no associated input or output format.
This is because we reserve the freedom to change the reference date in
the future (like we have done in the past).  However, daisy is easily
converted to and from other similar day counting systems so their input
and output format may be used instead.

   Also noteworthy on a more informative level, dateutils globally
assumes the Gregorian date switch to have taken place in October 1582.
This is unlike some other well-known tools (Unix cal for instance) which
assume the reformation to have occurred in September 1752.

2.4.1 julian, jdn
-----------------

A close sibling to the daisy system described before is the Julian day
number, with reference date 01 Jan 4713 BC in the proleptic Julian
calendar.

   The input and output format string is 'jdn' or 'julian', there is no
format specifier.

2.4.2 lilian, ldn
-----------------

Another close sibling to the daisy system is the Lilian day number, its
reference date is the first day of the Gregorian calendar, 15 Oct 1582.

   The input and output format string is 'ldn' or 'lilian', there is no
format specifier.

2.4.3 matlab, mdn
-----------------

Taking the Lilian day number further (in a proleptic sense) to the
beginning of time, the First of January in year 0, you get the Matlab
day number.

   The input and output format string is 'mdn' or 'matlab', there is no
format specifier.

2.5 bizda
=========

This calendric system is actually a whole tribe of calendars, in its
canonical form this tracks the number of business days after last
month's ultimo.  Where business day means any non-weekend day.  Years
are divided into 12 months, each of which consists of 20 to 23 business
days.

   The canonical input and output format is '%Y-%m-%db', where 'b' is a
suffix modifier meaning business days since last month's ultimo.
Similarly, '%Y-%m-%dB' stands for the business days until this month's
ultimo.


File: dateutils.info,  Node: Format specifiers and units,  Next: Localised input and output,  Prev: Calendars,  Up: Top

3 Format specifiers and units
*****************************

The tools provided by dateutils would be pretty meaningless if you could
not control how input is to be read or results are to be printed.
Following the footsteps of proven systems (such as libc) output
formatting is controlled through format specifiers (and flags), as
covered by the next 2 sections.

   Nonetheless, some tools ('dadd', 'dseq') require durations to be
input.  Their syntax is covered in the final section.

3.1 Format specs
================

Format specs in dateutils are similar to posix' strftime().

   However, due to a broader range of supported calendars dateutils must
employ different rules.

   Date specs:
  %a  The abbreviated weekday name
  %A  The full weekday name
  %_a The weekday name shortened to a single character (MTWRFAS)
  %b  The abbreviated month name
  %B  The full month name
  %_b The month name shortened to a single character (FGHJKMNQUVXZ)
  %c  The count of the weekday within the month (range 00 to 05)
  %C  The count of the weekday within the year (range 00 to 53)
  %d  The day of the month, 2 digits (range 00 to 31)
  %D  The day of the year, 3 digits (range 000 to 366)
  %F  Equivalent to %Y-%m-%d (ymd's canonical format)
  %g  ISO week date year without the century (range 00 to 99)
  %G  ISO week date year including the century
  %j  Equivalent to %D
  %m  The month in the current calendar (range 00 to 19)
  %Q  The quarter of the year (range Q1 to Q4)
  %q  The number of the quarter (range 01 to 04)
  %s  The number of seconds since the Epoch.
  %u  The weekday as number (range 01 to 07, Sunday being 07)
  %U  The week count, first day of week is Sun (range 00 to 53)
  %V  The ISO week count, first day of week is Mon (range 01 to 53)
  %w  The weekday as number (range 00 to 06, Sunday being 00)
  %W  The week count, first day of week is Mon (range 00 to 53)
  %y  The year without a century (range 00 to 99)
  %Y  The year including the century
  %_y The year shortened to a single digit
  %Z  The zone offset in hours and minutes (HH:MM) with
      a preceding sign (+ for offsets east of UTC, - for offsets
      west of UTC)

  %Od The day as roman numerals
  %Om The month as roman numerals
  %Oy The two digit year as roman numerals
  %OY The year including the century as roman numerals

  %rs In time systems whose Epoch is different from the unix Epoch, this
      selects the number of seconds since then.
  %rY In calendars with years that don't coincide with the Gregorian
      years, this selects the calendar's year.

  %dth  The day of the month as an ordinal number, 1st, 2nd, 3rd, etc.
  %mth  The month of the year as an ordinal number, 1st, 2nd, 3rd, etc.

  %db The business day of the month (since last month's ultimo)
  %dB Number of business days until this month's ultimo

   Time specs:
  %H  The hour of the day using a 24h clock, 2 digits (range 00 to 23)
  %I  The hour of the day using a 12h clock, 2 digits (range 01 to 12)
  %M  The minute (range 00 to 59)
  %N  The nanoseconds (range 000000000 to 999999999)
  %p  The string AM or PM, noon is PM and midnight is AM.
  %P  Like %p but in lowercase
  %S  The second (range 00 to 60, 60 is for leap seconds)
  %T  Equivalent to %H:%M:%S

   General specs:
  %n  A newline character
  %t  A tab character
  %%  A literal % character

   Modifiers:
  %O  Modifier to turn decimal numbers into Roman numerals
  %r  Modifier to turn units into real units
  %0  Modifier to turn on zero prefixes
  %SPC  Modifier to turn on space prefixes
  %-  Modifier to turn off prefixes altogether
  th  Suffix, read and print ordinal numbers
  b   Suffix, treat days as business days

   By design dates before 1601-01-01 are not supported.

   For conformity here is a list of calendar designators and their
corresponding format string:
  ymd     %Y-%m-%d
  ymcw    %Y-%m-%c-%w
  ywd     %rY-W%V-%u
  bizda   %Y-%m-%db
  lilian     n/a
  ldn        n/a
  julian     n/a
  jdn        n/a
  matlab     n/a
  mdn        n/a

   These designators can be used as output format string, moreover,
'lilian'/'ldn' and 'julian'/'jdn' can also be used as input format
string.

3.2 Format specs for durations
==============================

Unlike time or absolute instants, durations are reference-free, i.e.
the reference instant is not part of the duration.  As a result
durations cannot be named, i.e.  there is no naming scheme that applies
to all durations and all references unambiguously.

   Consequently, none of the format specifiers for date/times makes
sense for durations in the literal sense.  However, to aid intuitive
usage we reused format specifiers when they represent integral values
and a valid unit for duration, as follows:

   Date specs:
  %c  Equivalent to %w
  %d  Duration in days
  %F  Equivalent to %dd with no resorting to bigger units
  %m  Duration in months
  %w  Duration in weeks
  %y  Equivalent to %Y
  %Y  Duration in years

  %db Duration in business days
  %dB Equivalent to %db

   Time specs:
  %H  Duration in hours
  %I  Equivalent to %H
  %M  Duration in minutes
  %S  Duration in seconds
  %T  Equivalent to %Ss without resorting to bigger units

  %rS Duration in real-life seconds, as in including leap seconds
  %rT Equivalent to %rSs without resorting to bigger units

   General specs:
  %n  A newline character
  %t  A tab character
  %%  A literal % character

   Modifiers:
  %r    Modifier to turn units into real units
  %0    Modifier to pad refined values with zeroes
  %SPC  Modifier to pad refined values with spaces
  b     Suffix, treat days as business days

3.3 The refinement rule
=======================

Durations are somewhat ambiguous when it comes to representing them
through format specifiers.  Unlike format specifiers in point-in-time
representations duration specifiers can have an intra-line relationship.

   So for instance a duration of 128 seconds might be presented through
'%S' as '128' but similarly through '%M:%S' as '02:08' (read two minutes
and 8 seconds).

   There are several approaches to deal with this ambiguity.  The ddiff
tool will follow, what we call, the refinement rule.  That is,
regardless of the position of a format specifier, if it is a valid
/refinement/ of another specifier in the format string, then it will
only show the fractional value, i.e.  the value in its natural range
with respect to the /refined/ specifier.

  %Y  possible refinements: %m, %w, %d
  %m  possible refinements: %w, %d
  %w  possible refinements: %d
  %d  possible refinements: %H, %M, %S
  %H  possible refinements: %M, %S
  %M  possible refinements: %S

   The refinement alternatives are listed in order of precedence and
they are mutually exclusive.  I.e.  it is not possible to express a
duration in months and hours without having a '%d' specifier as well.
On the other hand in a chain of refinements inner elements are optional,
i.e.  you can express a duration in weeks and hours because every day
has 24 hours and hence there are 168 hours in a week.

   In case of negative durations (the minuend is in the future relative
to the subtrahend) only the largest unit will carry the minus sign.

   Using the refinement rule keeps the format string dead simple,
there's no need for operators or a full-blown language to distinguish
the range ambiguity, which then would have to be escaped because they
could also in theory be part of the literal characters of the format
string, resulting more often than not in command lines that are hard to
craft and even harder to understand later on (e.g.  if used in shell
scripts).

   The refinement rule ingeniously covers the 99% case but, unlike other
approaches, there's no way to display two unrefined values in the same
format string, e.g.  ''%w weeks (which is %d days)''.

3.4 Specifying durations
========================

Some tools ('dadd', 'dseq') need durations as their input.  Durations
are generally incompatible with input formats as specified by
'-i|--input-format' and (at the moment) the input syntax is fixed.

   The general format is '[+-]Nunit' where '+' or '-' is the sign, 'N' a
number, and 'unit' the unit as discussed below.

   Units:
  s  seconds
  m  minutes
  h  hours
  rs real-life seconds, as in including leap second transitions

  d  days
  b  business days
  mo months
  y  years

   For historical reasons, we used to accept 'm' in the context of
date-only input as a qualifier for months.  As of 0.4.4, this is no
longer the case.


File: dateutils.info,  Node: Localised input and output,  Next: Algorithms,  Prev: Format specifiers and units,  Up: Top

4 Localised input and output
****************************

Input and output may need to be refined even beyond what simple format
specifiers can accomplish, for example time zone information might not
be present in the input (or must not be present in the output); or using
named weekdays ('%a', '%A') or months ('%b', '%B') depending on region
and language.

   We present dateutils' solution in the next 2 sections.

4.1 Time zones and mappings
===========================

All tools of the dateutils suite support '--from-zone=ZONE' to globally
declare that date/time input is expressed in ZONE.

   Tools that output absolute date/times also allow '--zone=ZONE' to
globally declare that date/time output is to be converted into ZONE.

   When input or output zones are omitted dates and timestamps are
treated as coming from the special (built-in) timezone UTC.

   Due to the complexity in setting up and maintaining timezone
reference data, we decided to depart from our usual course and depend on
the system's zoneinfo database.  As a consequence, 'ZONE' can point to
anything in the system's zoneinfo directory which is assumed to be in
IANA format.

   Zones 'UTC', 'TAI', and 'GPS' are treated specially.  Their rules and
offsets are built-in and never read from the disk.

Timezone maps
=============

Additionally, and true to our motto not to depend on system facilities,
dateutils ships with timezone map files to map domain specific
identifiers to their IANA zoneinfo name.

   Mapped timezone identifiers generally look like 'DOMAIN:IDENTIFIER'
where 'DOMAIN.tzmap' is a file in the tzmap search path and 'IDENTIFIER'
is a valid entry therein.  In-lieu of 'ZONE' specifiers of the above
form are accepted by all tools of the dateutils suite as well.

   For more information on timezone map files, covered domains and
licence information visit <http://www.fresse.org/dateutils/tzmaps.html>.

4.2 Localised month and weekday names
=====================================

All tools of the dateutils suite support '--from-locale=LOC' to globally
declare that input with named specifiers uses names from LOC.

   Tools that output absolute date/times also allow '--locale=LOC' to
globally declare that output with named specifiers is to be expressed
using names from LOC.

   Inspired by ISO 15897, we use the 'language_TERRITORY' notation for
'LOC', the encoding is always UTF-8 and hence the encoding part in the
'LOC' notation is omitted.

   To be independent of system support locales in dateutils are provided
by the 'locale' file (shipped), a simple tab separated text file:
following the locale identifier line ('xx_XX') is the line of
abbreviated weekday names ('%a') of which there must be 7 corresponding
to Mon, Tue, ..., followed by long weekday names ('%A'), followed by
abbreviated month names ('%b') of which there must be 12 corresponding
to Jan, Feb, ..., followed last by the long month names ('%B').

   The environment variable 'LOCALE_FILE' can be used to override the
default location.


File: dateutils.info,  Node: Algorithms,  Next: dateadd,  Prev: Localised input and output,  Up: Top

5 Algorithms
************

Coming from a financial background, shaving milliseconds off of code is
daily core business.  And that in turn is why some of the algorithms
used in dateutils might look different to what other people do.

   In this chapter key concepts are briefly introduced.  For
implementation details see the '*-core.c' and '*-core.h' files.

5.1 32-adic year-days
=====================

Months, in the Gregorian sense, are roughly 30 days long.  Some are
longer, one is shorter.  It comes in handy though that the average month
length is close to a 2-power, 32.  So we can introduce a 32-adic year as
follows:

year-day        traditional     32-adic m/d
0       19      Jan|00          00|19
1       20      Jan|01          00|20
31      50      Jan|31          01|18

32      51      Feb|01          01|19
59      78      Feb|28          02|14

60      79      Mar|01          02|15
90      109     Mar|31          03|13

91      110     Apr|01          03|14
120     139     Apr|30          04|11

121     140     May|01          04|12
151     170     May|31          05|10

181     200     Jun|30          06|08
212     231     Jul|31          07|07
243     262     Aug|31          08|06
273     292     Sep|30          09|04
304     323     Oct|31          10|03
334     353     Nov|30          11|01
365     384     Dec|31          12|00

   As can be seen, the year has 19 unexplained days at the beginning,
and, more unintuitively, (traditional) months start in one (32-adic)
month and end in another.  But the ending always coincides with the
traditional months.

   Another nice thing about this year is that all months end on a
different day; this is nice because you can deduce the month just by
naming its ending (or the beginning respectively, as all months as a
consequence also start on a different day).

   The final nice thing lies in the property, that months that end (or
start) on a day <=16, are affected by the leap day introduced in Feb in
the traditional Gregorian calendar.  By affected we mean, that the
months start (and end) one day off in a leap year.

   So to cut this story short, the 32-adic year makes computations
easier that need a lot of mapping between the day in the year and the
month+day representation, e.g.  weekday computations (the 32-adic year
preserves weekdays as 32 and 7 are co-prime), day differences, etc.

   The algorithm to get the day of the year from a 32-adic month+day is:
Input: m <- 32-adic month
       d <- 32-adic day of month
Output: yd -> day of year

yd <- m * 32 + d - 19

   And conversely.  The algorithm to get the 32-adic month+day is
trivial.

   To convert between 32-adic month+day and Gregorian month+day:
Input: m <- 32-adic month
       d <- 32-adic day of month
Output: m -> 32-adic month
        d -> 32-adic day of month

/* day of month of the beginning and end of m */
bom <- get_beg_of_month(m)
eom <- get_end_of_month(m)

/* get yd as described above */
yd <- get_yd(m, d)

if d <= eom
        d <- yd - (32 * (m - 1) - 19 + bom - 1)
else
        d <- yd - (32 * m - 19 + eom)
        m <- m + 1


File: dateutils.info,  Node: dateadd,  Next: dateconv,  Prev: Algorithms,  Up: Top

6 dateadd
*********

'dateadd' may be invoked with the following command-line options:

Usage: dateadd [OPTION]... [DATE/TIME] [DURATION]

Add DURATION to DATE/TIME and print the result.
If DATE/TIME is omitted but DURATION is given, read a list of DATE/TIMEs from
stdin.
If DURATION is omitted but DATE/TIME is given, read a list of DURATIONs from
stdin.

Durations are specified as nY, nMO, nW, or nD for years, months, weeks, or days
respectively, or nH, nM, nS for hours, minutes, and seconds, where N is a
(possibly negative) number.  The unit symbols can be written lower-case as well
(y, mo, w, d, h, m, s) and the unit symbol `d' can be omitted.

Note that duration addition is not commutative!
  2000-03-30 +1mo +1d -> 2000-05-01
  2000-03-30 +1d +1mo -> 2000-04-30

  -h, --help            Print help and exit
  -V, --version         Print version and exit
  -q, --quiet           Suppress message about date/time and duration
                        parser errors and fix-ups.
                        The default is to print a warning or the
                        fixed up value and return error code 2.
  -f, --format=STRING   Output format.  This can either be a specifier
                        string (similar to strftime()'s FMT) or the name
                        of a calendar.
  -i, --input-format=STRING...
                        Input format, can be used multiple times.
                        Each date/time will be passed to the input
                        format parsers in the order they are given, if a
                        date/time can be read successfully with a given
                        input format specifier string, that value will
                        be used.
  -b, --base=DT         For underspecified input use DT as a fallback to
                        fill in missing fields.  Also used for ambiguous
                        format specifiers to position their range on the
                        absolute time line.
                        Must be a date/time in ISO8601 format.
                        If omitted defaults to the current date/time.
  -e, --backslash-escapes
                        Enable interpretation of backslash escapes in the
                        output and input format specifier strings.
  -S, --sed-mode        Copy parts from the input before and after a
                        matching date/time.
                        Note that all occurrences of date/times within a
                        line will be processed.
  -E, --empty-mode      Empty lines that cannot be parsed.
      --locale=LOCALE   Format results according to LOCALE, this would only
                        affect month and weekday names.
      --from-locale=LOCALE
                        Interpret dates on stdin or the command line as
                        coming from the locale LOCALE, this would only
                        affect month and weekday names as input formats
                        have to be specified explicitly.
      --from-zone=ZONE  Interpret dates on stdin or the command line as
                        coming from the time zone ZONE.
  -z, --zone=ZONE       Convert dates printed on stdout to time zone ZONE,
                        default: UTC.


Report bugs to https://github.com/hroptatyr/dateutils/issues

6.1 Examples
============

     $ dateadd 2012-03-01 1d
     2012-03-02
     $

     $ dateadd 2012-03-01 1mo
     2012-04-01
     $

     $ dateadd 2012-03-31 1mo
     2012-04-30
     $

     $ dateadd 2w2d <<EOF
     2012-03-01
     2012-03-02
     2012-03-04
     2012-03-08
     2012-03-16
     EOF
     2012-03-17
     2012-03-18
     2012-03-20
     2012-03-24
     2012-04-01
     $

     $ dateadd 10:01:00 1h6m
     11:07:00
     $

     $ dateadd 10:01:00 -1h6m
     08:55:00
     $

     $ dateadd 10:01:00 3605s
     11:01:05
     $


File: dateutils.info,  Node: dateconv,  Next: datediff,  Prev: dateadd,  Up: Top

7 dateconv
**********

'dateconv' may be invoked with the following command-line options:

Usage: dateconv [OPTION]... [DATE/TIME]...

Convert DATE/TIMEs between calendrical systems.
If DATE/TIME is omitted date/times are read from stdin.

DATE/TIME can also be one of the following specials
  - `now'           interpreted as the current (UTC) time stamp
  - `time'          the time part of the current (UTC) time stamp
  - `today'         the current date (according to UTC)
  - `tomo[rrow]'    tomorrow's date (according to UTC)
  - `y[ester]day'   yesterday's date (according to UTC)

  -h, --help            Print help and exit
  -V, --version         Print version and exit
  -q, --quiet           Suppress message about date/time and duration
                        parser errors and fix-ups.
                        The default is to print a warning or the
                        fixed up value and return error code 2.
  -f, --format=STRING   Output format.  This can either be a specifier
                        string (similar to strftime()'s FMT) or the name
                        of a calendar.
  -i, --input-format=STRING...
                        Input format, can be used multiple times.
                        Each date/time will be passed to the input
                        format parsers in the order they are given, if a
                        date/time can be read successfully with a given
                        input format specifier string, that value will
                        be used.
  -b, --base=DT         For underspecified input use DT as a fallback to
                        fill in missing fields.  Also used for ambiguous
                        format specifiers to position their range on the
                        absolute time line.
                        Must be a date/time in ISO8601 format.
                        If omitted defaults to the current date/time.
  -e, --backslash-escapes
                        Enable interpretation of backslash escapes in the
                        output and input format specifier strings.
  -S, --sed-mode        Copy parts from the input before and after a
                        matching date/time.
                        Note that all occurrences of date/times within a
                        line will be processed.
  -E, --empty-mode      Empty lines that cannot be parsed.
      --locale=LOCALE   Format results according to LOCALE, this would only
                        affect month and weekday names.
      --from-locale=LOCALE
                        Interpret dates on stdin or the command line as
                        coming from the locale LOCALE, this would only
                        affect month and weekday names as input formats
                        have to be specified explicitly.
      --from-zone=ZONE  Interpret dates on stdin or the command line as
                        coming from the time zone ZONE.
  -z, --zone=ZONE       Convert dates printed on stdout to time zone ZONE,
                        default: UTC.


Report bugs to https://github.com/hroptatyr/dateutils/issues

7.1 Examples
============

     $ dateconv 2012-03-01
     2012-03-01
     $

     $ dateconv -i "%d/%b/%y" 01/Mar/12
     2012-03-01
     $

     $ dateconv -f "%d/%b/%y" 2012-03-01
     01/Mar/12
     $

     $ dateconv -f "%d/%b/%y" -i "%OY %Om %Od" "MCMXCVIII IX XVII"
     17/Sep/98
     $

     $ dateconv 12:03:01
     12:03:01
     $

     $ dateconv -i "%I:%M:%S %p" "11:22:33 PM"
     23:22:33
     $

     $ dateconv '2012-03-01 00:00:00'
     2012-03-01T00:00:00
     $

     $ dateconv 2012-03-01T12:34:56
     2012-03-01T12:34:56
     $

     $ dateconv --zone America/Chicago <<EOF
     2012-03-01T07:05:06
     2012-03-01T08:12:34
     2012-03-11T01:05:06
     2012-03-11T02:05:06
     2012-03-11T07:05:06
     2012-03-11T08:05:06
     2012-03-11T17:05:06
     EOF
     2012-03-01T01:05:06
     2012-03-01T02:12:34
     2012-03-10T19:05:06
     2012-03-10T20:05:06
     2012-03-11T01:05:06
     2012-03-11T03:05:06
     2012-03-11T12:05:06
     $

     $ dateconv --from-zone America/Chicago <<EOF
     2012-03-01T01:05:06
     2012-03-01T02:12:34
     2012-03-10T19:05:06
     2012-03-10T20:05:06
     2012-03-11T01:05:06
     2012-03-11T03:05:06
     2012-03-11T12:05:06
     EOF
     2012-03-01T07:05:06
     2012-03-01T08:12:34
     2012-03-11T01:05:06
     2012-03-11T02:05:06
     2012-03-11T07:05:06
     2012-03-11T08:05:06
     2012-03-11T17:05:06
     $

     $ dateconv --from-zone America/Chicago -z Europe/Berlin '2012-03-01 12:00' -i '%F %H:%M' -f '%F %T'
     2012-03-01 19:00:00
     $


File: dateutils.info,  Node: datediff,  Next: dategrep,  Prev: dateconv,  Up: Top

8 datediff
**********

'datediff' may be invoked with the following command-line options:

Usage: datediff [OPTION]... DATE/TIME [DATE/TIME]...

Compute duration from DATE/TIME (the reference date/time) to the other
DATE/TIMEs given and print the result as duration.
If the other DATE/TIMEs are omitted read them from stdin.

DATE/TIME can also be one of the following specials
  - `now'           interpreted as the current (UTC) time stamp
  - `time'          the time part of the current (UTC) time stamp
  - `today'         the current date (according to UTC)
  - `tomo[rrow]'    tomorrow's date (according to UTC)
  - `y[ester]day'   yesterday's date (according to UTC)

Note: The output format of durations (specified via -f) takes all format
specifiers into account, i.e. specifying %M and %S for example prints the
duration in minutes and seconds, whereas specifying %S only prints the duration
in seconds.

See section `The refinement rule' in datediff(1).

  -h, --help            Print help and exit
  -V, --version         Print version and exit
  -q, --quiet           Suppress message about date/time and duration
                        parser errors and fix-ups.
                        The default is to print a warning or the
                        fixed up value and return error code 2.
                        Also see -S|--skip-illegal to output an empty
                        line instead of leaving out the line altogether.
  -S, --skip-illegal    Deprecated, use -E|--empty-mode.
  -E, --empty-mode      Output empty lines as placeholder for illegal
                        input, i.e. parser errors or date/times that
                        cannot be subtracted.
  -f, --format=STRING   Output format.  This can either be a specifier
                        string (similar to strftime()'s FMT) or the name
                        of a calendar.
  -i, --input-format=STRING...
                        Input format, can be used multiple times.
                        Each date/time will be passed to the input
                        format parsers in the order they are given, if a
                        date/time can be read successfully with a given
                        input format specifier string, that value will
                        be used.
  -b, --base=DT         For underspecified input use DT as a fallback to
                        fill in missing fields.  Also used for ambiguous
                        format specifiers to position their range on the
                        absolute time line.
                        Must be a date/time in ISO8601 format.
                        If omitted defaults to the current date/time.
  -e, --backslash-escapes
                        Enable interpretation of backslash escapes in the
                        output and input format specifier strings.
      --from-locale=LOCALE
                        Interpret dates on stdin or the command line as
                        coming from the locale LOCALE, this would only
                        affect month and weekday names as input formats
                        have to be specified explicitly.
      --from-zone=ZONE  Interpret dates on stdin or the command line as
                        coming from the time zone ZONE.


Report bugs to https://github.com/hroptatyr/dateutils/issues

8.1 Examples
============

     $ datediff 2012-03-02 2012-03-02
     0
     $

     $ datediff 2012-03-02 2012-03-12
     10
     $

     $ datediff 2012-03-02 2012-04-12
     41
     $

     $ datediff 2012-03-12 2012-04-02
     21
     $

     $ datediff 2012-04-02 2012-03-12
     -21
     $

     $ datediff 2012-01-02 2012-02-29 -f '%dd'
     58d
     $

     $ datediff 2012-01-02 2012-02-29 -f '%ww %dd'
     8w 2d
     $

     $ datediff 10:00:00 10:00:00
     0s
     $

     $ datediff 10:01:00 10:06:00
     300s
     $

     $ datediff 10:06:00 10:01:00
     -300s
     $

     $ datediff 10:01:00 11:03:10 -f '%S sec'
     3730 sec
     $

     $ datediff 10:01:00 11:03:10 -f '%Mm %Ss'
     62m 10s
     $

     $ datediff 10:01:00 11:03:10 -f '%H:%M:%S'
     1:2:10
     $

     $ datediff 2012-03-02T10:04:00 2012-03-02T10:14:00
     600s
     $

     $ datediff 2012-03-02T10:04:00 2012-03-02T10:14:00 -f '%M min'
     10 min
     $

     $ datediff 2012-03-01T12:17:00 2012-03-02T14:00:00
     92580s
     $

     $ datediff 2012-03-01T12:17:00 2012-03-02T14:00:00 -f '%d days and %S seconds'
     1 days and 6180 seconds
     $


File: dateutils.info,  Node: dategrep,  Next: dateround,  Prev: datediff,  Up: Top

9 dategrep
**********

'dategrep' may be invoked with the following command-line options:

Usage: dategrep [OPTION]... EXPRESSION

Grep standard input for lines that match EXPRESSION.

EXPRESSION may be date/times prefixed with an operator `<', `<=', `=', `>=',
`>', `!=', `<>' (if omitted defaults to `='),
which will match lines with date/times which are older, older-equal, equal,
newer-equal, newer, or not equal respectively.

EXPRESSION may also be format specifiers infixed by above operators
and suffixed by a value (e.g. `%a="Wed"') which matches lines whose
%a representation (weekday name abbreviated) is "Wed".

EXPRESSION may be statements as described above concatenated through `&&' (for
conjunction) or `||' (disjunction), both of which may be parenthesised as per
usual to change precedence (`&&' goes over `||').

If multiple date/times occur on the same line and any one of them fulfills the
criteria then the line is considered a match and will be output.

Note:
  Operations can be specified by options (--eq, --gt, ...) as well.
  This serves solely as a means of convenience, e.g. the datetest tool has a
  similar syntax.

  -h, --help            Print help and exit
  -V, --version         Print version and exit
  -q, --quiet           Suppress message about date/time and duration
                        parser errors.
  -i, --input-format=STRING...
                        Input format, can be used multiple times.
                        Each date/time will be passed to the input
                        format parsers in the order they are given, if a
                        date/time can be read successfully with a given
                        input format specifier string, that value will
                        be used.
  -b, --base=DT         For underspecified input use DT as a fallback to
                        fill in missing fields.  Also used for ambiguous
                        format specifiers to position their range on the
                        absolute time line.
                        Must be a date/time in ISO8601 format.
                        If omitted defaults to the current date/time.
  -e, --backslash-escapes
                        Enable interpretation of backslash escapes in the
                        output and input format specifier strings.
  -o, --only-matching   Show only the part of a line matching DATE.
  -v, --invert-match    Select non-matching lines.
      --from-locale=LOCALE
                        Interpret dates on stdin or the command line as
                        coming from the locale LOCALE, this would only
                        affect month and weekday names as input formats
                        have to be specified explicitly.
      --from-zone=ZONE  Consider date/times on stdin as coming from the
                        zone ZONE, default: UTC.
  -z, --zone=ZONE       Consider date/times in EXPRESSION as coming from
                        the zone ZONE, default: UTC.
      --eq              Lines match when date/times are equal to
                        EXPRESSION.
      --ne              Lines match when date/times are not the same as
                        EXPRESSION.
      --gt              Lines match when date/times are newer than
                        EXPRESSION.
      --lt              Lines match when date/times are older than
                        EXPRESSION.
      --ge              Lines match when date/times are newer than or
                        equal EXPRESSION.
      --le              Lines match when date/times are older than or
                        equal EXPRESSION.
      --nt              Lines match when date/times are newer than or
                        equal EXPRESSION.
      --ot              Lines match when date/times are older than or
                        equal EXPRESSION.


Report bugs to https://github.com/hroptatyr/dateutils/issues

9.1 Examples
============

     $ dategrep 2012-03-01 <<EOF
     2012-02-28
     2012-02-29
     2012-03-01
     2012-03-02
     EOF
     2012-03-01
     $

     $ dategrep '<2012-03-01' <<EOF
     2012-02-28
     2012-02-29
     2012-03-01
     2012-03-02
     EOF
     2012-02-28
     2012-02-29
     $

     $ dategrep \!=2012-03-01 <<EOF
     2012-02-28
     2012-02-29
     2012-03-01
     2012-03-02
     EOF
     2012-02-28
     2012-02-29
     2012-03-02
     $

     $ dategrep =2012-03-01 <<EOF
     Feb	2012-02-28
     Feb	2012-02-29	leap day
     Mar	2012-03-01
     Mar	2012-03-02
     EOF
     Mar	2012-03-01
     $

     $ dategrep -o \<2012-03-01 <<EOF
     Feb	2012-02-28
     Feb	2012-02-29	leap day
     Mar	2012-03-01
     Mar	2012-03-02
     EOF
     2012-02-28
     2012-02-29
     $

     $ dategrep '>=12:00:00' <<EOF
     fileA	11:59:58
     fileB	11:59:59	leap second?
     fileNOON	12:00:00	new version
     fileC	12:03:12
     EOF
     fileNOON	12:00:00	new version
     fileC	12:03:12
     $

     $ dategrep -o '>=12:00:00' <<EOF
     fileA	11:59:58
     fileB	11:59:59	leap second?
     fileNOON	12:00:00	new version
     fileC	12:03:12
     EOF
     12:00:00
     12:03:12
     $

     $ dategrep 2012-03-01 <<EOF
     2012-02-28T10:00:00
     2012-02-29T10:00:00
     2012-03-01T10:00:00
     2012-03-02T10:00:00
     EOF
     2012-03-01T10:00:00
     $

     $ dategrep '<2012-03-01' <<EOF
     2012-02-28T10:00:00
     2012-02-29T10:00:00
     2012-03-01T10:00:00
     2012-03-02T10:00:00
     EOF
     2012-02-28T10:00:00
     2012-02-29T10:00:00
     $

     $ dategrep 2012-03-01T10:00:00 <<EOF
     2012-02-28T10:00:00
     2012-02-29T10:00:00
     2012-03-01T10:00:00
     2012-03-02T10:00:00
     EOF
     2012-03-01T10:00:00
     $

     $ dategrep '<2012-03-01T14:00:00' <<EOF
     2012-02-28T10:00:00
     2012-02-29T10:00:00
     2012-03-01T10:00:00
     2012-03-02T10:00:00
     EOF
     2012-02-28T10:00:00
     2012-02-29T10:00:00
     2012-03-01T10:00:00
     $


File: dateutils.info,  Node: dateround,  Next: dateseq,  Prev: dategrep,  Up: Top

10 dateround
************

'dateround' may be invoked with the following command-line options:

Usage: dateround [OPTION]... [DATE/TIME] RNDSPEC...

Round DATE/TIME to the next occurrence of RNDSPEC.

If DATE/TIME is omitted a stream of date/times is read from stdin.

DATE/TIME can also be one of the following specials
  - `now'           interpreted as the current (UTC) time stamp
  - `time'          the time part of the current (UTC) time stamp
  - `today'         the current date (according to UTC)
  - `tomo[rrow]'    tomorrow's date (according to UTC)
  - `y[ester]day'   yesterday's date (according to UTC)

1. RNDSPECs can be month names (Jan, Feb, ...), weekday names (Sun, Mon, ...),
   numerals suffixed with y, q, mo, d, bd, h, m, or s, possibly prefixed with
   a dash (`-`) to indicate the rounding direction is downwards.

2. Suffixed RNDSPECs may additionally be prefixed with a slash (`/`) to
   indicate that rounding to a multiple of RNDSPEC is desired.
   Co-class rounding.

In the first case, rounding affects the named element in the specified date
or date/time and more significant elements by setting this element to the
specified value and adjusting the more significant elements such that the
result is greater (younger) or equal to the input (or strictly greater when
-n|--next is given) for positive values, and less (older) or equal (unless
-n|--next is given) for named elements that are prefixed with dash (`-`).
In either case, less significant elements, e.g. subdivisions of the named
element and their subdivisions are left unchanged.

    That is     dateround 2019-01-28T12:04:00 +6
    will yield  2019-02-06T12:04:00

    Similarly   dateround -n 2019-01-28T12:04:00 -- -Oct
    will yield  2018-10-28T12:04:00

In the second case, rounding is more like rounding decimal fractions to
negative infinity.  The time axis is partitioned by multiples of the named
element, and the oldest date or datetime is returned that is greater (younger)
(or equal if -n|--next is omitted) than the specified date or date/time,
when rounding down (`-` prefix) the oldest date or datetime is returned
that is less (older) than the specified date or datetime.

    That is     dateround 2019-01-28T12:04:00 /1y
    will yield  2020-01-01T00:00:00

    Similarly   dateround 2019-01-28T12:04:00 /-30m
    will yield  2019-01-28T12:00:00

The superdivision of years are millennia, i.e. there's 1000 years,
500 biennia, 100 decades, etc. in a millenium.

Multiple RNDSPECs are evaluated left to right.

Note that rounding isn't commutative, e.g.
	dateround 2012-03-01 Sat Sep -> 2012-09-03
vs.
	dateround 2012-03-01 Sep Sat -> 2012-09-01

Note that non-numeric strings prefixed with a `-' conflict with the command
line options and a separating `--' has to be used.

  -h, --help            Print help and exit
  -V, --version         Print version and exit
  -q, --quiet           Suppress message about date/time and duration
                        parser errors and fix-ups.
                        The default is to print a warning or the
                        fixed up value and return error code 2.
  -f, --format=STRING   Output format.  This can either be a specifier
                        string (similar to strftime()'s FMT) or the name
                        of a calendar.
  -i, --input-format=STRING...
                        Input format, can be used multiple times.
                        Each date/time will be passed to the input
                        format parsers in the order they are given, if a
                        date/time can be read successfully with a given
                        input format specifier string, that value will
                        be used.
  -b, --base=DT         For underspecified input use DT as a fallback to
                        fill in missing fields.  Also used for ambiguous
                        format specifiers to position their range on the
                        absolute time line.
                        Must be a date/time in ISO8601 format.
                        If omitted defaults to the current date/time.
  -e, --backslash-escapes
                        Enable interpretation of backslash escapes in the
                        output and input format specifier strings.
  -S, --sed-mode        Copy parts from the input before and after a
                        matching date/time.
                        Note that all occurrences of date/times within a
                        line will be processed.
  -E, --empty-mode      Empty lines that cannot be parsed.
      --locale=LOCALE   Format results according to LOCALE, this would only
                        affect month and weekday names.
      --from-locale=LOCALE
                        Interpret dates on stdin or the command line as
                        coming from the locale LOCALE, this would only
                        affect month and weekday names as input formats
                        have to be specified explicitly.
      --from-zone=ZONE  Interpret dates on stdin or the command line as
                        coming from the time zone ZONE.
  -z, --zone=ZONE       Convert dates printed on stdout to time zone ZONE,
                        default: UTC.
  -n, --next            Always round to a different date or time.


Report bugs to https://github.com/hroptatyr/dateutils/issues

10.1 Examples
=============

     $ dateround 2012-03-01 2
     2012-03-02
     $

     $ dateround -n 2012-03-01 1
     2012-04-01
     $

     $ dateround 17:05:00 5m
     17:05:00
     $ dateround 17:04:00 /5m
     17:05:00
     $

     $ dateround -n 17:04:00 4m
     18:04:00
     $ dateround -n 17:04:00 /1m
     17:05:00
     $


File: dateutils.info,  Node: dateseq,  Next: datesort,  Prev: dateround,  Up: Top

11 dateseq
**********

'dateseq' may be invoked with the following command-line options:

Usage: dateseq [OPTION]... FIRST [[INCREMENT] LAST]

Generate a sequence of date/times from FIRST to LAST, optionally in steps of
INCREMENT (which defaults to `1d').

If LAST is omitted it defaults to `now' if FIRST is a date/time, or `today' if
FIRST is a date, or `time' if FIRST is a time.

The values of FIRST and LAST are always inclusive and no date/times before
FIRST and no date/times after LAST will be printed.

Negative INCREMENTs must be given, i.e. if FIRST is newer than LAST.

  -h, --help            Print help and exit
  -V, --version         Print version and exit
  -q, --quiet           Suppress message about date/time and duration
                        parser errors and fix-ups.
                        The default is to print a warning or the
                        fixed up value and return error code 2.
  -f, --format=STRING   Output format.  This can either be a specifier
                        string (similar to strftime()'s FMT) or the name
                        of a calendar.
  -i, --input-format=STRING...
                        Input format, can be used multiple times.
                        Each date/time will be passed to the input
                        format parsers in the order they are given, if a
                        date/time can be read successfully with a given
                        input format specifier string, that value will
                        be used.
  -b, --base=DT         For underspecified input use DT as a fallback to
                        fill in missing fields.  Also used for ambiguous
                        format specifiers to position their range on the
                        absolute time line.
                        Must be a date/time in ISO8601 format.
                        If omitted defaults to the current date/time.
  -e, --backslash-escapes
                        Enable interpretation of backslash escapes in the
                        output and input format specifier strings.
      --locale=LOCALE   Format results according to LOCALE, this would only
                        affect month and weekday names.
      --from-locale=LOCALE
                        Interpret dates on stdin or the command line as
                        coming from the locale LOCALE, this would only
                        affect month and weekday names as input formats
                        have to be specified explicitly.
  -s, --skip=STRING...  Skip weekdays specified by STRING.
                        STRING can be a single weekday (Mon, Tue, etc.),
                        and to skip several days the --skip option can
                        be used multiple times.
                        STRING can also be a comma-separated list of
                        weekday names, or `ss' to skip weekends
                        (sat+sun) altogether.
                        STRING can also contain date ranges like `mo-we'
                        for monday to wednesday.
      --alt-inc=STRING  Alternative increment to use when a date is hit
                        that is skipped as per --skip.
                        This increment will be applied until a
                        non-skipped date is reached.
                        The special case `0' (default) deactivates
                        alternative incrementing.  A useful value could
                        be `1d' for increasing sequences and `-1d' for
                        decreasing sequences, so if a skipped date is
                        encountered the next non-skipped date
                        after/before will be used.
      --compute-from-last
                        Compute a start value from LAST using INCREMENT.
                        This option has an effect only when INCREMENT is
                        not a divisor of the duration between FIRST and
                        LAST.  In such case, an alternative FIRST will
                        be computed by consecutively subtracting
                        INCREMENT from LAST until FIRST is hit or
                        crossed.


Report bugs to https://github.com/hroptatyr/dateutils/issues

11.1 Examples
=============

     $ dateseq 2012-02-01 2012-03-01
     2012-02-01
     2012-02-02
     2012-02-03
     2012-02-04
     2012-02-05
     2012-02-06
     2012-02-07
     2012-02-08
     2012-02-09
     2012-02-10
     2012-02-11
     2012-02-12
     2012-02-13
     2012-02-14
     2012-02-15
     2012-02-16
     2012-02-17
     2012-02-18
     2012-02-19
     2012-02-20
     2012-02-21
     2012-02-22
     2012-02-23
     2012-02-24
     2012-02-25
     2012-02-26
     2012-02-27
     2012-02-28
     2012-02-29
     2012-03-01
     $

     $ dateseq 2001-02-03 2001-03-03 --skip sat -f "%F %a"
     2001-02-04 Sun
     2001-02-05 Mon
     2001-02-06 Tue
     2001-02-07 Wed
     2001-02-08 Thu
     2001-02-09 Fri
     2001-02-11 Sun
     2001-02-12 Mon
     2001-02-13 Tue
     2001-02-14 Wed
     2001-02-15 Thu
     2001-02-16 Fri
     2001-02-18 Sun
     2001-02-19 Mon
     2001-02-20 Tue
     2001-02-21 Wed
     2001-02-22 Thu
     2001-02-23 Fri
     2001-02-25 Sun
     2001-02-26 Mon
     2001-02-27 Tue
     2001-02-28 Wed
     2001-03-01 Thu
     2001-03-02 Fri
     $

     $ dateseq --compute-from-last 2001-02-03 1 2001-03-03 --skip sat -f "%F %a"
     2001-02-04 Sun
     2001-02-05 Mon
     2001-02-06 Tue
     2001-02-07 Wed
     2001-02-08 Thu
     2001-02-09 Fri
     2001-02-11 Sun
     2001-02-12 Mon
     2001-02-13 Tue
     2001-02-14 Wed
     2001-02-15 Thu
     2001-02-16 Fri
     2001-02-18 Sun
     2001-02-19 Mon
     2001-02-20 Tue
     2001-02-21 Wed
     2001-02-22 Thu
     2001-02-23 Fri
     2001-02-25 Sun
     2001-02-26 Mon
     2001-02-27 Tue
     2001-02-28 Wed
     2001-03-01 Thu
     2001-03-02 Fri
     $

     $ dateseq 2001-02-03 3 2001-03-03 --skip sat,fri -f "%F %a"
     2001-02-06 Tue
     2001-02-12 Mon
     2001-02-15 Thu
     2001-02-18 Sun
     2001-02-21 Wed
     2001-02-27 Tue
     $

     $ dateseq --compute-from-last 2001-02-03 3 2001-03-03 --skip sat,fri -f "%F %a"
     2001-02-04 Sun
     2001-02-07 Wed
     2001-02-13 Tue
     2001-02-19 Mon
     2001-02-22 Thu
     2001-02-25 Sun
     2001-02-28 Wed
     $

     $ dateseq 2001-02-05 4 2001-03-04 -f "%F %a"
     2001-02-05 Mon
     2001-02-09 Fri
     2001-02-13 Tue
     2001-02-17 Sat
     2001-02-21 Wed
     2001-02-25 Sun
     2001-03-01 Thu
     $

     $ dateseq --compute-from-last 2001-02-05 4 2001-03-04 -f "%F %a"
     2001-02-08 Thu
     2001-02-12 Mon
     2001-02-16 Fri
     2001-02-20 Tue
     2001-02-24 Sat
     2001-02-28 Wed
     2001-03-04 Sun
     $

     $ dateseq --alt-inc 1d 2001-02-03 3 2001-03-03 --skip sat,fri -f "%F %a"
     2001-02-04 Sun
     2001-02-07 Wed
     2001-02-11 Sun
     2001-02-14 Wed
     2001-02-18 Sun
     2001-02-21 Wed
     2001-02-25 Sun
     2001-02-28 Wed
     $

     $ dateseq --compute-from-last --alt-inc 1d 2001-02-03 3 2001-03-03 --skip sat,fri -f "%F %a"
     2001-02-04 Sun
     2001-02-07 Wed
     2001-02-11 Sun
     2001-02-14 Wed
     2001-02-18 Sun
     2001-02-21 Wed
     2001-02-25 Sun
     2001-02-28 Wed
     $

     $ dateseq 2001-01-01 2d 2001-01-08
     2001-01-01
     2001-01-03
     2001-01-05
     2001-01-07
     $

     $ dateseq --compute-from-last 2001-01-01 2d 2001-01-08
     2001-01-02
     2001-01-04
     2001-01-06
     2001-01-08
     $

     $ dateseq 2001-01-08 -2d 2001-01-01
     2001-01-08
     2001-01-06
     2001-01-04
     2001-01-02
     $

     $ dateseq --compute-from-last 2001-01-08 -2d 2001-01-01
     2001-01-07
     2001-01-05
     2001-01-03
     2001-01-01
     $

     $ dateseq 10:00:00 12m 11:20:00
     10:00:00
     10:12:00
     10:24:00
     10:36:00
     10:48:00
     11:00:00
     11:12:00
     $

     $ dateseq --compute-from-last 10:00:00 12m 11:20:00
     10:08:00
     10:20:00
     10:32:00
     10:44:00
     10:56:00
     11:08:00
     11:20:00
     $

     $ dateseq 11:20:00 -12m 10:00:00
     11:20:00
     11:08:00
     10:56:00
     10:44:00
     10:32:00
     10:20:00
     10:08:00
     $

     $ dateseq --compute-from-last 11:20:00 -12m 10:00:00
     11:12:00
     11:00:00
     10:48:00
     10:36:00
     10:24:00
     10:12:00
     10:00:00
     $


File: dateutils.info,  Node: datesort,  Next: datetest,  Prev: dateseq,  Up: Top

12 datesort
***********

'datesort' may be invoked with the following command-line options:

Usage: datesort [OPTION]... [FILE]...

Sort contents of FILE chronologically.
If FILE is omitted read from stdin.

The first date/time value per line is the sort key.  Dates without times
account for a smaller value than any date/time on the same day.  Times
without dates account for a smaller value than any date or date/time.
If a line contains no dates or times or date/times it is sorted towards
the front.

  -h, --help            Print help and exit
  -V, --version         Print version and exit
  -i, --input-format=STRING...
                        Input format, can be used multiple times.
                        Each date/time will be passed to the input
                        format parsers in the order they are given, if a
                        date/time can be read successfully with a given
                        input format specifier string, that value will
                        be used.
  -b, --base=DT         For underspecified input use DT as a fallback to
                        fill in missing fields.  Also used for ambiguous
                        format specifiers to position their range on the
                        absolute time line.
                        Must be a date/time in ISO8601 format.
                        If omitted defaults to the current date/time.
  -e, --backslash-escapes
                        Enable interpretation of backslash escapes in the
                        input format specifier strings.
      --from-locale=LOCALE
                        Interpret dates on stdin or the command line as
                        coming from the locale LOCALE, this would only
                        affect month and weekday names as input formats
                        have to be specified explicitly.
      --from-zone=ZONE  Interpret dates on stdin or the command line as
                        coming from the time zone ZONE.
  -r, --reverse         Reverse the sort order.
  -u, --unique          Print at most one line per date/time value.


Report bugs to https://github.com/hroptatyr/dateutils/issues

12.1 Examples
=============

     $ datesort < "${srcdir}/caev_01.txt"
     2009-06-03 caev="DVCA" secu="VOD" exch="XLON" xdte="2009-06-03" nett/GBX="5.2"
     2010-11-17 caev="DVCA" secu="VOD" exch="XLON" xdte="2010-11-17" nett/GBX="2.85"
     2011-11-16 caev="DVCA" secu="VOD" exch="XLON" xdte="2011-11-16" nett/GBX="3.05"
     2012-06-06 caev="DVCA" secu="VOD" exch="XLON" xdte="2012-06-06" nett/GBX="6.47"
     2013-06-12 caev="DVCA" secu="VOD" exch="XLON" xdte="2013-06-12" nett/GBX="6.92"
     2013-11-20 caev="DVCA" secu="VOD" exch="XLON" xdte="2013-11-20" nett/GBX="3.53"
     $

     $ datesort "${srcdir}/caev_01.txt"
     2009-06-03 caev="DVCA" secu="VOD" exch="XLON" xdte="2009-06-03" nett/GBX="5.2"
     2010-11-17 caev="DVCA" secu="VOD" exch="XLON" xdte="2010-11-17" nett/GBX="2.85"
     2011-11-16 caev="DVCA" secu="VOD" exch="XLON" xdte="2011-11-16" nett/GBX="3.05"
     2012-06-06 caev="DVCA" secu="VOD" exch="XLON" xdte="2012-06-06" nett/GBX="6.47"
     2013-06-12 caev="DVCA" secu="VOD" exch="XLON" xdte="2013-06-12" nett/GBX="6.92"
     2013-11-20 caev="DVCA" secu="VOD" exch="XLON" xdte="2013-11-20" nett/GBX="3.53"
     $

     $ datesort -r < "${srcdir}/caev_01.txt"
     2013-11-20 caev="DVCA" secu="VOD" exch="XLON" xdte="2013-11-20" nett/GBX="3.53"
     2013-06-12 caev="DVCA" secu="VOD" exch="XLON" xdte="2013-06-12" nett/GBX="6.92"
     2012-06-06 caev="DVCA" secu="VOD" exch="XLON" xdte="2012-06-06" nett/GBX="6.47"
     2011-11-16 caev="DVCA" secu="VOD" exch="XLON" xdte="2011-11-16" nett/GBX="3.05"
     2010-11-17 caev="DVCA" secu="VOD" exch="XLON" xdte="2010-11-17" nett/GBX="2.85"
     2009-06-03 caev="DVCA" secu="VOD" exch="XLON" xdte="2009-06-03" nett/GBX="5.2"
     $

     $ datesort -r "${srcdir}/caev_01.txt"
     2013-11-20 caev="DVCA" secu="VOD" exch="XLON" xdte="2013-11-20" nett/GBX="3.53"
     2013-06-12 caev="DVCA" secu="VOD" exch="XLON" xdte="2013-06-12" nett/GBX="6.92"
     2012-06-06 caev="DVCA" secu="VOD" exch="XLON" xdte="2012-06-06" nett/GBX="6.47"
     2011-11-16 caev="DVCA" secu="VOD" exch="XLON" xdte="2011-11-16" nett/GBX="3.05"
     2010-11-17 caev="DVCA" secu="VOD" exch="XLON" xdte="2010-11-17" nett/GBX="2.85"
     2009-06-03 caev="DVCA" secu="VOD" exch="XLON" xdte="2009-06-03" nett/GBX="5.2"
     $

     $ datesort -u < "${srcdir}/caev_02.txt"
     2009-06-03 caev="DVCA" secu="VOD" exch="XLON" xdte="2009-06-03" nett/GBX="5.2"
     2010-11-17 caev="XXXX" secu="VOD" exch="XLON" xdte="2010-11-17"
     2011-11-16 caev="DVCA" secu="VOD" exch="XLON" xdte="2011-11-16" nett/GBX="3.05"
     2012-06-06 caev="DVCA" secu="VOD" exch="XLON" xdte="2012-06-06" nett/GBX="6.47"
     2013-06-12 caev="DVCA" secu="VOD" exch="XLON" xdte="2013-06-12" nett/GBX="6.92"
     2013-11-20 caev="DVCA" secu="VOD" exch="XLON" xdte="2013-11-20" nett/GBX="3.53"
     $

     $ datesort -u "${srcdir}/caev_02.txt"
     2009-06-03 caev="DVCA" secu="VOD" exch="XLON" xdte="2009-06-03" nett/GBX="5.2"
     2010-11-17 caev="XXXX" secu="VOD" exch="XLON" xdte="2010-11-17"
     2011-11-16 caev="DVCA" secu="VOD" exch="XLON" xdte="2011-11-16" nett/GBX="3.05"
     2012-06-06 caev="DVCA" secu="VOD" exch="XLON" xdte="2012-06-06" nett/GBX="6.47"
     2013-06-12 caev="DVCA" secu="VOD" exch="XLON" xdte="2013-06-12" nett/GBX="6.92"
     2013-11-20 caev="DVCA" secu="VOD" exch="XLON" xdte="2013-11-20" nett/GBX="3.53"
     $


File: dateutils.info,  Node: datetest,  Next: datezone,  Prev: datesort,  Up: Top

13 datetest
***********

'datetest' may be invoked with the following command-line options:

Usage: datetest [OPTION]... DATE/TIME1 OP DATE/TIME2

Like test(1) but for dates.

  -h, --help            Print help and exit
  -V, --version         Print version and exit
  -q, --quiet           Suppress message about date/time and duration
                        parser errors.
  -i, --input-format=STRING...
                        Input format, can be used multiple times.
                        Each date/time will be passed to the input
                        format parsers in the order they are given, if a
                        date/time can be read successfully with a given
                        input format specifier string, that value will
                        be used.
  -b, --base=DT         For underspecified input use DT as a fallback to
                        fill in missing fields.  Also used for ambiguous
                        format specifiers to position their range on the
                        absolute time line.
                        Must be a date/time in ISO8601 format.
                        If omitted defaults to the current date/time.
      --from-locale=LOCALE
                        Interpret dates on stdin or the command line as
                        coming from the locale LOCALE, this would only
                        affect month and weekday names as input formats
                        have to be specified explicitly.
      --from-zone=ZONE  Interpret dates on stdin or the command line as
                        coming from the time zone ZONE.
  -e, --backslash-escapes
                        Enable interpretation of backslash escapes in the
                        output and input format specifier strings.
      --eq              DATE/TIME1 is the same as DATE/TIME2
      --ne              DATE/TIME1 is not the same as DATE/TIME2
      --gt              DATE/TIME1 is newer than DATE/TIME2
      --lt              DATE/TIME1 is older than DATE/TIME2
      --ge              DATE/TIME1 is newer than or equals DATE/TIME2
      --le              DATE/TIME1 is older than or equals DATE/TIME2
      --nt              DATE/TIME1 is newer than DATE/TIME2
      --ot              DATE/TIME1 is older than DATE/TIME2
      --cmp             compare DATE/TIME1 to DATE/TIME2, return with 0 if
                        equal, 1 if left argument was newer and 2 if
                        right argument was newer
      --isvalid         Return success if dates specified conform to
                        input format.


Report bugs to https://github.com/hroptatyr/dateutils/issues

13.1 Examples
=============

     $ datetest 2012-03-01 --gt 2012-03-02 || echo "false"
     false
     $

     $ datetest 2012-03-01 --ot 2012-03-02 && echo "true"
     true
     $

     $ datetest 2012-03-01 --cmp 2012-03-02; echo $?
     2
     $

     $ datetest 2012-03-02 --cmp 2012-03-02; echo $?
     0
     $

     $ datetest 2012-03-02 --cmp 2012-03-01; echo $?
     1
     $

     $ datetest 12:00:04 --gt 11:22:33 && echo "true"
     true
     $

     $ datetest 12:00:04 --lt 11:22:33 || echo "false"
     false
     $

     $ datetest 12:00:04 --cmp 11:22:33; echo "${?}"
     1
     $

     $ datetest --cmp 11:22:33 12:00:04; echo "${?}"
     2
     $

     $ datetest --ne 2012-03-02T00:00:00 2012-03-02 || echo 'false'
     false
     $

     $ datetest 2012-03-02T09:00:00 --ot 2012-03-02T10:00:00 && echo "true"
     true
     $

     $ datetest 2012-03-02T07:00:00 --cmp 2012-03-02T09:30:00; echo "${?}"
     2
     $

     $ datetest --cmp 2012-03-02T12:00:00 2012-03-02T09:30:00; echo "${?}"
     1
     $

     $ datetest 2012-03-02T07:00:00 --cmp 09:30:00; echo "${?}"
     3
     $


File: dateutils.info,  Node: datezone,  Next: strptime,  Prev: datetest,  Up: Top

14 datezone
***********

'datezone' may be invoked with the following command-line options:

Usage: datezone [OPTION]... [ZONENAME]... [DATE/TIME]...

Convert DATE/TIMEs between timezones.
If DATE/TIME is omitted, it defaults to `now'.

DATE/TIME can also be one of the following specials
  - `now'           interpreted as the current (UTC) time stamp
  - `time'          the time part of the current (UTC) time stamp
  - `today'         the current date (according to UTC)
  - `tomo[rrow]'    tomorrow's date (according to UTC)
  - `y[ester]day'   yesterday's date (according to UTC)

When DATE/TIME is a date (i.e. the time component is omitted)
the result will show the timezone offset at the end of that day.

When DATE/TIME is a time (i.e. the date component is omitted)
the conversion takes place on the date as specified by --base|-b,
by default the current date.

  -h, --help            display this help and exit
  -V, --version         output version information and exit
  -q, --quiet           Suppress message about date/time or zonename
                        parser errors and fix-ups.
                        The default is to print a warning or the
                        fixed up value and return error code 2.
  -b, --base=DT         For underspecified input use DT as a fallback to
                        fill in missing fields.  Also used for ambiguous
                        format specifiers to position their range on the
                        absolute time line.
                        Must be a date/time in ISO8601 format.
                        If omitted defaults to the current date/time.
  -i, --input-format=STRING...
                        Input format, can be used multiple times.
                        Each date/time will be passed to the input
                        format parsers in the order they are given, if a
                        date/time can be read successfully with a given
                        input format specifier string, that value will
                        be used.
      --from-locale=LOCALE
                        Interpret dates on stdin or the command line as
                        coming from the locale LOCALE, this would only
                        affect month and weekday names as input formats
                        have to be specified explicitly.
      --from-zone=ZONE  Interpret dates on stdin or the command line as
                        coming from the time zone ZONE.
      --next            Show next transition from/to DST.
      --prev            Show previous transition from/to DST.


Report bugs to https://github.com/hroptatyr/dateutils/issues

14.1 Examples
=============

     $ datezone 2012-03-04T12:04:11
     2012-03-04T12:04:11+00:00
     $

     $ datezone Europe/Berlin 2012-03-04T12:04:11
     2012-03-04T13:04:11+01:00	Europe/Berlin
     $

     $ datezone 2012-03-04T12:04:11 UTC
     2012-03-04T12:04:11+00:00	UTC
     $

     $ datezone Europe/Berlin Australia/Sydney 2012-01-01T14:04:00 2012-05-14T12:04:00
     2012-01-01T15:04:00+01:00	Europe/Berlin
     2012-01-02T01:04:00+11:00	Australia/Sydney
     2012-05-14T14:04:00+02:00	Europe/Berlin
     2012-05-14T22:04:00+10:00	Australia/Sydney
     $


File: dateutils.info,  Node: strptime,  Prev: datezone,  Up: Top

15 strptime
***********

'strptime' may be invoked with the following command-line options:

Usage: strptime [OPTION]... [INPUT]...

Parse input from stdin according to one of the given formats FORMATs.
The format string specifiers are the same as for strptime(3).

  -h, --help            Print help and exit
  -V, --version         Print version and exit
  -t, --time            also display time in the output, default is to
                        display the date
  -q, --quiet           Suppress message about date/time and duration
                        parser errors.
  -f, --format=STRING   Output format.  This can either be a specifier
                        string (similar to strftime()'s FMT) or the name
                        of a calendar.
  -i, --input-format=STRING...
                        Input format, can be used multiple times.
                        Each date/time will be passed to the input
                        format parsers in the order they are given, if a
                        date/time can be read successfully with a given
                        input format specifier string, that value will
                        be used.
  -e, --backslash-escapes
                        Enable interpretation of backslash escapes in the
                        output and input format specifier strings.
  -l, --locale          Make internal strptime(3) and strftime(3) behave
                        in a locale dependent way, default is to pretend
                        LC_ALL=C is in place.


Report bugs to https://github.com/hroptatyr/dateutils/issues

15.1 Examples
=============

     $ strptime -i '%a, %b-%d/%Y' 'Mon, May-01/2000'
     2000-05-01
     $

     $ strptime -i '%a, %b-%d/%Y' <<EOF
     Mon, May-01/2000
     Mon, Mar-2/2000
     EOF
     2000-05-01
     2000-03-02
     $



Tag Table:
Node: Top1800
Node: Introduction3020
Node: Calendars4291
Node: Format specifiers and units10122
Node: Localised input and output18736
Node: Algorithms21881
Node: dateadd25086
Node: dateconv29023
Node: datediff33745
Node: dategrep38322
Node: dateround44335
Node: dateseq50139
Node: datesort58596
Node: datetest64206
Node: datezone68049
Node: strptime71358

End Tag Table
