format-dateTime

The format-dateTime() function returns a formatted representation of a date and time, as a string.

Changes in 2.0

This function is new in XSLT 2.0.

Signature

Argument	Data type	Meaning
dateTime	xs:dateTime?	The date and time to be formatted.
picture	xs:string	A picture string identifying the components to be output and the format in which they are output.
language (optional)	xs:string?	A string following the same rules as the xml:lang attribute in XML, to indicate the language to be used for formatting the date and time. For example, «en » indicates English, «de » German, and «es » Spanish.
calendar (optional)	xs:string?	A string giving a code for the calendar to be used for formatting the date.
country (optional)	xs:string?	A code identifying the country associated with the date and time, for example the country in which the dated event took place.
Result	xs: string?	The formatted date and time.

The last three arguments are optional, but they must either all be supplied, or all be omitted. That is, the function must be called either with two arguments or with five. Calling it with two arguments is equivalent to supplying an empty sequence «() » for each of the last three arguments; an empty sequence for any of these arguments invokes the default value.

Effect

If the dateTime argument is an empty sequence, then the result is an empty sequence.

The Picture Argument

The picture argument consists of a string containing so-called variable markers enclosed in square brackets. Characters outside the square brackets are literal characters to be copied to the result; variable markers within the square brackets indicate components of the date and time to be added to the output string, and the format in which they are to be displayed.

If square brackets are needed as literal characters in the result they should be doubled .

For example, if the picture is given as «[D1 ] / [M1 ] / [Y1{4}] » then the date 1 February 2002 will be displayed as «1/2/2002 » .

Each variable marker consists of a component specifier identifying which component of the date or time is to be displayed; an optional formatting token; an optional presentation modifier ; and finally, an optional width modifier, preceded by a comma if it is present.

The components of the date and time are identified by the following letters .

Letter	Component	Default Format
Y	Year	Four digits
M	Month of year	Numeric 1-12
D	Day of month	Numeric 1-31
d	Day of year	Numeric 1-366
F	Day of week	Name of day (language dependent)
W	Week of year	Numeric 1-53
w	Week of month	Numeric 1-5
H	Hour (24 hours)	Numeric 00-23
h	Hour (12 hours)	Numeric 1-12
P	A.M. or P.M.	Alphabetic (language dependent)
m	Minutes in hour	Numeric 00-59
s	Seconds in minute	Numeric 00-59
f	Fractional seconds	Numeric, one decimal place
Z	Timezone	Numeric, for example +08:00
z	Timezone	GMT+n
C	Calendar	Name of calendar, for example «Old Style »
E	Era	Text or abbreviation describing the baseline from which the year is calculated, for example A.D. or the name of a monarch

The formatting token consists of one or more additional letters or digits. The value can be either a formatting token recognized by the <xsl:number> instruction (see page 359 in Chapter 5), or one of the values «N » , «n » , or «Nn » indicating that the component is to be output by name. Ignoring values such as «a » and «A » that are unlikely to be useful, at least in English, this leaves the following as examples of the possibilities.

Character	Resulting Format	Example
1	Decimal numeric format with no leading zeroes: 1,2,3, ...	1, 2, 3
01	Decimal format, two digits: 01, 02, 03, ...	01, 02, 03
Other Unicode digit	Decimal numeric format, using the set of Unicode digits in which the given digit represents the value one.	, , & pound ;, ,
i	Roman numerals	i, ii, iii, iv
I	Roman numerals	I, II, III, IV
N	Name of component, in upper case	MONDAY, TUESDAY
n	Name of component, in lower case	monday, tuesday
Nn	Name of component, in title case (for example Monday)	Monday, Tuesday
W	Number expressed in upper case words	ONE, TWO, THREE
w	Number expressed in lower case words	one, two, three
Ww	Number expressed in title case words	One, Two, Three

Two presentation modifiers are recognized:

Character	Resulting Format
t	Indicates so-called traditional numbering. The meaning of this depends on the language; it is intended to produce the same effect as « letter-value = " traditional" » in <xsl:number> . The requirement most often cited is for Hebrew numbering.
o	Indicates ordinal numbering. For example, «1o » gives 1st , 2nd , 3rd... , while «wo » gives first , second , third , and «Wwo » gives First , Second , Third . All these examples are of course language dependent: the language is controlled using the language argument.

Not all combinations of these make sense, but the specification leaves it very open to implementations how to interpret combinations other than the obvious ones. The golden rule for this function is that it is never supposed to raise an error-if it doesn't understand the format that you asked for, it should output the date in some fallback format.

The width modifier, if present, indicates how many digits or letters should be included in the result. It takes the form «, m » or «, m-n » , where m is a number giving the minimum width, or «* » to indicate no minimum, and n is the maximum width, or «* » to indicate no maximum. If n is omitted, it is assumed to be equal to m .

Specifying leading zeros in the formatting token is regarded as a shorthand for the width modifier: for example, «01 » is a shorthand for «1, 2 -2 » . For most numeric fields, the width specified controls whether leading zeroes are output: if the minimum width is 2, then the value 8 will be output as 08. The year field is treated specially: a maximum width of 2 indicates that the century should be omitted. The fractional seconds are also handled differently: the minimum and maximum width indicates the minimum and maximum number of decimal places to be output.

