format-time

format-time

The format-time() function is used to output a time of day in human-readable format.

Changes in 2.0

This function is new in XSLT 2.0.

Signature

Argument	Data Type	Meaning
time	xs:time?	The 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. 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 time.
country (optional)	xs:string?	A code identifying the country associated with the time, for example the country in which the timed event took place.
Result	xs:string?	The formatted 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 $time argument is an empty sequence, then the result is an empty sequence.

The $picture string may contain a number of component specifiers, identifying the components to be output. These are described in detail in the section format-dateTime() , page 550 earlier in the chapter. If the $picture argument includes component specifiers that are not appropriate to a time value (for example, the year, month, and day components) then the processor may either report a runtime error, or simply ignore those component specifiers.

Apart from this, the effect of the function is the same as that of casting the $time value to an xs:dateTime (which gives the xs:dateTime representing that time on the current date) and calling format-dateTime() with the same value of the $picture argument, and the same value of the $format argument if it is present.

Usage and Examples

The main use of this function is in producing a time formatted for human readers. For example:

  format-time(xs:time('15:30:00'), '[h].[m01] [Pn]')  

typically produces the output:

  3.30 p.m.  

This is assuming that default language is English.

Full details of the picture string and the other arguments are provided under format-dateTime() page 550 earlier in the chapter.

See Also

• format-date () on page 548.

• format-dateTime() on page 550.