XSLT and XPath function reference in alphabetical order

(Excerpt from “XSLT 2.0 & XPath 2.0” by Frank Bongers, chapter 5, translated from German)

A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z

format-dateTime

Category:

Type conversion and output formatting

Origin:

XSLT 2.0

Return value:

A xs:string string; the input value formatted by means of a pattern string and further parameters to be optionally passed on.

Call/Arguments:

format-dateTime($timestamp?, $formattingPattern, $language?, $calendar?, $location?)

$timestamp:

Optional. A timestamp value of xs:dateTime type which may contain a timezone indication. If the no value is passed on, which means the empty sequence, the function returns the empty sequence.

$formattingPattern:

Obligatory. A xs:string character string which determines the formatting of the resulting character string in the form of a preset pattern (picture string).

$language:

Optional. A xs:string character string in the form of a country code consisting of two characters according to ISO 3166-1. By the third parameter, a language for the formatting of the data string can be determined. This has a direct effect on the identifiers selected as names of weekdays and months, where applicable, also on the order of the outputted components of the date value. The appropriate identifers and the abbreviations in common use must be available for the system.

$calendar:

Optional. A xs:string character string in the form of an abbreviation consisting of capital letters of that calendar which shall be taken as a basis of the formatting. The default value is that calendar according to ISO (according to the Gregorian calendar) whose support is required. The default calendar also becomes effective when passing on the empty string or the empty sequence for $calendar. The support of further calendars depends on the implementation.

$location:

Optional. A xs:string character string in the form of a country code consisting of two characters according to ISO 3166-1. This parameter seeming redundant with regard to the language indication is used in order to geographically locate the value to be formatted and to modify the formatting of the time indication according to this location.

Purpose of use:

The format-dateTime() function determines the outer form in which a xs:dateTime timestamp value passed on is outputted formatted as xs:string string.

In order to determine the appearance of the formatting, a string passed on as second obligatory argument is used and applied in the sense of a formatting pattern (picture string).

A function call without any further arguments refers to the default formatting which is performed according to the system environment. The choice of the calendar (e.g. Gregorian) and the choice of the language setting is concerned. The latter has, for example, influence on the order of the component output or when outputting the daytime, influence on the display of the hour values (0–23 vs. 1–24, 0–11 vs. 1–12).

If the formatting shall not be performed by means of the default settings, an explicit language setting as well as the underlying calendar can be specified by two further optional arguments. A fifth (controversial) argument is used to bind the formatting of a value to a geographical location.

Further explanations can be found at format-date()
A detailed explanation on formatting patterns, component wildcards and presentation modifiers as well as on the calendar argument can be found at the format-date() function.

Since a xs:dateTime timestamp value contains all date as well as all daytime components, all agreed component symbols can be used in the formatting pattern.

Symbol	Component	Presentation	Example
Y	year	numerical	2003
M	month (related to the year)	numerical	12
D	day (related to the month)	numerical	30
d	day (related to the year)	numerical	365
F	day (weekday)	identifier	Friday
W	week (calendar week)	numerical	52
w	week (of the month)	numerical	3
H	hour (24-hours day)	numerical	23
h	hour (2 x 12-hours day)	numerical	10
P	AM/PM indication	identifier	AM
m	minute (related to the hour)	numerical	59
s	second (related to the minute)	numerical	30
f	seconds with fraction	numerical	59.99
Z	UTC timezone	duration	+ 2:00
z	GMT timezone	identifier + duration	GMT + 2:00
C	calendar used	identifier	Gregorian
E	reference era	identifier	[name of ruler]

Table: component symbols of the formatting pattern

The two timezone symbols are interpreted as follows:

Z stands for a timezone indication related to UTC time which can be outputted numerically as time difference or with the N modifier by ZN as timezone identifier (e.g. EST for Eastern Standard Time). If there is no difference (the time indication is already available in UTC), this is symbolised by the letter Z.

z stands for a timezone indication related to GMT time which is presented as time difference in the form GMT ± [hh:00], for example GMT +2:00.

Example 1 - simple timestamp formatting, version 1:

format-dateTime($dt,"[Y]-[M]-[D] [H]:[m]")

Results in: 2007-12-31 15:58.

In this case the number values of the respective components are simply extracted and outputted in the appropriate order provided with the string literals.

Example 2 - simple timestamp formatting, version 2:

format-dateTime($dt,"[M]-[D]-[Y] [H]:[m]:[s]")

Results in: 12-31-2007 15:58:45.

In principle, a variant of example 1. The order of the output corresponds to the order of the wildcards in the pattern string. The daytime output was extended by the output of the seconds component.

Example 3 - simple timestamp formatting, version 3:

format-dateTime($dt,"[D]. [M]. [Y], [h]:[m]:[s] Uhr")

Results in: 31. 12. 2007, 15:58:45 Uhr.

In this example, other string literals are used. The output corresponds to the convention in the German-speaking area. However, it is not achieved via a date format declaration with the language attribute, but directly by the form of the pattern string.

Example 4 - date formatting with date format declaration (1):

format-dateTime($dt,"[D1o] [Mn], [Y]; [h]:[m] [PN]",

"en", (), ())

Results in: 31st December, 2007; 3:58 PM.

The [D1o] subpattern outputs the day with ordinal »st«. Since this is caused by the secondary modifier o, the 1 must be added to the D, although not in this sense »modifying«, as primary modifier (D1o; D with 1 as primary and o as secondary modifier).

The names of the months are outputted according to the rules of the language indicated with the third argument "en" as identifiers with capital and small letters (Mn; M with modifier n).

Accordingly, the daytime is outputted according to the Anglo-American convention. AM and PM are indicated with capital letters (PN; P with modifier N), the hour value is adapted (3 instead of 15).

The default calender is used, because the empty string was passed on for the calendar argument. For the not used (fifth) location argument also the empty sequence is passed on for formal reasons.

Example 5 - date formatting with date format declaration (2):

format-dateTime($dt,"[Fn] [D] [Mn] [Y], [H]:[m]:[s] [z]",

"sv", (), ())

Results in: Onsdag 31 December 2007, 15:58:45 GMT+01:00.

The function call determines Swedish "sv" as formatting. The processor must support the output accordingly in the Swedish language, otherwise the function call fails.

The output of the daytime components is conventional. Here, the output of the timezone related to GMT (Greenwich Mean Time) is required by means of the wildcard symbol z.

Since the (forth) calendar argument is also empty, the »Gregorian« default calendar applies. The fifth argument was omitted.

Function definition:

XSLT 1.0:

The function is not available.

XSLT 2.0:

format-dateTime($value as xs:dateTime?,

$picture as xs:string) as xs:string?

format-dateTime($value as xs:dateTime?,

$picture as xs:string,

$language as xs:string?,

$calendar as xs:string?,

$country as xs:string?) as xs:string?

   

<< back

next >>