fn:format-dateTime
format-dateTime($value as xs:dateTime?, $picture as xs:string) ➔ xs:string?
Formats a dateTime, using a format controlled by the picture string. The result is equivalent to the 5-argument form of the function, with the third, fourth, and fifth arguments set to an empty sequence.
Arguments | |||
| $value | xs:dateTime? | The dateTime to be formatted |
| $picture | xs:string | Picture showing how the dateTime is to be formatted |
Result | xs:string? |
format-dateTime($value as xs:dateTime?, $picture as xs:string, $language as xs:string?, $calendar as xs:string?, $place as xs:string?) ➔ xs:string?
Formats a dateTime, using a format controlled by the picture string.
Arguments | |||
| $value | xs:dateTime? | The dateTime to be formatted |
| $picture | xs:string | Picture showing how the dateTime is to be formatted |
| $language | xs:string? | The language for the output |
| $calendar | xs:string? | The calendar for the output |
| $place | xs:string? | The country or Olson timezone where the event took place |
Result | xs:string? |
Namespace
http://www.w3.org/2005/xpath-functions
Links to W3C specifications
XPath 3.0 Functions and Operators
XPath 3.1 Functions and Operators
Notes on the Saxon implementation
Formats a date, using a format controlled by the picture string. If no language is
specified, the value is taken from the current Java locale. If the language (explicitly
supplied or defaulted) is other than en
, the system tries to locate a
localization class for the language (called, for historic reasons, a Numberer);
this class must provide methods to perform the localization.
Support for English (language="en"
) is built-in in all versions of the
product.
In Saxon-PE and Saxon-EE, support for a variety of other languages is provided by facilities from the ICU - International Components for Unicode. For full details see Numbers and Dates from ICU.
Details of additional numbering support for several European languages: specifically
da
, de
, fr
, fr_BE
, he
,
it
, nl
, nl_BE
, and sv
, can be found
in Numberings for
selected languages. These features are used by Saxon-PE/EE in the absence of a
loaded ICU library. They are not built in with Saxon-HE, but are available as open source
code, and it is possible to configure them by writing a subclass of LocalizerFactory and registering it with
the Configuration.
Localization modules for other languages can be configured. They are written to implement
the interface Numberer, typically
as subclasses of AbstractNumberer. In Saxon-HE they are configured as described
above. In Saxon-PE and
Saxon-EE they can be registered in one of two ways: programmatically using the call
Configuration.getLocalizerFactory().setLanguageProperties("ja", props))
where props
is a Properties
object in which the
class
property is set to the name of the relevant Numberer
class; or by setting an entry in the configuration file. For more information on writing localization modules, see Localizing numbers and dates.
If a calendar other than AD or ISO is specified, the result is prefixed "[Calendar: AD]" and is otherwise output as if the default calendar were used.
The country argument is currently used only when the format requests output of timezones
by name (using [ZN]
): for example with language="en",
country="gb"
and a date that falls in British Summer Time, +01:00 is output as
"BST". This is problematic, because the information is not really available: the data type
maintains only a time zone offset, and different countries (time zones) use different
names for the same offset, at different times of year. If the value is a date or dateTime,
and if the country argument is supplied, Saxon uses the Java database of time zones and
daylight savings time (summer time) changeover dates to work out the most likely timezone
applicable to the date in question.
If the timezone is formatted as [ZN,6]
(specifically, with a minumum length
of 6 or more) then the Olsen timezone name is output (again, this requires the country to
be supplied). The Olsen timezone name generally takes the form
Continent/City
, for example Europe/London
or
America/Los_Angeles
. If the date/time is in daylight savings time for that
timezone, an asterisk is appended to the Olsen timezone name.
When formatting times in the 12-hour clock, with language="en"
, the
abbreviations "a.m." and "p.m." are used. These can be shortened to "am" and "pm" by
giving a maximum width of 2 ([PN,*-2]
). The US convention of denoting noon as
"pm" and midnight as "am" is followed, unless the maximum width is 8 or more
([PN,*-8]
) in which case these values are represented as "noon" and
"midnight" respectively.
The rules for formatting of timezones have been clarified and extended in the XPath 3.0 version of the specification. These changes are implemented in 9.5, and apply whether or not support for XPath 3.0 is enabled.