format-dateTime

(Auszug aus "XSLT 2.0 & XPath 2.0" von Frank Bongers, Kapitel 5.)

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

Kategorie: Typkonvertierung und Ausgabeformatierung

Herkunft: XSLT 2.0

Rückgabewert: Ein String xs:string; der anhand eines Musterstrings und weiteren optional zu übergebenden Parametern formatierte Eingabewert

Aufruf/Argumente:

format-dateTime($zeitstempel?, $formatierungsmuster, $sprache?, $kalender?, $verortung?)

$zeitstempel:
Optional. Ein Zeitstempelwert vom Typ xs:dateTime, der eine Zeitzonenangabe beinhalten kann. Wird kein Wert übergeben, also die leere Sequenz, so gibt die Funktion diese zurück.

$formatierungsmuster:
Obligatorisch. Eine Zeichenkette xs:string, die in Form eines vorgegebenen Musters (picture string) die Formatierung der resul­tierenden Zeichenkette bestimmt (ausführliche Erläuterung siehe format-date()).

$sprache:
Optional. Eine Zeichenkette xs:string in Form eines aus zwei Zeichen bestehenden Kürzels einer Landesbezeichnung nach ISO 3166-1. Durch den dritten Parameter kann eine Sprache für die Formatierung des Datumsstrings bestimmt werden. Dies hat unmittelbar Auswirkung auf die als Namen von Wochentagen oder Monaten gewählten Bezeichner, gegebenen­falls auch auf die Reihenfolge der Ausgabe der Komponenten des Datumswer­tes. Die entsprechenden Bezeichner und üblichen Abkürzungen müssen dem System zur Verfügung stehen.

$kalender:
Optional. Eine Zeichenkette xs:string in Form einer aus Groß­buchstaben bestehenden Kurzbezeichnung desjenigen Kalenders, der der For­matierung zugrunde gelegt werden soll. Defaultwert ist der Kalender nach ISO (entspricht dem Gregorianischen Kalender), dessen Unterstützung vorgeschrie­ben ist. Der Defaultkalender tritt auch bei der Übergabe des leeren Strings oder der leeren Sequenz für $kalender in Kraft. Die Unterstützung weiterer Kalender ist implementationsabhängig.

$verortung:
Optional. Eine Zeichenkette xs:string in Form eines aus zwei Zeichen bestehenden Kürzels einer Landesbezeichnung nach ISO 3166-1. Die­ser zur Sprachangabe redundant erscheinende Parameter dient dazu, den zu formatierenden Wert geographisch zu verorten und die Formatierung der Zeit­angabe gemäß dieser Verortung zu modifizieren.

Verwendungszweck:

Die Funktion format-dateTime() bestimmt die äußere Form, in dem ein ihr übergebener Zeitstempelwert xs:dateTime als String xs:string formatiert ausgegeben wird.

Zur Bestimmung des Aussehens der Formatierung wird ein, als zweites obliga­torisches Argument, übergebener String zu Hilfe genommen, und im Sinne eines Formatierungsmusters (pic­ture string) eingesetzt.

Ein Funktionsaufruf ohne weitere Argumente bezieht sich auf die Defaultfor­matierung. Diese wird entsprechend der Systemumgebung vorgenommen. Betroffen ist die Wahl des Kalenders (z.B. Gregorianisch) und der Sprachein­stellung. Letztere hat unter anderem Einfluss auf die Reihenfolge der Kompo­nentenausgabe oder bei Tageszeitausgabe auf die Wiedergabe der Stunden­werte (0-23 vs 1-24, 0-11 vs 1-12).

Soll die Formatierung nicht anhand der Default-Einstellungen vorgenommen werden, so können mittels zweier weiterer optionaler Argumente eine expli­zite Spracheinstellung sowie der zugrunde gelegte Kalender spezifiziert wer­den. Ein fünftes (umstrittenes) Argument ist dafür vorgesehen, die Formatie­rung eines Wertes an einen geographischen Ort zu binden.

Weitere Erläuterungen bei format-date()
Eine ausführliche Erläuterung zu Formatierungsmuster, Kompo­nenten­platzhalter und Präsentationsmodifikatoren sowie zum Kalender­argu­ment finden Sie bei der Funktion format-date().

