This is dateutils.info, produced by makeinfo version 7.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 © 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 12)
  %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:



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:



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:



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:



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:



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:



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:



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:



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:



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:



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: Top1799
Node: Introduction3019
Node: Calendars4290
Node: Format specifiers and units10189
Node: Localised input and output18887
Node: Algorithms22136
Node: dateadd25349
Node: dateconv26075
Node: datediff27775
Node: dategrep29106
Node: dateround31301
Node: dateseq31824
Node: datesort36133
Node: datetest39673
Node: datezone40966
Node: strptime41721

End Tag Table


Local Variables:
coding: utf-8
End:
