smjg.libs.util.datetimeformat
The smjg.libs.util.datetimeformat module implements the generation of formatted date and time strings.
Usually, one will not use this module directly, but instead use the corresponding properties of the types defined in smjg.libs.util.datetime.- Format specifiers:
-
The letters of the basic Latin alphabet are reserved for format specifiers. Each specifier is a
letter, or two or more of the same letter consecutively. The letter denotes what piece of
information to format, and the capitalisation and length denote how to format it. Where
alternative capitalisations are given for a single format, they denote the output capitalisation
of the corresponding datum.
Letter Datum Specifier Format Y Year yy
Two digits yyy
Exact required length yyyy
Four digits (longer if necessary) YYY
Astronomical notation (BC represented as negative numbers) B BC/AD B
orb
BC if necessary BB
orbb
BC or AD BBB
orbbb
BCE or CE BBBB
orbbbb
BCE if necessary M Month m
numeric without leading zero mm
numeric with leading zero MMM
,Mmm
ormmm
abbreviated name MMMM
,Mmmm
ormmmm
full name D Day of month d
no leading zero dd
leading zero T Ordinal suffix T
ort
Ordinal suffix (TH, ND or RD) of last formatted datum W Day of week WWW
,Www
orwww
abbreviated name WWWW
,Wwww
orwwww
full name H Hour H
24-hour without leading zero HH
24-hour with leading zero h
12-hour without leading zero hh
12-hour with leading zero A AM/PM A
ora
A or P AA
oraa
AM or PM I Minute i
no leading zero ii
leading zero S Second s
no leading zero ss
leading zero F Fraction of a second f
deciseconds FF
centiseconds with leading zero ff
centiseconds without leading zero FFF
milliseconds with leading zero fff
milliseconds without leading zero Z Time zone zzzz
offset from UTC
- Format specifier examples:
-
Format string Sample formatted date/time dd/mm/yy
08/09/05
Www dt Mmm yyyy BB
Thu 8th Sep 2005 AD
h:ii AA
4:51 PM
yyyy-mm-dd HH:ii:ss zzzz
2005-09-08 16:51:09 +0100
- Literals:
-
Any non-alphabetic character that doesn't have a special meaning is a literal, i.e. it will be placed as is in the generated string. You can literalise a single character by placing a backquote (
`
) immediately before it, or any number of consecutive characters by enclosing them in single quotes ('...'
).All letters of the basic Latin alphabet, even those that are not defined as format specifiers, must be literalised if they are to occur as are in the generated string. This is to prevent accidental use of letters that may become format specifiers in future versions of the notation.
The following characters will always be literals:
- : , . /
space and all Unicode codepoints beyond U+007F.
- Alignment fields:
-
(Since 0.5)
Square brackets (
[ ]
) can be used to create fields. A field is a piece of formatting that is padded to a specific width. Inside a pair of square brackets, the input consists of up to three parts: the left padding, content and right padding. Either padding part consists of the same literal character one or more times in succession. The total number of padding characters determines the width of the field. The field alignment is determined by which paddings are present:- If there is only right padding, it will be left aligned.
- If there is only left padding, it will be right aligned.
- If there is padding on both sides, it will be centred. If the content cannot be centred exactly, then the output will have one more padding character on the left, unless in the format string the right padding is longer than the left padding, in which case there will be one more padding character on the right.
An alternative is to place a number just inside the square bracket, next to a single padding character. Then the number is the field width. For left-aligned and right-aligned fields, the number must be on the same side as the padding character. For centred fields, the padding character is given on each side, and the side on which the number is placed will receive the extra padding character if the content cannot be centred exactly.
In the unlikely event that you may wish to use a digit as a padding character, it must be literalised.
[------Wwww.....]
This is a centred, eleven-character field containing the name of the day of the week. The generated string will be one of these:
---Sunday.. ---Monday.. --Tuesday.. -Wednesday. --Thursday. ---Friday.. --Saturday.
The format string
[11-Wwww.]
has the same meaning.The content can contain any number of format specifiers and literals. For example:
[d/m/yyy ]HH:ii:ss
creates, if outputting a list of date/time values, a column for the date and a column for the time. Sample output:
24/9/1979 03:05:42 15/11/1983 21:43:05 3/4/991 13:57:24
- Collapsible portions:
-
Curly brackets (
{ }
) can be used to create a collapsible portion. This is a portion that will appear in the output only if at least one of the format specifiers within it actually generates something. Under the current spec, the only conditions in which a format specifier may generate nothing are:- The
B
,b
,BBBB
orbbbb
specifier is used, and the date is AD. - The requested component (or a component required to calculate what is requested) is unspecified in the date/time object being formatted.
- The time zone is not output for any date/time object in which the hour is unspecified.
d Mmm yyy{ B}{ HH:ii:ss zzzz}
Formats the date, and the time if present, with only one space between them whether the date is BC or AD.
{d }{Mmm }yyy BB
For applications in which an exact date, the month and year or just the year may be known, to prevent leading spaces.
HH:ii{:ss}{.FFF}
For applications in which a time is always known to the precision of minutes, but may sometimes be known more precisely.
- The
- See Also:
- the original proposal (includes discussion)
- Since:
- 0.02
- Todo:
- implement timezone TLAs.
- string formatDateTime(const(DateTimeComponents)* dt, string formatString);
Formats dt according to formatString.
- Returns:
- the formatted date string.
- Throws:
- DateTimeFormatException if the formatting fails, e.g. because of an error in the format string. UtfException if formatString is not a correctly-formed UTF-8 string.
- class DateTimeFormatException: object.Exception;
Exception thrown if there was a problem in formatting a date or time.
- immutable string[7u] SHORT_L_DAY_NAME;
Short (three-letter) names of the days of the week.
- immutable string[7u] SHORT_U_DAY_NAME;
Short (three-letter) names of the days of the week.
- immutable string[7u] LONG_L_DAY_NAME;
Full names of the days of the week.
- immutable string[7u] LONG_U_DAY_NAME;
Full names of the days of the week.
- immutable string[13u] SHORT_L_MONTH_NAME;
Short (three-letter) names of the months of the year.
- immutable string[13u] SHORT_U_MONTH_NAME;
Short (three-letter) names of the months of the year.
- immutable string[13u] LONG_L_MONTH_NAME;
Full names of the months of the year.
- immutable string[13u] LONG_U_MONTH_NAME;
Full names of the months of the year.