Package smjg.libs.util.datetimeformat

Date and time formatting. More...

Variables
	mon
	tue
	wed
	thu
	fri
	sat
const char[3][7]	SHORT_U_DAY_NAME
	Short (three-letter) names of the days of the week.
const char[][7]	LONG_L_DAY_NAME
	Full names of the days of the week.
const char[][7]	LONG_U_DAY_NAME
	Full names of the days of the week.
const char[3][13]	SHORT_L_MONTH_NAME
	Short (three-letter) names of the months of the year.
const char[3][13]	SHORT_U_MONTH_NAME
	Short (three-letter) names of the months of the year.
const char[][13]	LONG_L_MONTH_NAME
	Full names of the months of the year.
const char[][13]	LONG_U_MONTH_NAME
	Full names of the months of the year.

---

Detailed Description

Date and time formatting.

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 or b	BC if necessary
		BB or bb	BC or AD
		BBB or bbb	BCE or CE
		BBBB or bbbb	BCE if necessary
M	Month	m	numeric without leading zero
		mm	numeric with leading zero
		MMM, Mmm or mmm	abbreviated name
		MMMM, Mmmm or mmmm	full name
D	Day of month	d	no leading zero
		dd	leading zero
T	Ordinal suffix	T or t	Ordinal suffix (TH, ND or RD) of last formatted datum
W	Day of week	WWW, Www or www	abbreviated name
		WWWW, Wwww or wwww	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 or a	A or P
		AA or aa	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

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.

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 or bbbb 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.

Examples

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.

See also:

the original proposal (includes some as-yet unimplemented features and discussion)

Since:

0.02

Todo:

Implement timezone TLAs and alignment fields.

---

Variable Documentation

smjg::libs::util::datetimeformat.fri

const char [][7] smjg::libs::util::datetimeformat.LONG_L_DAY_NAME

Initial value:

 [
       DAY_OF_WEEK.SUN: "sunday", "monday", "tuesday", "wednesday",
         "thursday", "friday", "saturday"
]

Full names of the days of the week.

const char [][13] smjg::libs::util::datetimeformat.LONG_L_MONTH_NAME

Initial value:

 [
       null, MONTH.JAN: "january", "february", "march", "april", "may", "june",
       "july", "august", "september", "october", "november", "december"
]

Full names of the months of the year.

const char [][7] smjg::libs::util::datetimeformat.LONG_U_DAY_NAME

Initial value:

 [
       DAY_OF_WEEK.SUN: "SUNDAY", "MONDAY", "TUESDAY", "WEDNESDAY",
         "THURSDAY", "FRIDAY", "SATURDAY"
]

Full names of the days of the week.

const char [][13] smjg::libs::util::datetimeformat.LONG_U_MONTH_NAME

Initial value:

 [
       null, MONTH.JAN: "JANUARY", "FEBRUARY", "MARCH", "APRIL", "MAY", "JUNE",
       "JULY", "AUGUST", "SEPTEMBER", "OCTOBER", "NOVEMBER", "DECEMBER"
]

Full names of the months of the year.

smjg::libs::util::datetimeformat.mon

smjg::libs::util::datetimeformat.sat

const char [3][13] smjg::libs::util::datetimeformat.SHORT_L_MONTH_NAME

Initial value:

 [
       "\xFF\xFF\xFF",
       MONTH.JAN: "jan", "feb", "mar", "apr", "may", "jun",
       "jul", "aug", "sep", "oct", "nov", "dec"
]

Short (three-letter) names of the months of the year.

const char [3][7] smjg::libs::util::datetimeformat.SHORT_U_DAY_NAME

Initial value:

 [
       DAY_OF_WEEK.SUN: "SUN", "MON", "TUE", "WED", "THU", "FRI", "SAT"
]

Short (three-letter) names of the days of the week.

const char [3][13] smjg::libs::util::datetimeformat.SHORT_U_MONTH_NAME

Initial value:

 [
       "\xFF\xFF\xFF",
       MONTH.JAN: "JAN", "FEB", "MAR", "APR", "MAY", "JUN",
       "JUL", "AUG", "SEP", "OCT", "NOV", "DEC"
]

Short (three-letter) names of the months of the year.

smjg::libs::util::datetimeformat.thu

smjg::libs::util::datetimeformat.tue

smjg::libs::util::datetimeformat.wed

---