format-time

(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-time($zeit?, $formatierungsmuster, $sprache?, $kalender?, $verortung?)

$zeit:
Optional. Eine Tageszeitangabe vom Typ xs:time, der eine Zeitzonenan­gabe 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.

$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. 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-time() bestimmt die äußere Form, in der ein ihr übergebener Tageszeitwert xs:time als String xs:string formatiert ausgegeben wird.

Das Aussehen der Formatierung wird durch ein Formatierungsmuster (picture string) bestimmt, das in Stringform als zweites Argu­ment übergeben wird.

Ein Funktionsaufruf ohne eines der drei weiteren möglichen Argumente fordert eine Default­for­matierung entsprechend der Systemumgebung. Dies legt die Wahl des Kalenders fest (z.B. Gregorianisch), und bestimmt die Sprachein­stellung, was unter anderem die Reihenfolge der Kompo­nentenausgabe beeinflusst, wie etwa die Wiedergabe der Stundenwerte (0-23 vs 1-24, 0-11 vs 1-12).

Soll die Formatierung nicht anhand der Defaulteinstellungen 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().

Für die Funktion format-time() gelten folgende Komponentensymbole:

Tabelle: Die Komponentensymbole für format-time().

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, CET für Central European 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:

Alle folgenden Beispiele verwenden einen Tageszeitwert $t vom Typ xs:time, der als Wert eine Tageszeit (mit Zeitzonenangabe) von 15:58:45 + 01:00 angibt. Die Zeitzonenangabe bedeutet UTC+01:00 bzw. CET (Central European Time).

Beispiel 1 – Einfache Uhrzeitangabe:

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

ergibt 15:58.

Hier werden nur die Stunden- und Minutenkomponenten ausgegeben.

Beispiel 2 – Einfache Uhrzeitangabe mit Sekunden:

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

ergibt 15:58:45.

Entspricht Beispiel 1, erweitert um die Ausgabe der Sekundenkomponente.

Beispiel 3 – Angloamerikanische Uhrzeit mit AM/PM-Angabe, Version 1:

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

ergibt 3:58 PM.

Es wird eine Datumsformatierung gemäß den Regeln der mit dem dritten Argu­ment "en" bezeichneten Sprache vorgenommen – in diesem Fall wird die Aus­gabe an die englische Sprache gebunden. Entsprechend wird eine Tageszeit nach angloamerikanischer Konvention ausgegeben. 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 der leere String übergeben wurde.

Aus formalen Gründen wurde ebenfalls für das nicht eingesetzte (fünfte) Veror­tungs-Argument die leere Sequenz übergeben.

Beispiel 4 – Angloamerikanische Uhrzeit mit AM/PM-Angabe, Version 2:

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

ergibt 3:58:45 pm.

Hier wird die AM/PM-Angabe in Kleinbuchstaben ausgegeben (Pn; P mit Modi­fikator n). Es wird auch die Sekundenkomponente verwendet. Ansonsten ent­spricht dies Beispiel 3.

Beispiel 5 – Uhrzeitangabe mit Vor-/Nachmittagsangabe und Zeitzone:

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

ergibt 3:58:45 PM CET.

Die im Wert enthaltene Zeitzonenangabe (UTC+01:00) wird als Zeitzonenbe­zeichner ausgegeben (ZN; Z mit Modifikator N); die Längenbeschränkung (*-3) veranlasst die Verwendung des 3-buchstabigen Kürzels.

Beispiel 6 – Dto. mit Stringliteral, Vor-/Nachmittagsangabe und Zeitzone

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

ergibt 3:58:45 o'clock PM CET.

Hier wird zusätzlich das Stringliteral »o'clock« ausgegeben. Innerhalb des Funk­tionsaufrufs wird der Apostroph besser durch die Entität ' umschrieben, da es sonst zu Kollisionen mit umgebenden Stringbegrenzern kommen kann. In die­sem Fall nicht mit denen des Formatierungsmusters, sondern mit denjenigen, die den gesamten XPath-Ausdruck mit dem Funktionsaufruf innerhalb eines Attributwerts umfassen.

Beispiel 7 – Uhrzeit mit GMT-Zeitzone:

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

ergibt 15:58:45 GMT+01:00.

Hier wird mittels des Platzhaltersymbols z die Ausgabe der Zeitzone bezogen auf GMT (Greenwich Mean Time) gefordert.

Funktionsdefinition:

XSLT 1.0:

Funktion nicht verfügbar

XSLT 2.0: