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

NAME

6       dateround - Round DATE/TIME to the next occurrence of RNDSPEC.
7

SYNOPSIS

9       dateround [OPTION]...  [DATE/TIME] RNDSPEC...
10

DESCRIPTION

12       Round DATE/TIME to the next occurrence of RNDSPEC.
13
14       If DATE/TIME is omitted a stream of date/times is read from stdin.
15
16       DATE/TIME can also be one of the following specials
17         - `now'           interpreted as the current (UTC) time stamp
18         - `time'          the time part of the current (UTC) time stamp
19         - `today'         the current date (according to UTC)
20         - `tomo[rrow]'    tomorrow's date (according to UTC)
21         - `y[ester]day'   yesterday's date (according to UTC)
22
23       1.  RNDSPECs  can  be  month names (Jan, Feb, ...), weekday names (Sun,
24       Mon, ...),
25          numerals suffixed with y, q, mo, d, bd, h, m, or  s,  possibly  pre‐
26       fixed with
27          a dash (`-`) to indicate the rounding direction is downwards.
28
29       2. Suffixed RNDSPECs may additionally be prefixed with a slash (`/`) to
30          indicate that rounding to a multiple of RNDSPEC is desired.
31          Co-class rounding.
32
33       In  the first case, rounding affects the named element in the specified
34       date or date/time and more significant elements by setting this element
35       to the specified value and adjusting the more significant elements such
36       that the result is greater (younger) or equal to the input (or strictly
37       greater  when -n|--next is given) for positive values, and less (older)
38       or equal (unless -n|--next is given) for named elements that  are  pre‐
39       fixed with dash (`-`).  In either case, less significant elements, e.g.
40       subdivisions of the named element and their subdivisions are  left  un‐
41       changed.
42
43           That is     dateround 2019-01-28T12:04:00 +6
44           will yield  2019-02-06T12:04:00
45
46           Similarly   dateround -n 2019-01-28T12:04:00 -- -Oct
47           will yield  2018-10-28T12:04:00
48
49       In the second case, rounding is more like rounding decimal fractions to
50       negative infinity.  The time axis is partitioned by  multiples  of  the
51       named  element,  and  the  oldest  date or datetime is returned that is
52       greater (younger) (or equal if -n|--next is omitted) than the specified
53       date  or  date/time, when rounding down (`-` prefix) the oldest date or
54       datetime is returned that is less (older) than the  specified  date  or
55       datetime.
56
57           That is     dateround 2019-01-28T12:04:00 /1y
58           will yield  2020-01-01T00:00:00
59
60           Similarly   dateround 2019-01-28T12:04:00 /-30m
61           will yield  2019-01-28T12:00:00
62
63       The  superdivision of years are millennia, i.e. there's 1000 years, 500
64       biennia, 100 decades, etc. in a millenium.
65
66       Multiple RNDSPECs are evaluated left to right.
67
68       Note that rounding isn't commutative, e.g.        dateround  2012-03-01
69       Sat  Sep  ->  2012-09-03  vs.        dateround  2012-03-01  Sep  Sat ->
70       2012-09-01
71
72       Note that non-numeric strings prefixed with a  `-'  conflict  with  the
73       command line options and a separating `--' has to be used.
74
75
76       Recognized OPTIONs:
77
78       -h, --help
79              Print help and exit
80
81       -V, --version
82              Print version and exit
83
84       -q, --quiet
85              Suppress  message about date/time and duration parser errors and
86              fix-ups.  The default is to print a  warning  or  the  fixed  up
87              value and return error code 2.
88
89       -f, --format=STRING
90              Output  format.   This can either be a specifier string (similar
91              to strftime()'s FMT) or the name of a calendar.
92
93       -i, --input-format=STRING...
94              Input format, can be used multiple times.  Each  date/time  will
95              be  passed  to  the  input  format parsers in the order they are
96              given, if a date/time can be read successfully with a given  in‐
97              put format specifier string, that value will be used.
98
99       -b, --base=DT
100              For underspecified input use DT as a fallback to fill in missing
101              fields.  Also used for ambiguous format specifiers  to  position
102              their  range  on the absolute time line.  Must be a date/time in
103              ISO8601 format.  If omitted defaults to the current date/time.
104
105       -e, --backslash-escapes
106              Enable interpretation of backslash escapes in the output and in‐
107              put format specifier strings.
108
109       -S, --sed-mode
110              Copy parts from the input before and after a matching date/time.
111              Note that all occurrences of date/times within a  line  will  be
112              processed.
113
114       -E, --empty-mode
115              Empty lines that cannot be parsed.
116
117       --locale=LOCALE
118              Format results according to LOCALE, this would only affect month
119              and weekday names.
120
121       --from-locale=LOCALE
122              Interpret dates on stdin or the command line as coming from  the
123              locale LOCALE, this would only affect month and weekday names as
124              input formats have to be specified explicitly.
125
126       --from-zone=ZONE
127              Interpret dates on stdin or the command line as coming from  the
128              time zone ZONE.
129
130       -z, --zone=ZONE
131              Convert dates printed on stdout to time zone ZONE, default: UTC.
132
133       -n, --next
134              Always round to a different date or time.
135

FORMAT SPECS

137       Format specs in dateutils are similar to posix' strftime().
138
139       However,  due  to a broader range of supported calendars dateutils must
140       employ different rules.
141
142       Date specs:
143         %a  The abbreviated weekday name
144         %A  The full weekday name
145         %_a The weekday name shortened to a single character (MTWRFAS)
146         %b  The abbreviated month name
147         %B  The full month name
148         %_b The month name shortened to a single character (FGHJKMNQUVXZ)
149         %c  The count of the weekday within the month (range 00 to 05)
150         %C  The count of the weekday within the year (range 00 to 53)
151         %d  The day of the month, 2 digits (range 00 to 31)
152         %D  The day of the year, 3 digits (range 000 to 366)
153         %F  Equivalent to %Y-%m-%d (ymd's canonical format)
154         %g  ISO week date year without the century (range 00 to 99)
155         %G  ISO week date year including the century
156         %j  Equivalent to %D
157         %m  The month in the current calendar (range 00 to 12)
158         %Q  The quarter of the year (range Q1 to Q4)
159         %q  The number of the quarter (range 01 to 04)
160         %s  The number of seconds since the Epoch.
161         %u  The weekday as number (range 01 to 07, Sunday being 07)
162         %U  The week count,  day of week is Sun (range 00 to 53)
163         %V  The ISO week count,  day of week is Mon (range 01 to 53)
164         %w  The weekday as number (range 00 to 06, Sunday being 00)
165         %W  The week count,  day of week is Mon (range 00 to 53)
166         %y  The year without a century (range 00 to 99)
167         %Y  The year including the century
168         %_y The year shortened to a single digit
169         %Z  The zone offset in hours and minutes (HH:MM) with
170             a preceding sign (+ for offsets east of UTC, - for offsets
171             west of UTC)
172
173         %Od The day as roman numerals
174         %Om The month as roman numerals
175         %Oy The two digit year as roman numerals
176         %OY The year including the century as roman numerals
177
178         %rs In time systems whose Epoch is different from the unix Epoch, this
179             selects the number of seconds since then.
180         %rY In calendars with years that don't coincide with the Gregorian
181             years, this selects the calendar's year.
182
183         %dth  The day of the month as an ordinal number, 1st, 2nd, 3rd, etc.
184         %mth  The month of the year as an ordinal number, 1st, 2nd, 3rd, etc.
185
186         %db The business day of the month (since last month's ultimo)
187         %dB Number of business days until this month's ultimo
188
189       Time specs:
190         %H  The hour of the day using a 24h clock, 2 digits (range 00 to 23)
191         %I  The hour of the day using a 12h clock, 2 digits (range 01 to 12)
192         %M  The minute (range 00 to 59)
193         %N  The nanoseconds (range 000000000 to 999999999)
194         %p  The string AM or PM, noon is PM and midnight is AM.
195         %P  Like %p but in lowercase
196         %S  The  (range 00 to 60, 60 is for leap seconds)
197         %T  Equivalent to %H:%M:%S
198
199       General specs:
200         %n  A newline character
201         %t  A tab character
202         %%  A literal % character
203
204       Modifiers:
205         %O  Modifier to turn decimal numbers into Roman numerals
206         %r  Modifier to turn units into real units
207         %0  Modifier to turn on zero prefixes
208         %SPC  Modifier to turn on space prefixes
209         %-  Modifier to turn off prefixes altogether
210         th  Suffix, read and print ordinal numbers
211         b   Suffix, treat days as business days
212
213       By design dates before 1601-01-01 are not supported.
214
215       For conformity here is a list of calendar designators and their  corre‐
216       sponding format string:
217         ymd     %Y-%m-%d
218         ymcw    %Y-%m-%c-%w
219         ywd     %rY-W%V-%u
220         bizda   %Y-%m-%db
221         lilian     n/a
222         ldn        n/a
223         julian     n/a
224         jdn        n/a
225         matlab     n/a
226         mdn        n/a
227
228       These  designators  can  be  used  as  output  format string, moreover,
229       @code{lilian}/@code{ldn} and @code{julian}/@code{jdn} can also be  used
230       as input format string.
231
232

SPECIFYING DURATIONS

234       Some tools ("dateadd", "dateseq") need durations as their input.  Dura‐
235       tions are generally incompatible with input  formats  as  specified  by
236       "-i|--input-format" and (at the moment) the input syntax is fixed.
237
238       The  general  format  is  "+-Nunit" where "+" or "-" is the sign, "N" a
239       number, and "unit" the unit as discussed below.
240
241       Units:
242         s  seconds
243         m  minutes
244         h  hours
245         rs real-life seconds, as in including leap  transitions
246
247         d  days
248         b  business days
249         mo months
250         y  years
251
252       For historical reasons, we used to accept "m" in the context  of  date-
253       only  input  as a qualifier for months.  As of 0.4.4, this is no longer
254       the case.
255
256

EXAMPLES

258         $ dateround 2012-03-01 2
259         2012-03-02
260         $
261
262         $ dateround -n 2012-03-01 1
263         2012-04-01
264         $
265
266         $ dateround 17:05:00 5m
267         17:05:00
268         $ dateround 17:04:00 /5m
269         17:05:00
270         $
271
272         $ dateround -n 17:04:00 4m
273         18:04:00
274         $ dateround -n 17:04:00 /1m
275         17:05:00
276         $
277

AUTHOR

279       Written by Sebastian Freundt <freundt@fresse.org>
280

REPORTING BUGS

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

SEE ALSO

285       The full documentation for dateround is maintained as a Texinfo manual.
286       If the info and dateround programs are properly installed at your site,
287       the command
288
289              info (dateutils)dateround
290
291       should give you access to the complete manual.
292
293
294
295dateutils 0.4.10                   May 2022                       DATEROUND(1)
Impressum