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              Deprecated, use -E|--empty-mode.
48
49       -E, --empty-mode
50              Output empty lines as placeholder for illegal input, i.e. parser
51              errors or date/times that cannot be subtracted.
52
53       -f, --format=STRING
54              Output  format.   This can either be a specifier string (similar
55              to strftime()'s FMT) or the name of a calendar.
56
57       -i, --input-format=STRING...
58              Input format, can be used multiple times.  Each  date/time  will
59              be  passed  to  the  input  format parsers in the order they are
60              given, if a date/time can be  read  successfully  with  a  given
61              input format specifier string, that value will be used.
62
63       -b, --base=DT
64              For underspecified input use DT as a fallback to fill in missing
65              fields.  Also used for ambiguous format specifiers  to  position
66              their  range  on the absolute time line.  Must be a date/time in
67              ISO8601 format.  If omitted defaults to the current date/time.
68
69       -e, --backslash-escapes
70              Enable interpretation of backslash escapes  in  the  output  and
71              input format specifier strings.
72
73       --from-locale=LOCALE
74              Interpret  dates on stdin or the command line as coming from the
75              locale LOCALE, this would only affect month and weekday names as
76              input formats have to be specified explicitly.
77
78       --from-zone=ZONE
79              Interpret  dates on stdin or the command line as coming from the
80              time zone ZONE.
81

FORMAT SPECS

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

FORMAT SPECS FOR DURATIONS

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

THE REFINEMENT RULE

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

EXAMPLES

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

AUTHOR

339       Written by Sebastian Freundt <freundt@fresse.org>
340

REPORTING BUGS

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