This is dateutils.info, produced by makeinfo version 4.13 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
* dadd: (dateutils)dadd.                        Add durations to dates or times.
* dconv: (dateutils)dconv.                      Convert dates between
                                                  calendars or time zones.
* ddiff: (dateutils)ddiff.                      Compute durations between dates
                                                  and times.
* dgrep: (dateutils)dgrep.                      Find date or time matches in
                                                  input stream.
* dround: (dateutils)dround.                    Round dates or times to
                                                  designated values.
* dseq: (dateutils)dseq.                        Generate sequences of dates or
                                                  times.
* dtest: (dateutils)dtest.                      Compare dates or times.
* strptime: (dateutils)strptime.                Command line version
                                                  of the C function.
END-INFO-DIR-ENTRY

   This manual documents the dateutils package.

   Copyright (C) 2011-2012 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
* Algorithms::          Some notes on the algorithms used
* dadd::                Add durations to dates or times
* dconv::               Convert dates between calendars or time zones
* ddiff::               Compute durations between dates and times
* dgrep::               Find date or time matches in input stream
* dround::              Round dates or times to designated values
* dseq::                Generate sequences of dates or times
* dtest::               Compare dates or times
* 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,
date-core.  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 tools' 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'.

2.2 ymcw
========

This is a calendric system used at some security exchanges, it holds a
year, a month, a weekday and the count of the weekday within the month.
This holds dates like the third Thursday in March 2011.  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'.

2.3 daisy
=========

This is one of the most common calendric systems, it counts the days
since (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) a given reference date.  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 below 1917 in a
similar fashion.

   The daisy calendar has no notion of years or months.

   The daisy calendar has no associated input or output format.  This is
due to its nature that the reference date is arbitrary.  Outlook: As
soon as Julian dates are supported, daisy will use its in/out format
specs.

   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 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.

2.5 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).


File: dateutils.info,  Node: Format specifiers and units,  Next: Algorithms,  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)
  %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

  %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
  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 spec names and their
meaning:
  ymd   %Y-%m-%d
  ymcw  %Y-%m-%c-%w
  ywd   %rY-W%V-%u
  bizda %Y-%m-%db

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  Durations in days
  %F  Equivalent to %dd with no resorting to bigger units
  %m  Durations in months
  %w  Durations in weeks
  %y  Equivalent to %Y
  %Y  Durations in years

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

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

  %rS Durations in real-life seconds, as in including leap seconds
  %rT Equivalent to %rSs without resoring 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.

   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


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

4 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.

4.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: dadd,  Next: dconv,  Prev: Algorithms,  Up: Top

5 dadd
******

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

dadd 0.2.7

