DATEZONE(1)

💖 NAME 💖

okay so this is datezone, from the datezone(1) manual page in the User Commands section — and bestie, it does exactly one iconic thing: it converts DATE/TIMEs between timezones. that's it, that's the whole job, and it slays at it. 🌍✨

---

🦋 SYNOPSIS 🦋

datezone [OPTION]...  [ZONENAME]... [DATE/TIME]...

---

✨ DESCRIPTION ✨

So the vibe is: you hand it DATE/TIMEs and it converts them between timezones. If you just… don't give it a DATE/TIME at all? It defaults to now. no thoughts, just the present moment. 🕐

DATE/TIME can also be one of these special little guys:

• 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)

Two rules that lowkey matter a lot:

• When DATE/TIME is a date (i.e. the time component is omitted) the result will show the timezone offset at the end of that day.
• When DATE/TIME is a time (i.e. the date component is omitted) the conversion takes place on the date as specified by --base/-b, by default the current date.

💅 Recognized OPTIONs 💅

• -h, --help — display this help and exit. classic. 🫶
• -V, --version — output version information and exit. also classic.
• -q, --quiet — Suppress message about date/time or zonename parser errors and fix-ups. The default is to print a warning or the fixed up value and return error code 2. so if you want silence instead of being lovingly corrected, this is your girl. 🤫
• -b, --base=DT — For underspecified input use DT as a fallback to fill in missing fields. Also used for ambiguous format specifiers to position their range on the absolute time line. Must be a date/time in ISO8601 format. If omitted defaults to the current date/time.
• -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.
• --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.
• --next — Show next transition from/to DST. ⏭️
• --prev — Show previous transition from/to DST. ⏮️

---

🎀 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)
• %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)

and the roman numeral era: 🏛️

• %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

the calendar-specific ones:

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

ordinals, because we're fancy: ✨

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

and the business-day girlies: 💼

• %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. not a bug, a whole design choice, and we respect it. 🚫

For conformity here is 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 🌸

no zone given? you get UTC, and honestly? she said "you're welcome". 💖

$ datezone 2012-03-04T12:04:11
2012-03-04T12:04:11+00:00
$

name a zone, get that zone. iconic behavior. 🦋

$ datezone Europe/Berlin 2012-03-04T12:04:11
2012-03-04T13:04:11+01:00     Europe/Berlin
$

zone after the timestamp? also valid, we're flexible like that.

$ datezone 2012-03-04T12:04:11 UTC
2012-03-04T12:04:11+00:00     UTC
$

and the flex: multiple zones × multiple date/times, all converted, in order. she's doing the MOST. 👑

$ datezone Europe/Berlin Australia/Sydney 2012-01-01T14:04:00 2012-05-14T12:04:00
2012-01-01T15:04:00+01:00     Europe/Berlin
2012-01-02T01:04:00+11:00     Australia/Sydney
2012-05-14T14:04:00+02:00     Europe/Berlin
2012-05-14T22:04:00+10:00     Australia/Sydney
$

---

👑 AUTHOR 👑

Written by Sebastian Freundt <freundt@fresse.org> — thank you for your service, legend. 🫡💜

---

🐛 REPORTING BUGS 🐛

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

fr fr if something's cursed, tell them there, not me. 🙈

---

🌈 SEE ALSO 🌈

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

info (dateutils)datezone

should give you access to the complete manual. 📖✨

---

okay bestie that's the whole page 💅 this was dateutils 0.4.11, dated January 2024, and this lil DATEZONE(1) manual is officially out. go convert some timezones, you got this. 🎀🦋💖