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 Eingabezahl
Aufruf/Argumente:
format-number($eingabezahl, $formatierungsmuster, $formatdefinition?)
$eingabezahl:
Obligatorisch. Das erste Argument bestimmt die zu formatierende 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 solchen 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 optionalen Suffix.
Der Formatierungsstring des Formatierungsmusters:
Der Formatierungsstring setzt sich aus den Platzhaltern für Ziffern der Vorkommastellen 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äischem Muster muss daher eine xsl:decimal-format-Deklaration wie folgt zu Hilfe genommen werden, die eine entsprechende Vertauschung vornimmt:
<xsl:decimal-format name="westeuropa" decimal-separator=',' grouping-separator='.' />
Die Ziffer 0 bzw. das im zero-digit-Attribut definierte Zeichen dient im Formatpattern als Platzhalter für Stellen, die im Ausgabestring mit Nullen aufgefü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 Platzhalter 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 Formatierungsstring vorgesehen. Überschüssige Stellen entfallen, die letzte ausgegebene 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 formatierten 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 Subformatierungsmuster definiert werden, von denen das zweite zur Formatierung negativer Zahlen herangezogen wird. Als Trennsymbol zwischen den Submustern dient das Semikolon, sofern nicht im Attribut pattern-separator einer verknüpften Formatdeklaration ein anderes Zeichen vereinbart wurde:
'##.00;minus ##.00'
Steht ein Submuster für negative Zahlen zur Verfügung, so entfällt die Verwendung des Vorzeichens im Ausgabestring (es sei denn, es ist im Submuster explizit vorgesehen).
Auch Submuster können jeweils Prä- und Suffixe besitzen. Das (unwillkürliche und rein optisch gemeinte) Trennen der Subgruppen durch Leerzeichen ist fehlerträ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:
<xsl:value-of select="format-number($number,'##00.0###')"/>
Eingabewert | Ausgabewert |
---|---|
-5 | -05.0 |
-3.895 | -03.895 |
1.63 | 01.63 |
467.531 | 467.531 |
Tabelle: Formatierung mit Formatsstring '##00.0###'.
Beispiel 2 – Beschränkung auf zwei Nachkommastellen (mit Rundung)
<xsl:value-of select="format-number($number,'##.##')"/>
Eingabewert | Ausgabewert |
---|---|
-5 | -5 |
-3.895 | -3.9 |
1.63 | 1.63 |
467.531 | 467.53 |
Tabelle: Formatierung mit Formatsstring '##.##'.
Beispiel 3 – Erzwingen von zwei Dezimalstellen nach dem Komma:
<xsl:value-of select="format-number($number,'##.00')"/>
Eingabewert | Ausgabewert |
---|---|
-5 | -5.00 |
-3.895 | -3.90 |
1.63 | 1.63 |
467.531 | 467.53 |
Tabelle: Formatierung mit Formatsstring '##.00'.
Beispiel 4 – Verwendung von Submustern für negative Zahlen:
<xsl:value-of select="format-number($number,'##.00;minus ##.00')"/>
Eingabewert | Ausgabewert |
---|---|
-5 | minus 5.00 |
-3.895 | minus 3.90 |
1.63 | 1.63 |
467.531 | 467.53 |
Tabelle: Formatierung mit Formatsstring '##.00;minus ##.00'.
Anmerkung: Für negative Eingabewerte erfolgt aufgrund des Submusters keine Ausgabe des Minuszeichens.
Beispiel 5 – Verwendung eines Suffixes (hier in Form einer Maßeinheit):
<xsl:value-of select="format-number($number,'##.00 cm')"/>
Eingabewert | Ausgabewert |
---|---|
-5 | -5.00 cm |
-3.895 | -3.90 cm |
1.63 | 1.63 cm |
467.531 | 467.53 cm |
Tabelle: Formatierung mit Formatsstring '##.00 cm'.
Beispiel 6 – Verwendung von Präfix, Suffix und Submustern:
<xsl:value-of select="format-number($number,'Gewinn: ##.00 Euro;Verlust: ##.00 Euro')"/>
Eingabewert | Ausgabewert |
---|---|
-5 | Verlust: 5.00 Euro |
-3.895 | Verlust: 3.90 Euro |
1.63 | Gewinn: 1.63 Euro |
467.531 | Gewinn: 467.53 Euro |
Tabelle: Formatierung mit Formatsstring 'Gewinn: ##.00 Euro;Verlust: ##.00 Euro'.
Querverweis:
Beispiele unter Einbeziehung einer Formatdeklaration befinden 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 Ignorieren 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.)
<< zurück | vor >> |
Tipp der data2type-Redaktion: Zum Thema XSLT bieten wir auch folgende Schulungen zur Vertiefung und professionellen Fortbildung an: |
Copyright © Galileo Press, Bonn 2008
Für Ihren privaten Gebrauch dürfen Sie die Online-Version ausdrucken.
Ansonsten unterliegt dieses Kapitel aus dem Buch "XSLT 2.0 & XPath 2.0 ― Das umfassende Handbuch" denselben Bestimmungen wie die gebundene Ausgabe: Das Werk einschließlich aller seiner Teile ist urheberrechtlich geschützt. Alle Rechte vorbehalten einschließlich der Vervielfältigung, Übersetzung, Mikroverfilmung sowie Einspeicherung und Verarbeitung in elektronischen Systemen.
Galileo Press, Rheinwerkallee 4, 53227 Bonn