Usage: dadd [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.
  -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.
  -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.
      --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.

5.1 Examples
============

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

     $ dadd 2012-03-01 1m
     2012-04-01
     $

     $ dadd 2012-03-31 1m
     2012-04-30
     $

     $ dadd 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
     $

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

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

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


File: dateutils.info,  Node: dconv,  Next: ddiff,  Prev: dadd,  Up: Top

6 dconv
*******

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

dconv 0.2.7

Usage: dconv [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.
  -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.
      --default=DT           For underspecified input use DT as a fallback to
                               fill in missing fields.  Must be a date/time in
                               ISO8601 format.  If omitted the default value is
                               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.
      --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.

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

     $ dconv 2012-03-01
     2012-03-01
     $

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

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

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

     $ dconv 12:03:01
     12:03:01
     $

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

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

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

     $ dconv --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
     $

     $ dconv --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
     $

     $ dconv --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: ddiff,  Next: dgrep,  Prev: dconv,  Up: Top

7 ddiff
*******

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

ddiff 0.2.7

Usage: ddiff [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 ddiff(1).

  -h, --help                 Print help and exit
  -V, --version              Print version and exit
  -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.
      --from-zone=ZONE       Interpret dates on stdin or the command line as
                               coming from the time zone ZONE.

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

     $ ddiff 2012-03-02 2012-03-02
     0
     $

     $ ddiff 2012-03-02 2012-03-12
     10
     $

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

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

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

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

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

     $ ddiff 10:00:00 10:00:00
     0s
     $

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

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

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

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

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

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

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

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

     $ ddiff 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: dgrep,  Next: dround,  Prev: ddiff,  Up: Top

8 dgrep
*******

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

dgrep 0.2.7

Usage: dgrep [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.

  -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.
  -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.

 Group: op
  Operations can be specified by options as well.
  EXPRESSION must then be a date/time and no concatenation through
  conjunction (`&&') or disjunction (`||') operators is possible.

  This serves solely as a means of convenience, e.g. the dtest tool has a
  similar syntax.
      --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.

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

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

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

     $ dgrep \!=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
     $

     $ dgrep =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
     $

     $ dgrep -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
     $

     $ dgrep '>=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
     $

     $ dgrep -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
     $

     $ dgrep 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
     $

     $ dgrep '<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
     $

     $ dgrep 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
     $

     $ dgrep '<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: dround,  Next: dseq,  Prev: dgrep,  Up: Top

9 dround
********

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

dround 0.2.7

Usage: dround [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)


RNDSPECs can be month names (Jan, Feb, ...), weekday names (Sun, Mon, ...), or
days.
If a month name the next date/time relative to DATE/TIME is returned whose
month part matches the value given, so e.`g. dround 2012-01-01 Feb' will return
2012-02-01.
If a weekday name is given, the next date/time after DATE/TIME whose weekday
part matches the values given is returned.
If a day, the next date/time after DATE/TIME whose day part matches is
returned, so `dround 2012-01-15 1' will return 2012-02-01.

RNDSPECs can also be multiples of the day dividing units, e.g 1h rounds to the
nearest full hour, 30m to the nearest half hour, and 10s to the next 10s mark.

To round to the previous occurrence of a RNDSPEC any argument can be prefixed
with a `-' to denote that.  E.g. `dround 2012-02-14 -1' will return 2012-02-01.
And `dround 2012-02-11 -- -Sep' will return 2011-09-11.

Multiple RNDSPECs are evaluated left to right.

Note that rounding isn't commutative, e.g.
	2012-03-01 Sat Sep -> 2012-09-03
vs.
	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.
  -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.
  -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.
      --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.

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

     $ dround 2012-03-01 2
     2012-03-02
     $

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

     $ dround 17:04:00 5m
     17:05:00
     $

     $ dround -n 17:04:00 1m
     17:05:00
     $


File: dateutils.info,  Node: dseq,  Next: dtest,  Prev: dround,  Up: Top

10 dseq
*******

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

dseq 0.2.7

Usage: dseq [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.
  -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.
  -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.

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

     $ dseq 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
     $

     $ dseq 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
     $

     $ dseq --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
     $

     $ dseq 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
     $

     $ dseq --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
     $

     $ dseq 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
     $

     $ dseq --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
     $

     $ dseq --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
     $

     $ dseq --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
     $

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

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

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

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

     $ dseq 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
     $

     $ dseq --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
     $

     $ dseq 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
     $

     $ dseq --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: dtest,  Next: strptime,  Prev: dseq,  Up: Top

11 dtest
********

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

dtest 0.2.7

Usage: dtest [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.
  -e, --backslash-escapes    Enable interpretation of backslash escapes in the
                               output and input format specifier strings.

 Group: op
  Following operations are supported
      --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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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


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

12 strptime
***********

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

strptime 0.2.7

Usage: strptime [-h|--help] [-V|--version] [-t|--time] [-q|--quiet]
         [-fSTRING|--format=STRING] [-iSTRING|--input-format=STRING]
         [-e|--backslash-escapes] [-S|--sed-mode] [FMTs]...

Parse input from stdin according to one of the given formats FMTs.
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.
  -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.



Tag Table:
Node: Top1772
Node: Introduction2798
Node: Calendars4069
Node: Format specifiers and units8571
Node: Algorithms16181
Node: dadd19385
Node: dconv22290
Node: ddiff26259
Node: dgrep29539
Node: dround34747
Node: dseq38439
Node: dtest45991
Node: strptime48918

End Tag Table
