CONVCAL(1)

📦
version 5.1.25 · 3 versions
, in debian bookworm, debian trixie, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

NAME ✨

convcal — convert dates to different formats 💖 (yes bestie, it's literally just that, it's giving one-job-icon)

SYNOPSIS 🎀

convcal [OPTIONS] [DATE]

DESCRIPTION 🌸

Okay so convcal is part of the grace software package, which is an application for two-dimensional data visualization 📊✨. What convcal does is convert dates from and to various formats. Here's the lineup of date formats it supports — and heads up, hour, minutes and seconds are always optional 🕰️:

  • iso — 1999-12-31T23:59:59.999
  • european — 31/12/1999 23:59:59.999 or 31/12/99 23:59:59.999
  • us — 12/31/1999 23:59:59.999 or 12/31/99 23:59:59.999
  • days — 123456.789
  • seconds — 123456.789

The formats get tried in this order: user's choice, then iso, then european, then us. (And ngl there's zero ambiguity between the calendar formats and the numerical formats, so no order is specified for those two, they just vibe.) 🌈

USAGE 🦋

convcal reads the dates either straight off the command line, or from standard input if the command line has no date in it. 💅

The user's choice for the input format puts one format ahead of all the others in the trial list — and this is mainly a gift for US citizens, who would certainly prefer having the US format checked before the european one 🇺🇸. The default user's choice (nohint) does absolutely nothing, so the following formats in the list get checked instead. Periodt.

The separators between the various fields can be any characters in the set: " :/.-T". One or more spaces act as one single separator, the other characters can't be repeated, and the T separator is only allowed between date and time — mainly for iso8601. So the string "1999-12 31:23-59" is allowed (but, bestie, it is not recommended 🙈). The - character is doing double duty here: it's a separator (the traditional iso8601 thing) and it's the unary minus (for dates way back in the far past, or for numerical dates). Two jobs, one character, main character energy honestly.

When the year is between 0 and 99 and is written with two or less digits, it gets mapped to the era beginning at wrap year and ending at wrap year + 99, like this:

[wy ; 99] -> [ wrap_year ; 100*(1 + wrap_year/100) - 1 ]

[00 ; wy-1] -> [ 100*(1 + wrap_year/100) ; wrap_year + 99]

so for example, if the wrap year is set to 1950 (which is the default value), then the mapping is:

  • range [00 ; 49] is mapped to [2000 ; 2049]
  • range [50 ; 99] is mapped to [1950 ; 1999]

this is reasonably Y2K compliant and is consistent with current use ✨. Specifying year 1 is still possible using more than two digits, like this: "0001-03-04" is unambiguously March the 4th, year 1, even if the user's choice is us format 👑. However using two digits only is not recommended (we introduce a 2050 bug here so this feature should be removed at some point in the future ;-) 💀

Numerical dates (the days and seconds formats) can be specified using integer, real or exponential formats — and yes, the 'd' and 'D' exponant markers from fortran are supported in addition to 'e' and 'E' 🧚. They're computed according to a customizable reference date. The default value is given by the REFDATE constant in the source file. You can change this value however you want before compiling, and you can change it at will using the -r command line option. The default value in the distributed file is "-4713-01-01T12:00:00" — it's a classical reference for astronomical events 🌌 (note that the - is used here both as a unary minus and as a separator, sneaky).

The program can be used either for Denys's and gregorian calendars. It does not take into account leap seconds: you can think it works only in International Atomic Time (TAI) and not in Coordinated Unified Time (UTC) ... 😭 Inexistant dates are detected, and they include year 0, dates between 1582-10-05 and 1582-10-14, February 29th of non leap years, months below 1 or above 12, ... 🔥

OPTIONS 💅

A summary of the options supported by convcal is included below. Slay.

  • -h — prints the help message on stderr and exits successfully 🫶
  • -i format — set user's choice for input format; the supported formats are iso, european, us, days, seconds and nohint. At the beginning the input format is nohint, which means the program will try to guess the format by itself; if the user's choice does not allow it to parse the date, other formats are tried 🔍
  • -o format — force output format; the supported formats are iso, european, us, days, seconds and nohint. At the beginning, the output format is nohint, which means the program uses days format for dates read in any calendar format and uses iso8601 for dates read in numerical format 🎀
  • -r date — set reference date (the date is read using the current input format); at the beginning the reference is set according to the REFDATE constant in the code, which is -4713-01-01T12:00:00 in the distributed file 🌟
  • -w year — set the wrap year to year ⭐

SEE ALSO 🌈

AUTHOR 💜

Luc Maisonobe 🌸

This man-page was written by Jan Schaumann <jschauma@netmeister.org> as part of "The Missing Man Pages Project". Please see http://www.netmeister.org/misc/m2p2/index.html for details. 💖

okay that's the whole thing bestie, you're officially a date-conversion expert, no cap 🫶✨

grace · August 11, 2001 — mwah, ty for reading, ily, bye 💋🎀

📦 where this page comes from