XSLT 2.0 and XPath 2.0 Programmer's Reference, 4th Edition (566 page)

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:

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:

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. It's probably not a good idea to ask for time zone names, however. The
xs:dateTime
type simply doesn't have this information. Within a limited range of dates and countries, the system might be able to work out that the time zone displacement -04:00 refers to US Eastern Daylight Time; but this doesn't work if the time is supplied without a date, if the country is unknown, or if the date is in the future (as many US citizens discovered in 2007, the dates for daylight savings time changes are set by governments as they see fit).

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 2008-11-03 might be formatted using various values of the
picture
argument, assuming the use of the English language and the Gregorian calendar.

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.

See Also

day-from-date()
,
day-from-dateTime()
on page 744

month-from-date()
,
month-from-dateTime()
on page 833

year-from-date()
,
year-from-dateTime()
on page 911

hours-from-time()
,
hours-from-dateTime()
on page 800

minutes-from-time()
,
minutes-from-dateTime()
on page 832

seconds-from-time()
,
seconds-from-dateTime()
on page 873

timezone-from-date()
,
timezone-from-dateTime
,
timezone-from-time()
on page 893

format-number

This function is available in XSLT only
.

The
format-number()
function is used to convert numbers into strings for display to a human user. It is also useful when converting to legacy formats that require a number to occupy a fixed number of character positions. The format of the result is controlled using the

declaration in an XSLT stylesheet.

For example, the expression
format-number(12.5, ‘$#0.00’)
returns the string
$12.50
.