datediff(1)

1DATEDIFF(1)                      User Commands                     DATEDIFF(1)
2
3
4

NAME

6       datediff - Compute duration from DATE/TIME (the reference date/time) to
7       the other
8

SYNOPSIS

10       datediff [OPTION]...  DATE/TIME [DATE/TIME]...
11

DESCRIPTION

13       Compute duration from DATE/TIME (the reference date/time) to the  other
14       DATE/TIMEs  given  and  print  the  result  as  duration.  If the other
15       DATE/TIMEs are omitted read them from stdin.
16
17       DATE/TIME can also be one of the following specials
18         - `now'           interpreted as the current (UTC) time stamp
19         - `time'          the time part of the current (UTC) time stamp
20         - `today'         the current date (according to UTC)
21         - `tomo[rrow]'    tomorrow's date (according to UTC)
22         - `y[ester]day'   yesterday's date (according to UTC)
23
24       Note: The output format of durations (specified via -f) takes all  for‐
25       mat  specifiers  into  account,  i.e.  specifying %M and %S for example
26       prints the duration in minutes and seconds, whereas specifying %S  only
27       prints the duration in seconds.
28
29       See section `The refinement rule' in datediff(1).
30
31
32       Recognized OPTIONs:
33
34       -h, --help
35              Print help and exit
36
37       -V, --version
38              Print version and exit
39
40       -q, --quiet
41              Suppress  message about date/time and duration parser errors and
42              fix-ups.  The default is to print a  warning  or  the  fixed  up
43              value  and  return  error code 2.  Also see -S|--skip-illegal to
44              output an empty line instead of leaving out the line altogether.
45
46       -S, --skip-illegal
47              Output empty lines as placeholder for illegal input, i.e. parser
48              errors or date/times that cannot be subtracted.
49
50       -f, --format=STRING
51              Output  format.   This can either be a specifier string (similar
52              to strftime()'s FMT) or the name of a calendar.
53
54       -i, --input-format=STRING...
55              Input format, can be used multiple times.  Each  date/time  will
56              be  passed  to  the  input  format parsers in the order they are
57              given, if a date/time can be  read  successfully  with  a  given
58              input format specifier string, that value will be used.
59
60       -b, --base=DT
61              For underspecified input use DT as a fallback to fill in missing
62              fields.  Also used for ambiguous format specifiers  to  position
63              their  range  on the absolute time line.  Must be a date/time in
64              ISO8601 format.  If omitted defaults to the current date/time.
65
66       -e, --backslash-escapes
67              Enable interpretation of backslash escapes  in  the  output  and
68              input format specifier strings.
69
70       --from-locale=LOCALE
71              Interpret  dates on stdin or the command line as coming from the
72              locale LOCALE, this would only affect month and weekday names as
73              input formats have to be specified explicitly.
74
75       --from-zone=ZONE
76              Interpret  dates on stdin or the command line as coming from the
77              time zone ZONE.
78

FORMAT SPECS

80       Format specs in dateutils are similar to posix' strftime().
81
82       However, due to a broader range of supported calendars  dateutils  must
83       employ different rules.
84
85       Date specs:
86         %a  The abbreviated weekday name
87         %A  The full weekday name
88         %_a The weekday name shortened to a single character (MTWRFAS)
89         %b  The abbreviated month name
90         %B  The full month name
91         %_b The month name shortened to a single character (FGHJKMNQUVXZ)
92         %c  The count of the weekday within the month (range 00 to 05)
93         %C  The count of the weekday within the year (range 00 to 53)
94         %d  The day of the month, 2 digits (range 00 to 31)
95         %D  The day of the year, 3 digits (range 000 to 366)
96         %F  Equivalent to %Y-%m-%d (ymd's canonical format)
97         %g  ISO week date year without the century (range 00 to 99)
98         %G  ISO week date year including the century
99         %j  Equivalent to %D
100         %m  The month in the current calendar (range 00 to 19)
101         %Q  The quarter of the year (range Q1 to Q4)
102         %q  The number of the quarter (range 01 to 04)
103         %s  The number of seconds since the Epoch.
104         %u  The weekday as number (range 01 to 07, Sunday being 07)
105         %U  The week count,  day of week is Sun (range 00 to 53)
106         %V  The ISO week count,  day of week is Mon (range 01 to 53)
107         %w  The weekday as number (range 00 to 06, Sunday being 00)
108         %W  The week count,  day of week is Mon (range 00 to 53)
109         %y  The year without a century (range 00 to 99)
110         %Y  The year including the century
111         %_y The year shortened to a single digit
112         %Z  The zone offset in hours and minutes (HH:MM) with
113             a preceding sign (+ for offsets east of UTC, - for offsets
114             west of UTC)
115
116         %Od The day as roman numerals
117         %Om The month as roman numerals
118         %Oy The two digit year as roman numerals
119         %OY The year including the century as roman numerals
120
121         %rs In time systems whose Epoch is different from the unix Epoch, this
122             selects the number of seconds since then.
123         %rY In calendars with years that don't coincide with the Gregorian
124             years, this selects the calendar's year.
125
126         %dth  The day of the month as an ordinal number, 1st, 2nd, 3rd, etc.
127         %mth  The month of the year as an ordinal number, 1st, 2nd, 3rd, etc.
128
129         %db The business day of the month (since last month's ultimo)
130         %dB Number of business days until this month's ultimo
131
132       Time specs:
133         %H  The hour of the day using a 24h clock, 2 digits (range 00 to 23)
134         %I  The hour of the day using a 12h clock, 2 digits (range 01 to 12)
135         %M  The minute (range 00 to 59)
136         %N  The nanoseconds (range 000000000 to 999999999)
137         %p  The string AM or PM, noon is PM and midnight is AM.
138         %P  Like %p but in lowercase
139         %S  The  (range 00 to 60, 60 is for leap seconds)
140         %T  Equivalent to %H:%M:%S
141
142       General specs:
143         %n  A newline character
144         %t  A tab character
145         %%  A literal % character
146
147       Modifiers:
148         %O  Modifier to turn decimal numbers into Roman numerals
149         %r  Modifier to turn units into real units
150         %0  Modifier to turn on zero prefixes
151         %SPC  Modifier to turn on space prefixes
152         %-  Modifier to turn off prefixes altogether
153         th  Suffix, read and print ordinal numbers
154         b   Suffix, treat days as business days
155
156       By design dates before 1601-01-01 are not supported.
157
158       For  conformity here is a list of calendar designators and their corre‐
159       sponding format string:
160         ymd     %Y-%m-%d
161         ymcw    %Y-%m-%c-%w
162         ywd     %rY-W%V-%u
163         bizda   %Y-%m-%db
164         lilian     n/a
165         ldn        n/a
166         julian     n/a
167         jdn        n/a
168         matlab     n/a
169         mdn        n/a
170
171       These designators can  be  used  as  output  format  string,  moreover,
172       @code{lilian}/@code{ldn}  and @code{julian}/@code{jdn} can also be used
173       as input format string.
174
175

FORMAT SPECS FOR DURATIONS

177       Unlike time or absolute instants, durations  are  reference-free,  i.e.
178       the  reference  instant is not part of the duration.  As a result dura‐
179       tions cannot be named, i.e. there is no naming scheme that  applies  to
180       all durations and all references unambiguously.
181
182       Consequently,  none of the format specifiers for date/times makes sense
183       for durations in the literal sense.  However, to aid intuitive usage we
184       reused  format  specifiers  when  they  represent integral values and a
185       valid unit for duration, as follows:
186
187       Date specs:
188         %c  Equivalent to %w
189         %d  Duration in days
190         %F  Equivalent to %dd with no resorting to bigger units
191         %m  Duration in months
192         %w  Duration in weeks
193         %y  Equivalent to %Y
194         %Y  Duration in years
195
196         %db Duration in business days
197         %dB Equivalent to %db
198
199       Time specs:
200         %H  Duration in hours
201         %I  Equivalent to %H
202         %M  Duration in minutes
203         %S  Duration in seconds
204         %T  Equivalent to %Ss without resorting to bigger units
205
206         %rS Duration in real-life seconds, as in including leap seconds
207         %rT Equivalent to %rSs without resorting to bigger units
208
209       General specs:
210         %n  A newline character
211         %t  A tab character
212         %%  A literal % character
213
214       Modifiers:
215         %r    Modifier to turn units into real units
216         %0    Modifier to pad refined values with zeroes
217         %SPC  Modifier to pad refined values with spaces
218         b     Suffix, treat days as business days
219

THE REFINEMENT RULE

221       Durations are somewhat ambiguous when it  comes  to  representing  them
222       through  format  specifiers.  Unlike format specifiers in point-in-time
223       representations duration specifiers can have  an  intra-line  relation‐
224       ship.
225
226       So  for  instance  a duration of 128 seconds might be presented through
227       "%S" as "128" but similarly through "%M:%S" as "02:08" (read  two  min‐
228       utes and 8 seconds).
229
230       There are several approaches to deal with this ambiguity.  The datediff
231       tool will follow, what we call, the refinement rule.  That is,  regard‐
232       less  of  the position of a format specifier, if it is a valid /refine‐
233       ment/ of another specifier in the format string, then it will only show
234       the  fractional value, i.e. the value in its natural range with respect
235       to the /refined/ specifier.
236
237         %Y  possible refinements: %m, %w, %d
238         %m  possible refinements: %w, %d
239         %w  possible refinements: %d
240         %d  possible refinements: %H, %M, %S
241         %H  possible refinements: %M, %S
242         %M  possible refinements: %S
243
244       The refinement alternatives are listed in order of precedence and  they
245       are  mutually exclusive.  I.e. it is not possible to express a duration
246       in months and hours without having a "%d" specifier as  well.   On  the
247       other  hand in a chain of refinements inner elements are optional, i.e.
248       you can express a duration in weeks and hours because every day has  24
249       hours and hence there are 168 hours in a week.
250
251       In case of negative durations (the minuend is in the future relative to
252       the subtrahend) only the largest unit will carry the minus sign.
253
254       Using the refinement rule keeps the format string dead simple,  there's
255       no need for operators or a full-blown language to distinguish the range
256       ambiguity, which then would have to be escaped because they could  also
257       in  theory  be  part  of  the  literal characters of the format string,
258       resulting more often than not in command lines that are hard  to  craft
259       and even harder to understand later on (e.g. if used in shell scripts).
260
261       The  refinement  rule ingeniously covers the 99% case but, unlike other
262       approaches, there's no way to display two unrefined values in the  same
263       format string, e.g. "'%w weeks (which is %d days)'".
264
265

EXAMPLES

267         $ datediff 2012-03-02 2012-03-02
268         0
269         $
270
271         $ datediff 2012-03-02 2012-03-12
272         10
273         $
274
275         $ datediff 2012-03-02 2012-04-12
276         41
277         $
278
279         $ datediff 2012-03-12 2012-04-02
280         21
281         $
282
283         $ datediff 2012-04-02 2012-03-12
284         -21
285         $
286
287         $ datediff 2012-01-02 2012-02-29 -f '%dd'
288         58d
289         $
290
291         $ datediff 2012-01-02 2012-02-29 -f '%ww %dd'
292         8w 2d
293         $
294
295         $ datediff 10:00:00 10:00:00
296         0s
297         $
298
299         $ datediff 10:01:00 10:06:00
300         300s
301         $
302
303         $ datediff 10:06:00 10:01:00
304         -300s
305         $
306
307         $ datediff 10:01:00 11:03:10 -f '%S sec'
308         3730 sec
309         $
310
311         $ datediff 10:01:00 11:03:10 -f '%Mm %Ss'
312         62m 10s
313         $
314
315         $ datediff 10:01:00 11:03:10 -f '%H:%M:%S'
316         1:2:10
317         $
318
319         $ datediff 2012-03-02T10:04:00 2012-03-02T10:14:00
320         600s
321         $
322
323         $ datediff 2012-03-02T10:04:00 2012-03-02T10:14:00 -f '%M min'
324         10 min
325         $
326
327         $ datediff 2012-03-01T12:17:00 2012-03-02T14:00:00
328         92580s
329         $
330
331         $ datediff 2012-03-01T12:17:00 2012-03-02T14:00:00 -f '%d days and %S seconds'
332         1 days and 6180 seconds
333         $
334

AUTHOR

336       Written by Sebastian Freundt <freundt@fresse.org>
337

REPORTING BUGS

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