For named fields, such as the name of the month and the day of the week, the width modifier controls the choice of abbreviations. For example, specifying «3-3 » requests abbreviations that are exactly three characters long. The specification doesn't say exactly how the abbreviations should be chosen ; some systems might use a dictionary of abbreviated forms (for example JLY for July), while others might use simple truncation of the full name. Names should be padded to the minimum length if they are shorter.

The Language Argument

The language argument defines the language to be used for those parts of the output date that are language dependent. The most obvious examples are the names of the days of the week and the months of the year: for example, if the value is «en » then a date might be output as «Sunday 13 December 1987 » , while with «de » (the code for German) the same date would be «Sonntag 13 Dezember 1987 » . The choice of language is also likely to affect the way the ordinal numbers are represented ( «4th » in English, «4. » in German, and «4 me » in French), and the choice of words or abbreviations equivalent to the English «p.m. » and «A.D. ».

Since the variety of calendars and numbering schemes that implementations might support is completely open ended, it's quite possible that the language attribute might be used in other ways than these, for example to decide between «IV » and «IIII » as the representation of the number 4 in Roman numerals. Implementations are not required to support any particular languages, and the set of languages that are supported is likely to depend on the choice of calendar.

The Calendar Argument

The World Wide Web Consortium takes its name very seriously, and bends over backwards to ensure that it caters for every different society on the planet. While most of the western world, and much of the eastern world, now uses the Gregorian calendar first introduced in the sixteenth century, there are many other calendars still in use.

The XSLT specification defines the following codes that you can use to represent different calendars.