Da ein Zeitstempelwert xs:dateTime sowohl alle Datums- als auch alle Tageszeitkomponenten enthält, dürfen im Formatierungsmuster alle vereinbarten Komponentensymbole eingesetzt werden.

Tabelle: Komponentensymbole des Formatierungsmusters.

Die beiden Zeitzonensymbole werden wie folgt interpretiert:

Z steht für eine Zeitzonenangabe bezogen auf UTC-Zeit, die entweder numerisch als Zeitdifferenz ausgegeben werden kann, oder, mit Modifikator N, durch ZN als Zeitzonenbezeichner (z.B. EST für Eastern Standard Time). Besteht keine Differenz (die Zeitangabe liegt bereits in UTC vor), so wird dies durch den Buchstaben Z symbolisiert.

z steht für eine Zeitzonenangabe bezogen auf GMT-Zeit, die als Zeitdifferenz, in der Form GMT ± [hh:00] präsentiert wird, beispielsweise GMT +2:00.

Beispiele:

Beispiel 1 – Einfache Zeitstempelformatierung, Version 1

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

ergibt: 2007-12-31 15:58

In diesem Fall werden einfach die Zahlenwerte der jeweiligen Komponenten entnommen und in entsprechender Reihenfolge mit den vorgesehenen String­literalen versehen ausgegeben.

Beispiel 2 – Einfache Zeitstempelformatierung, Version 2:

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

ergibt: 12-31-2007

Prinzipiell eine Variante von Beispiel 1. Die Reihenfolge der Ausgabe entspricht der Reihenfolge der Platzhalter im Musterstring. Die Tageszeit­ausgabe wurde erweitert um die Ausgabe der Sekundenkomponente.

Beispiel 3 – Einfache Zeitstempelformatierung, Version 3:

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

ergibt: 31. 12. 2007, 15:58:45 Uhr

Hier werden andere Stringliterale verwendet. Die Ausgabe entspricht der Kon­vention im deutschen Sprachraum, wird aber nicht über eine Datumsformatde­klaration mit language-Attribut erreicht, sondern unmittelbar durch die Form des Musterstrings.

Beispiel 4 -Datumsformatierung mit Datumsformatdeklaration (1):

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

ergibt: 31st December, 2007; 3:58 PM

Das Teilmuster [D1o] gibt den Tag mit Ordinal aus. Da dies durch den sekundären Modi­fikator o bewirkt wird, muss dem D auch die 1, obwohl nicht in diesem Sinne »modifizierend«, als primärer Modifikator beigegeben werden (D1o; D mit 1 als primärem und o als sekundärem Modifikator).

Die Monatsnamen werden gemäß den Regeln der mit dem dritten Argument "en" bezeichneten Sprache als Bezeichner mit Groß- und Kleinbuchstaben aus­gegeben (Mn; M mit Modifikator n).

Entsprechend erfolgt auch die Tageszeitausgabe nach angloamerikanischer Konvention Die AM/PM-Angabe wird mit Großbuchstaben vorgenommen (PN; P mit Modifikator N), der Stundenwert angepasst (3 statt 15).

Es wird der Defaultkalender verwendet, da für das calendar-Argument die leere Sequenz übergeben wurde. Für das nicht verwendete (fünfte) Veror­tungs-Argument wird aus formalen Gründen ebenfalls die leere Sequenz übergeben.

Beispiel 5 – Datumsformatierung mit Datumsformatdeklaration (2):

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

ergibt: Onsdag 31 December 2007, 15:58:45 GMT+01:00

Der Funktionsaufruf bestimmt Schwedisch "sv" als Formatierung. Der Prozessor muss also die Ausgabe in schwedischer Sprache entsprechend unterstützen, sonst schlägt der Funktionsaufruf fehl.

Die Ausgabe der Tageszeitkomponenten ist konventionell. Hier wird mittels des Platzhaltersymbols z die Ausgabe der Zeitzone bezogen auf GMT (Green­wich Mean Time) gefordert.

Da das (vierte) calendar-Argument ebenfalls leer ist, gilt der Defaultka­lender »Gregorian«. Das fünfte Argument wurde weggelassen.

Funktionsdefinition:

XSLT 1.0:

Funktion nicht verfügbar

XSLT 2.0: