DATETEST(1)

✨ NAME ✨

Bestie, meet datetest(1) — it’s literally like test(1) but for dates. That’s the whole pitch. No cap, it’s the date-comparison bestie you didn’t know you needed. 💅

---

🌸 SYNOPSIS 🌸

datetest [OPTION]...  DATE/TIME1 OP DATE/TIME2

🦋 DESCRIPTION 🦋

Like test(1) but for dates. Yes, that’s the whole vibe. 🫶 You hand it two dates/times and an operator situation, and it tells you what’s up.

💖 Recognized OPTIONs 💖

• -h, --help — prints help and exits. Iconic.
• -V, --version — prints version and exits. Slay.
• -q, --quiet — suppresses the message about date/time and duration parser errors. Less noise, same drama.
• -i, --input-format=STRING... — input format, and yes you can use it 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. Big brain energy.
• -b, --base=DT — for underspecified input, use DT as a fallback to fill in missing fields. It’s also used for ambiguous format specifiers to position their range on the absolute time line. DT must be a date/time in ISO8601 format. If omitted, it defaults to the current date/time.
• --from-locale=LOCALE — interpret dates on stdin or the command line as coming from the locale LOCALE. This would only affect month and weekday names, as input formats have to be specified explicitly.
• --from-zone=ZONE — interpret dates on stdin or the command line as coming from the time zone ZONE.
• -e, --backslash-escapes — enable interpretation of backslash escapes in the output and input format specifier strings.
• --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 the left argument was newer and 2 if the right argument was newer. The receipts are built in.
• --isvalid — return success if dates specified conform to input format.

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

📅 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, day of week is Sun (range 00 to 53).
• %V — the ISO week count, 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, 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 seconds (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. That’s the limit, bestie. 💀

For conformity, here’s 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, @code{lilian}/@code{ldn} and @code{julian}/@code{jdn} can also be used as input format string.

🍓 EXAMPLES 🍓

Okay so these examples literally use dtest as written — copy them exactly, bestie, we don’t “fix” the command name here. 😭

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

👑 AUTHOR 👑

Written by Sebastian Freundt <freundt@fresse.org>. Author slay.

🐛 REPORTING BUGS 🐛

Report bugs to: https://github.com/hroptatyr/dateutils/issues. The maintainers want the tea. ☕

🔍 SEE ALSO 🔍

The full documentation for datetest is maintained as a Texinfo manual. If the info and datetest programs are properly installed at your site, the command

info (dateutils)datetest

should give you access to the complete manual. Periodt.

💖 dateutils 0.4.11 · January 2024 — that’s the footer, bestie. Mwah. 💖