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-time

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-time($time?, $formattingPattern, $language?, $calendar?, $location?)

$time:

Optional. A daytime indication of xs:time 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 (corresponds to the Gregorian calendar) whose support is required. 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-time() function determines the outer form in which a xs:time daytime value passed on is outputted formatted as xs:string string.

The appearance of the formatting is determined by a formatting pattern (picture string) passed on in string form as second argument.

A function call without one of the three other possible arguments requires a default formatting according to the system environment. This determines the choice of the calendar (e.g. Gregorian) and the language setting. The latter has, for example, influence on the order of the component output, such as the rendering 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.

For the format-time() function, the following component symbols apply:

SymbolComponentPresentationExample
Hhour (24-hours day)numerical23
hhour (2 x 12-hours day)numerical10
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 + numerical GMT + 2:00

Table: the component symbols for format-time()

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, CET for Central European 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.

The following examples use a $t daytime value of xs:time type which indicates as value a daytime (with timezone indication) of 15:58:45 + 01:00. The timezone indication means UTC + 01:00 or CET.

Example 1 - simple time indication:

format-time($t,"[H]:[m]")

Results in: 15:58.

In this example, only the hour and minutes components are outputted.

Example 2 - simple time indication with seconds:

format-time($t,"[H]:[m]:[s]")

Results in: 15:58:45.

This case corresponds to example 1, extended by the output of the seconds component.

Example 3 - Anglo-American time with AM/PM indication, version 1:

format-time($t,"[h]:[m] [PN]", "en", (), ())

Results in: 3:58 PM.

The date is formatted according to the rules of the language indicated with the third argument "en" - in this case, the output is bound to the English language. Accordingly, a 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 4 - Anglo-American time with AM/PM indication, version 2:

format-time($t,"[h]:[m]:[s] [Pn]", "en", (), ())

Results in: 3:58:45 pm.

In this example, the AM/PM indication is outputted in small letters (Pn; P with modifier n). The seconds component is also used. In other respects, this corresponds to example 3.

Example 5 - time indication with AM/PM indication and timezone:

format-time($t,"[h]:[m]:[s] [PN] [ZN,*-3]", "en", (), ())

Results in: 3:58:45 PM CET.

The timezone indication (UTC + 01:00) contained in the value is outputted as timezone identifier (ZN; Z with modifier N); the length restriction (*-3) causes the usage of the three-letter abbreviation.

Example 6 - time with string literal, AM/PM indication and timezone:

format-time($t,"[h]:[m]:[s] o'clock [PN] [ZN,*-3]", "en", (), ())

Results in: 3:58:45 o'clock PM CET.

Here, in addition, an »o'clock« string literal is outputted. Within the function call, it is better to transcribe the apostrophe by the ' entity, since otherwise collisions with the surrounding string delimiters could occur. In this case, not with the string delimiters of the formatting pattern, but with the ones surrounding the entire XPath expression with the function call within an attribute value.

Example 7 - time with GMT timezone:

format-time($t,"[H]:[m]:[s] [z]")

Results in: 15:58:45 GMT + 01:00.

In this example, the output of the timezone with regard to GMT (Greenwich Mean Time) is required by means of the z wildcard symbol.

Function definition:

XSLT 1.0:

The function is not available.

XSLT 2.0:

format-time($value as xs:time?

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

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

$picture as xs:string,

$language as xs:string?,

$calendar as xs:string?,

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

   

<< back next >>

 

 

 


Copyright © Galileo Press, Bonn 2008
Printing of the online version is permitted exclusively for private use. Otherwise this chapter from the book "XSLT 2.0 & XPath 2.0" is subject to the same provisions as those applicable for the hardcover edition: The work including all its components is protected by copyright. All rights reserved, including reproduction, translation, microfilming as well as storage and processing in electronic systems.


Galileo Press, Rheinwerkallee 4, 53227 Bonn, Germany