Code	Calendar
AD	Anno Domini (Christian Era)
AH	Anno Hegirae (Muhammedan Era)
AME	Mauludi Era (solar years since Mohammed's birth)
AM	Anno Mundi (Jewish Calendar)
AP	Anno Persici
AS	Aji Saka Era (Java)
BE	Buddhist Era
CB	Cooch Behar Era
CE	Common Era
CL	Chinese Lunar Era
CS	Chula Sakarat Era
EE	Ethiopian Era
FE	Fasli Era
ISO	ISO 8601 calendar
JE	Japanese Calendar
KE	Khalsa Era (Sikh calendar)
KY	Kali Yuga
ME	Malabar Era
MS	Monarchic Solar Era
NS	Nepal Samwat Era
OS	Old Style (Julian Calendar)
RS	Rattanakosin (Bangkok) Era
SE	Saka Era
SH	Mohammedan Solar Era (Iran)
SS	Saka Samvat
TE	Tripurabda Era
VE	Vikrama Era
VS	Vikrama Samvat Era

This looks like a pretty impressive list, but before you get too excited that your favorite calendar is in the list, you should be aware that there is no requirement for implementations to support all these. And even if a calendar is supported, there are snags that you need to be aware of.

The date-formatting functions assume that the date and/or time will be represented using the data types defined in XML Schema, which are based on the ISO 8601 specification. This doesn't mean that you have to be using a schema to take advantage of them, because you can always construct an instance of one of these data types using a call to a constructor function, for example «xs:date (" 1999-11-16") » . It does mean, however, that you have to ensure that your dates and times are in ISO format before you can use these functions. If your XML documents contain dates in nonstandard formats such as «16 NOV 9 9 » or «11 /16 /19 9 9 » , then you are going to have to convert them first to the ISO format. And the same is true if your dates are in a different calendar.

A very common use of these functions is simply to output the current date: for example, «format-dateTime (current-dateTime(),...) » , In this case you don't have to worry about whether the supplied date is in the correct ISO format and calendar: it always will be.

If the calendar argument selects a calendar other than the Gregorian calendar, then the date is translated into that calendar before extracting the relevant component. Not all calendars include concepts directly equivalent to months and weeks (for example, some calendars use lunar months), but most have concepts that are sufficiently similar for this to work. In practice, the handling of non-Gregorian calendars is likely to vary depending on your implementation and is only very loosely described in the XSLT specification.

The numbering of days of the week and weeks of the year may vary from one country or language to another. If you want predictable results, select the «ISO » calendar in the calendar argument. The results will then follow the rules in ISO 8601:

Days of the week are numbered from 1 (Monday) to 7 (Sunday).
Weeks of the year are numbered so that week 1 is the Monday-to-Sunday week that includes the first Thursday of the year. The days before week 1 fall in week 52 or 53 of the previous year.
ISO 8601 does not define a numbering for weeks within a month. You will have to see what your implementation returns.

It's important to understand the distinction in XML Schema between the value space of a data type and the lexical space. The value space for xs:date simply contains one data point for every day in the history of the world, past, present, and future (within limits, but they need not concern us). It's not meaningful to ask whether these data points are represented as integers or strings or to ask what format they are in-or to get to the point, it's not meaningful to ask what calendar they are in. There is a data point representing the day when the Great Fire of London started, and you can represent this data point using any calendar you like. So the value space of dates in XML Schema is calendar neutral.

The same is not true of the lexical space. The lexical representation of dates in XML Schema uses the Gregorian calendar. In fact, it uses the Gregorian calendar even to represent dates that occurred long before the Gregorian calendar was invented: this is referred to as the proleptic Gregorian calendar (ISO 8601 calls it "prolaptic," but that appears to be an error). This simply projects the Gregorian calendar backwards in time. This is really no different from our use of "B.C." dates: we are using a representation of dates that is unrelated to the way those same dates were represented in contemporary records.

This means that if you want to use a non-Gregorian calendar, you have to be very careful. For example, if you are storing a historical document that records that the Great Fire of London broke out on September 2,1666, then if you want to represent this correctly using the xs:date data type you need to know how to convert it into a Gregorian date. In fact, the correct lexical representation of this date is «1666 -09-12 » , as there was then a 10-day difference between the Julian and Gregorian calendars. (Although the Gregorian calendar was introduced in 1585, Britain has always been slow to pick up European ideas, and did not adopt it until 1752.)

If you now want to format this date using the Julian calendar, you can do so by specifying «OS » in the calendar argument. This will produce the correct output ( «Sunday 2nd Sept 1666 » ) only if you represented the date correctly in the value space. If you were careless, and created the date by writing «xs:date(" 1666-09-02") » , then the formatted output will be «Thursday 23rd Aug 1666 » .

I suspect what this means in practice is that if you need to use non-Gregorian calendars, the support provided in XSLT 2.0 may not actually be sufficient for your needs; it allows you to convert dates from the Gregorian calendar to a different calendar, but does not provide a conversion in the reverse direction. There are software utilities available to do that, which could be integrated as extension functions, but if you use them then you may well find that they also offer date formatting capability that is better than that offered by your XSLT processor.

If you ask for a date to be formatted using a calendar that hasn't been implemented, the system will output the date using a calendar of its own choosing (you can be fairly certain this will be the Gregorian calendar) but adding to the output a tag indicating that it is a different calendar from the one that was requested .

The inclusion of «ISO » as a calendar name in this list has a special purpose. Sometimes, you want to format the date not in order to present the information to a human reader, but to pass information to other software. The format-date () function, for example, is the only way available in standard XSLT of finding out the day of the week or the week number in the year. If you want to determine whether a given date is a Sunday, then it would be unfortunate if you had to test the result against a language-dependent string. If you choose ISO as the calendar, then you can do this test as:

  <xsl:variable name="is-Sunday" as="xs:boolean"   select="format-date(current-date() 'F1', (), 'ISO', ()) = '7'"/>

This is because the ISO 8601 standard specifies numeric representations of the days of the week from Monday (1) to Sunday (7). Similarly, you can get the ISO week number by writing:

  <xsl:value-of select="format:-date(current-date(), 'W', (), 'ISO', ())"/>

ISO week numbers (which in some countries are widely used in project planning and similar applications) are chosen so that week 1 is the Monday-to-Sunday week that includes 4th January. Week 1 may thus start before or after 1st January, but always starts on a Monday.

The Country Argument

The country argument allows you to indicate the country associated with the date and time being formatted. For example, if the date and time refer to the death of Erasmus, which took place on July 12, 1536 in Basel , Switzerland, then you can set the country argument to «ch » , which is the ISO country code for Switzerland. The system can use this information to assist in converting Gregorian dates to a date in the chosen calendar, since with many non-Gregorian calendars, different variants of the calendar were in use in different places at different times. For example, although in the old Julian calendar the day and the month were synchronized across much of Europe, New Year's day varied in different countries, so the year number might be different from one country to another.

In some cases, such as the Islamic calendar, the start of a day is tied to sunrise or sunset, so accurate conversion of a date into another calendar requires not only knowledge of the time of day, but also knowledge of where the event took place.

More prosaicly, the country code might be used to determine the abbreviated names of timezones. Names such as EST and PST are recognized in the US, but not necessarily in other English-speaking countries.

The value of the country argument is expected to be an ISO country code, but the use that the system makes of the information is entirely implementation defined. You can always supply an empty sequence as the value of this argument.

Usage and Examples

Here are some examples showing how the date 2003-11-03 might be formatted using various values of the picture argument, assuming the use of the English language and the Gregorian calendar.

Picture	Output
[D]/[M]/[Y]	3/11/2003
[M]/[D]/[Y]	11/3/2003
[MNn] [Do], [Y] [E]	November 3rd, 2003 A.D.
[Y]-[M,2]-[D,2]	2003-11-03
[MN] [YI]	NOVEMBER MMIII
[Y] [[week [W]:[FNn]]]	2003[week 45:Monday]

The following examples show how the time 09:30:02.26-05:00 might be formatted, under the same assumptions. It is possible, of course, to output date and time components at the same time, using a single picture.

Picture	Output
[H01].[m01]	09.30
[h].[m01] [P]	9.30 A.M.
[H01]:[m01]:[s01].[f001] [ZN]	14:30:02.327 EST