format-number

(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 1.0

Rückgabewert: Ein String xs:string; die gemäß den Default-Regeln oder einer benannten xsl:decimal-format-Deklaration formatierte Eingabe­zahl

Aufruf/Argumente:

format-number($eingabezahl, $formatierungsmuster, $formatdefinition?)

$eingabezahl:
Obligatorisch. Das erste Argument bestimmt die zu formatie­rende Zahl. In XPath 2.0 muss diese vom Typ xs:double sein. (In XPath 1.0 wird das Eingabeargument gemäß den Regeln von number() in eine Zahl umgewandelt.)

$formatierungsmuster:
Obligatorisch. Das zweite Argument bestimmt das Muster (picture string), das zur Formatierung der übergebenen Zahl verwendet werden soll. Im Wesentlichen wird hier die Stellenzahl von Dezimalzahlen sowie die Anzahl von führenden und folgenden Nullen definiert.

Defaultmäßig wird die Ziffer 0 als Platzhalter für auszugebende führende oder folgende Nullen eingesetzt (zero-digit-sign) und das Hashzeichen # als Platzhalter für beliebige Ziffern an Stellen, wo deren Ausgabe entfallen kann (digit-sign). Bei Bedarf können aber in einer Formatdeklaration durch xsl:decimal-format auch andere Zeichen für diese Rollen festgelegt werden.

$formatdefinition:
Optional. Das dritte Argument besteht aus dem QName einer durch xsl:decimal-format deklarierten Formatdefinition. In einer sol­chen Definition werden die bei der Stringausgabe zu verwendenden Zeichen für Dezimaltrenner, Tausendertrennzeichen sowie NaN und weitere festgelegt. Die Formatdefinition durch xsl:decimal-format hat keinen Einfluss auf die Form des als Formatierungsregel übergebenen zweiten Arguments, bestimmt aber die dort verwendbaren Zeichensymbole.

Verwendungszweck:

Ein Formatierungsmuster (picture string) besteht aus einem optionalen Präfix, dem Formatierungsstring und einem optiona­len Suffix.

Der Formatierungsstring des Formatierungsmusters:

Der Formatierungsstring setzt sich aus den Platzhaltern für Ziffern der Vorkom­mastellen mit eventuellen Gruppierungsymbolen, dem Dezimaltrennsymbol und weiteren Platzhaltern für Nachkommastellen zusammen. Die hier verwendbaren Zeichen können in den entsprechenden Attributen der Deklaration vereinbart werden – ansonsten treten die jeweiligen Defaultwerte in Kraft.

'###,###,000.0###'

Defaultwerte sind, entsperechend der amerikanischen Zahlenformatierung, das Komma als Gruppierungszeichen sowie der Punkt als Dezimaltrenner. Für die Formatierung von Zahlen nach westeuropäi­schem Muster muss daher eine xsl:decimal-format-Deklaration wie folgt zu Hilfe genommen werden, die eine entsprechende Vertauschung vornimmt:

Die Ziffer 0 bzw. das im zero-digit-Attribut definierte Zeichen dient im For­matpattern als Platzhalter für Stellen, die im Ausgabestring mit Nullen aufge­füllt werden sollen, falls ihnen keine Ziffer größer 0 zugeordnet werden kann. So konnen gleichermaßen führende wie folgende Nullen erzwungen werden.

Das #-Zeichen bzw. das im digit-Attribut definierte Zeichen dient als Platzhal­ter für Stellen, die im Ausgabestring entfallen können, falls ihnen keine Ziffer größer 0 zugeordnet werden kann.

Es werden in keinem Fall mehr Nachkommastellen ausgegeben als im Forma­tierungsstring vorgesehen. Überschüssige Stellen entfallen, die letzte ausgege­bene Stelle wird entsprechend gerundet.

Präfix und Suffix des Formatierungsmusters:

Für Präfix und Suffix des Formatierungsstrings dürfen beliebige Zeichen (auch Leerzeichen sind signifikant!) verwendet werden, jedoch nicht diejenigen, die für den Formatierungsstring vereinbart sind. Bei der Formatierung werden Prä­fix und Suffix unverändert in den Ergebnisstring übernommen und der forma­tierten Zahl voran- bzw. nachgestellt. Es findet keine Normalisierung statt, d.h., auch führende Leerzeichen gelangen in den Ausgabestring.

'Mein Präfix: ##00.0### mein Suffix'

Zur Formatierung einer negativen Zahl wird dieser das im Attribut minus-sign vereinbarte Vorzeichen vorangestellt. Die Stringumwandlung erfolgt ansonsten anhand des Formatierungsmusters.

Alternativ hierzu können innerhalb des Formatierungsstrings zwei Subforma­tierungsmuster definiert werden, von denen das zweite zur Formatierung nega­tiver Zahlen herangezogen wird. Als Trennsymbol zwischen den Submustern dient das Semikolon, sofern nicht im Attribut pattern-separator einer ver­knüpften Formatdeklaration ein anderes Zeichen vereinbart wurde:

'##.00;minus ##.00'

Steht ein Submuster für negative Zahlen zur Verfügung, so entfällt die Verwen­dung des Vorzeichens im Ausgabestring (es sei denn, es ist im Submuster expli­zit vorgesehen).

Auch Submuster können jeweils Prä- und Suffixe besitzen. Das (unwillkürliche und rein optisch gemeinte) Trennen der Subgruppen durch Leerzeichen ist feh­lerträchtig, da Leerzeichen auch hier als signifikant gelten:

-5 mit '##.00;minus ##.00' ergibt: minus 5.00

Hier ist im Formatierungsstring ein Leerzeichen eingewandert:

-5 mit '##.00; minus ##.00' ergibt: _minus 5.00

Das ungewollt ausgegebene Leerzeichen wird im obigen Beispiel durch den Unterstrich symbolisiert. Auch hier findet keine Normalisierung statt.

Beispiele:

Beispiel 1 – Erzwingen von zwei Vorkomma- und einer Nachkommastelle:

Tabelle: Formatierung mit Formatsstring '##00.0###'.

Beispiel 2 – Beschränkung auf zwei Nachkommastellen (mit Rundung)

Tabelle: Formatierung mit Formatsstring '##.##'.

Beispiel 3 – Erzwingen von zwei Dezimalstellen nach dem Komma:

Tabelle: Formatierung mit Formatsstring '##.00'.

Beispiel 4 – Verwendung von Submustern für negative Zahlen:

Tabelle: Formatierung mit Formatsstring '##.00;minus ##.00'.

Anmerkung: Für negative Eingabewerte erfolgt aufgrund des Submusters keine Ausgabe des Minuszei­chens.

Beispiel 5 – Verwendung eines Suffixes (hier in Form einer Maßeinheit):

Tabelle: Formatierung mit Formatsstring '##.00 cm'.

Beispiel 6 – Verwendung von Präfix, Suffix und Submustern:

Tabelle: Formatierung mit Formatsstring 'Gewinn: ##.00 Euro;Verlust: ##.00 Euro'.

Querverweis:
Beispiele unter Einbeziehung einer Formatdeklaration befin­den sich in der Referenz zu den XSLT-Instruktionen bei xsl:decimal-format.

Funktionsdefinition:

XSLT 1.0:

format-number(eingabezahl, 
              formatierungsmuster, 
              formatdefinition?) => string

XSLT 2.0:

format-number(eingabezahl as xs:double, 
              formatierungsmuster as xs:string,
              formatdefinition? as xs:string) as string

Mögliche Kompatibilitätsprobleme XSLT 2.0 zu XSLT 1.0:
Geringfügig. Die Funktion verlangt unter XSLT 2.0 bei Angabe einer Formatdeklaration xsl:decimal-format auch deren tatsächliches Vorhandensein; auch muss der Bezeichner (lexikalisch) ein gültiger QName sein. Ein Fehler führt zum Ignorie­ren des entsprechenden Arguments. Die Deklaration xsl:decimal-format wurde unter XSLT 2.0 in Bezug auf sprachbedingte Darstellung und andere Details erweitert. Dies betrifft unter anderem auch die Position eines Vorzeichens bei gleichzeitig auszugebendem Präfixstring (Vorzeichen in XSLT 1.0 nach dem Präfix, in XSLT 2.0 davor.)