Date and time format elements for parsing/printing are defined by the following groups of characters
element |
aliases |
description |
d | D | One- or two-digit day. |
dd | DD | Two-digit day. Single-digit day values are preceded by a zero. |
th | st/TH/ST | Two-character ordinal suffix. (lower/uppercase) Must immediately follow d/D/dd/DD. |
ddd | Ddd/DDD | Three-character weekday abbreviation. (lowercase/capitalised/uppercase) |
dddd | Dddd/DDDD | Full weekday name. (lowercase/capitalised/uppercase) |
doy | | Day of year (1..366). |
h | H | One- or two-digit hour. (See am/pm notes below.) |
hh | HH | Two-digit hour. Single-digit values are preceded by a zero. ("") |
m | mm | Two-digit minute. Single-digit values are preceded by a zero. (NB not M/MM) |
s | ss/S/SS | Two-digit second. Single-digit values are preceded by a zero. |
pm | am/PM/AM | Two-letter am/pm abbreviation, prior hour must exist. (lower/uppercase) |
M | | One- or two-digit month number. (NB not m) |
MM | | Two-digit month number. Single-digit values are preceded by a zero. (NB not mm) |
mmm | Mmm/MMM | Three-character month abbreviation. (lowercase/capitalised/uppercase) |
mmmm | Mmmm/MMMM | Full month name. (lowercase/capitalised/uppercase) |
y | yy/Y/YY | One- or two-digit year. |
yyyy | YYYY | Four-digit year. |
tz | TZ | Three- or four-character uppercase time zone |
tzz | Tzz/TZZ | Full time zone name. (capitalised) |
Examples |
|
"YYYY/MM/DD ham tz" "Ddd, Mmm dst, yyyy"
"YYYY/MM/DD ham" "Ddd, Mmm dth, yyyy"
"DD Mmm YY" "ham tz" "DDD, Mmm dST, yyyy"
"M/D/YY" "ham" "Ddd, MMM DTH, yyyy"
"D/M/Y" "hpm tz" "Ddd, Mmm dth, YYYY, h:mmpm tz"
"M/D/Y" "hpm" "Ddd, Mmm dth, YYYY, h:mmpm"
"M/D/YYY" "h:m:s am" "Dddd, Mmmm dth, YYYY, h:mmpm"
"MM/DD/YY" "h:m:sam" "Dddd, Mmmm dd, yyyy"
"M/DD/YY" " (tzz)" "Dddd, Mmmm d, YYYY"
"M/DD/YYYY" "Dddd d Mmmm yyyy h:mmpm tz"
"YYYY-MM-DD" "Mmmm d, yyyy, hh:mm:ss"
"D/M/YYYY hpm TZ" "Mmmm dth yyyy h:mmam tz"
"D/M/YYYY hpm (Tzz)" "Mmmm dth yyyy h:mmam"
"dd-Mmm-YY" "Mmmm d yyyy h:mmpm tz"
"'Today is' Dddd, Mmmm dth, YYYY" -- (put literals in single quotes)
"'Today''''s date is' Dddd, Mmmm dth, YYYY"
|
WRONG |
|
"dd/mm/yyyy" -- would be day/minute/year!!
"HH:MM" -- would be hour/month!!
An error (3 element sequence) is returned if minute immediately follows day or year, or if month immediately follows hour or precedes second or ampm.
(But not if minute immedately precedes year or day, since "1:50 [2016] 2nd Jan" is fine, and month immediately preceding hour or day is fine.)
|
Technicalia
|
|
Special attention is required to avoid confusing m/mm (minute) and M/MM (month).
Spaces and punctuation (other than single quotes) in a format are treated as literals.
Any required literal alphanumerics must be enclosed in single quotes, with two adjacent
single quotes treated as one single quote, eg "'Today''''s date is 'DD/MM/YYYY.", which
yields/parses eg "Today's date is 14/09/2015."
Feel free to print fragments, eg "dst", "Mmmm", "tz", and post-process/stitch together.
At the moment ordinals (1st/2nd/3rd/4th/etc) are only supported in/for english.
There’s a commented-out set_timedate_lang() and google translates for seven other
languages besides English, all untested and awaiting approval by someone who speaks it.
Minutes and seconds <10 cannot be printed without a leading 0, but month/day/hours can.
Two digit years use a -80..+20 rule, eg in 2017, 36 -> 2036 but 37 -> 1937.
lowercase/uppercase actually match any case input, whereas capitalised is more strict;
it is really for output that all those different distinctions are available anyway.
Obviously uppercase/lowercase format specifiers make no difference on numeric fields.
A timezone is always parsed and printed in uppercase. tzz/Tzz/TZZ as-is, see tzdesc.
When am/pm is parsed/printed, it adjusts a previous hour (error if none) appropriately.
There is no way to print a 12-hour time without also printing an am/pm indicator.
The times "12:15am" and "2:15pm" are internally stored as {0,15} and {14,15} respectively,
and reconstituted exactly as they were, as long as you use the same format string.
Some languages, eg de, use a two-character weekday abbreviation - but the format string
used to obtain said is still three characters long (ddd/Ddd/DDD).
Great care has been taken to avoid any potential ambiguity, the only potential mishap
is "stz" which opts for "st" (aka "th") which will probably error out because it
does not immediately follow a d, and if it was "dstz" then it would error on the
"z" anyway. Should you really want seconds hard pressed against a timezone with
no separating space, use "sstz" instead, or stitch fragments together.
A key idea is that the same format strings can be used for parse and output, so rather
than have any fiddly "optional" bits, just use a collection of acceptable formats (and
if you need more than say eight, it may be time to think of an alternative strategy).
|