DATE::DATETIME 1g 2023 laplante@plcb.ca GOWEB/DATE

title: DATE::DATETIME section: 1g version: 1.0.0 date: 2023 author: laplante@plcb.ca

category: GOWEB/DATE

name

date::datetime Parse a date, perform an operation, and output the result.

SYNOPSIS

date::datetime or datetime([date: "date_string", op: "operation_string", format: "format_string",
    location: "location_string", layout: "layout_string", locale: "locale_string", lg: "lg_string"])

DESCRIPTION

The datetime function parses a given date, optionally applies an operation (such as adding days or months), and outputs the date in a specified format.

• If no date is specified, the current date is used.
• If no format is specified, the default is %!F(MISSING) %!T(MISSING), producing output in the format YYYY-MM-DD HH:MM:SS.

PARAMETERS

date

The input date can be in multiple formats. The function attempts to detect the layout automatically unless explicitly set with the layout parameter.

Order of parsing attempts:

1. If the date contains only digits, it is parsed as seconds since the epoch.
2. Layout 2006-01-02 15:04:05
3. Layout RFC1123Z — e.g., Thu, 19 Apr 2018 11:00:49 +0000
4. Layout 2006-01-02

layout

Specifies the format of the input date. Follows Go’s time package layouts (see time package constants).

Additional Layout Behavior

When lg is set and format contains %!e(MISSING)lg:

• If lg = "fr" and the date is the 1st of the month → outputs 1er mois; otherwise 26 mois.
• If lg = "en" → outputs Month 1st, Month 2nd, Month 3rd, Month 4th, etc.

In format, %!b(MISSING) outputs the abbreviated month name according to the current locale. The locale parameter affects this result.

locale

Sets the locale for output formatting (does not affect input parsing — use location for that).

List available locales:

locale -a

(The full list can be very long; run the command above on your system to see all installed locales.)

location

Specifies the timezone used to interpret the input date.

List available locations (Linux):

awk '/^Z/ { print $2 }; /^L/ { print $3 }' /usr/share/zoneinfo/tzdata.zi

lg

Shorthand to select a locale via a language key defined in the configuration file, for example:

[lg]
    fr = "fr_CA.utf8"
    en = "en_CA.utf8"

operation

Defines a modification to apply to the input date.

[+|-]<number><unit>

Where unit is one of:

• s : second
• m : minute
• h : hour
• d : day
• w : week
• M : month
• y : year

Multiple operations can be chained (e.g., 1M5m7s).

format

Output formatting uses Linux strftime. Default: %!F(MISSING) %!T(MISSING).

Common directives include:

• %!a(MISSING) — Abbreviated weekday name (locale-based)
• %!A(MISSING) — Full weekday name
• %!b(MISSING) — Abbreviated month name
• %!B(MISSING) — Full month name
• %!c(MISSING) — Preferred date/time representation (locale-based)
• %!C(MISSING) — Century (year/100) as 2-digit integer
• %!d(MISSING) — Day of month (01–31)
• %!D(MISSING) — Equivalent to %!m(MISSING)/%!d(MISSING)/%!y(MISSING)
• %!e(MISSING) — Day of month, leading space instead of zero
• %!E(MISSING) — Alternate format modifier
• %!F(MISSING) — ISO date %!Y(MISSING)-%!m(MISSING)-%!d(MISSING)
• %!G(MISSING) — ISO 8601 year with century
• %!g(MISSING) — ISO 8601 year without century (00–99)
• %!h(MISSING) — Equivalent to %!b(MISSING)
• %!H(MISSING) — Hour (00–23)
• %!I(MISSING) — Hour (01–12)
• %!j(MISSING) — Day of year (001–366)
• %!k(MISSING) — Hour ( 0–23, leading space)
• %!l(MISSING) — Hour ( 1–12, leading space)
• %!m(MISSING) — Month (01–12)
• %!M(MISSING) — Minute (00–59)
• %!n(MISSING) — Newline
• %!O(MISSING) — Alternate format modifier
• %!p(MISSING) — AM or PM (locale-based)
• %!P(MISSING) — am or pm (lowercase, GNU)
• %!r(MISSING) — 12-hour clock time; in POSIX %!I(MISSING):%!M(MISSING):%!S(MISSING) %!p(MISSING)
• %!R(MISSING) — 24-hour time %!H(MISSING):%!M(MISSING)
• %!s(MISSING) — Seconds since the Epoch (UTC)
• %!S(MISSING) — Second (00–60; allows leap seconds)
• %!t(MISSING) — Tab
• %!T(MISSING) — 24-hour time %!H(MISSING):%!M(MISSING):%!S(MISSING)
• %!u(MISSING) — ISO weekday number (1–7; Monday=1)
• %!U(MISSING) — Week number, Sunday as first day (00–53)
• %!V(MISSING) — ISO week number (01–53; Monday as first day)
• %!w(MISSING) — Weekday number (0–6; Sunday=0)
• %!W(MISSING) — Week number, Monday as first day (00–53)
• %!x(MISSING) — Preferred date (locale-based)
• %!X(MISSING) — Preferred time (locale-based)
• %!y(MISSING) — Year without century (00–99)
• %!Y(MISSING) — Year with century
• %!z(MISSING) — Numeric UTC offset (e.g., +0100)
• %!Z(MISSING) — Time zone name or abbreviation
• %!<(MISSING)/code> — Date/time in date(1) format
• % — Literal percent sign

datetime(date: "2000-01-31", op: "1M")
→ 2000-02-29 00:00:00

datetime(location: "Europe/Paris", date: "2000-01-31 03:00:00", op: "1M", format: "%!F(MISSING) %!T(MISSING)")
→ 2000-02-29 03:00:00

datetime(date: "2000-01-31 03:04:05", op: "1M5m7s", format: "%!F(MISSING) %!T(MISSING)")
→ 2000-02-29 03:09:12

datetime(date: "2000-01-31 03:04:05", op: "-1M-5m-7s", format: "%!F(MISSING) %!T(MISSING)")
→ 1999-12-31 02:58:58

a := "2000-01-31 03:04:05";
a; "  ";
a = datetime(date:a, op:"+15M", format: "%!F(MISSING) %!T(MISSING)");
a; "  ";
datetime(date:a, op:"-15M", format: "%!F(MISSING) %!T(MISSING)")
→ 2000-01-31 03:04:05  2001-04-30 03:04:05  2000-01-30 03:04:05

datetime(date: "2021-10-28 00:00:00", op: "-10m")
→ 2021-10-27 23:50:00

datetime(date: "2000-02-29", op: "-1y")
→ 2001-02-28 00:00:00

datetime(date: "2000-02-29", op: "+1y")
→ 2001-02-28 00:00:00

datetime(date: "2023-05-01", lg: "fr", format: "%!B(MISSING)")
→ mai

datetime(date: "2023-05-01", lg: "xr", format: "%!B(MISSING)")
→ *invalid lg 'xr'*