fn:round-half-to-even

(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: Rundungsfunktionen für numerische Typen

Herkunft: XPath 2.0

Rückgabewert: Ein numerischer Wert vom gleichen numerischen Typ wie der Eingabewert, entsprechend dem Wert des Präzisionsargumentes gerundet.

Aufruf/Argumente:

fn:round-half-to-even($eingabewert?, $praezision?)

$eingabewert:
Optional. Argument ist ein Eingabewert beliebigen numeri­schen Typs (numeric), der als zu rundende Zahl interpretiert wird. Entspricht der Wert keinem der numerischen Datentypen oder einem hiervon abgeleite­ten Typ, so erfolgt ein Typfehler.

$praezision:
Optional. Eine Präzisionsangabe in Form einer beliebigen, positiven oder negativen Ganzzahl xs:integer. Wird als Argument die 0 über­geben, so entspricht dies dem nicht übergebenen Argument.

Verwendungszweck:

Die Funktion fn:round-half-to-even() rundet numerische Eingangswerte auf eine bestimmbare Zahl von Stellen vor oder nach dem Komma, gemäß einer übergebenen Präzisionsangabe. Der Datentyp der Zahl bleibt dabei erhalten. Falls es sich bei der Eingabezahl bereits um eine Ganzzahl handelt, bleibt der Wert unverändert. Handelt es sich beim Eingabe­wert nicht um einen der vier numerischen Typen xs:float, xs:double, xs:decimal oder xs:integer bzw. einen von diesen abgeleiteten Typ, so wird ein Typfehler gemeldet.

Hat der Eingabewert den Typ xs:untypedAtomic, so wird dieser mittels Typ-Promotion zu xs:double umgewidmet.

Ist der Eingangstyp ein von einem der numerischen Basistypen abgeleiteter Typ (derived type) so wird das Rundungsergebnis mit dem entsprechenden Basistyp typisiert zurückgegeben.

Wird der Funktion die leere Sequenz übergeben, so gibt sie ebenfalls die leere Sequenz zurück. Ist (beim Eingangstyp xs:double oder xs:float) der Ein­gangswert NaN, so wird ebenfalls NaN zurückgegeben.

Solange keine explizite Präzisionsangabe vorliegt bzw. wenn der Wert 0 als zweites Argument übergeben wird, verhält sich die Funktion im Wesentlichen wie fn:round(), rundet also zur nächsten Ganzzahl auf oder ab.

Ein Unterschied besteht allerdings in der Handhabung von Werten genau auf der Schwelle zwischen Auf- und Abrundung: Ist die Ziffer nach der kleinsten zu rundenden Stelle eine 5, so wird die letzte Stelle zur nächsten geraden Ziffer (»half to even«) auf- oder abgerundet:

1.25 mit Präzision +1 wird zu 1.2 abgerundet und nicht (wie vielleicht erwar­tet) zu 1.3 aufgerundet. Der Wert 1.35 mit Präzision +1 wird dagegen zu 1.4 aufgerundet.

Liegt eine zu rundende Zahl vom Typ xs:float oder xs:double in Exponen­tialform vor, so erfolgt die Rundung stets in der auf Exponent 0 umgerechne­ten Mantisse der Zahl: Also wird z.B. 1.234E+2 zunächst in die Form 123.4E+0 gebracht und das Partikel 123.4 (die Mantisse) gemäß der gültigen Präzisionsangabe gerundet.

Ist der Eingabewert eine positive oder negative Null (also notwendigerweise vom Typ xs:float oder xs:double), so verhält sich die Funktion transparent. Sie gibt also z.B. für -0 auch -0 zurück; für +0 entsprechend +0.

Präzisionsangabe größer 0:
Eine positive Ganzzahl als Präzisionsargument übergeben, bestimmt die Anzahl der beizubehaltenden Nachkommastellen. Formal wird für einen Wert n zur nächstgelegenen Stelle des Eingabewertes gerundet, der 10E-n entspricht, für n=2 also auf 10E-2, also Hundertstel (ent­sprechend zwei Nachkommastellen).

Präzisionsangabe gleich 0:
Die 0 als Präzisionsargument bewirkt die Run­dung auf ganze Zahlen. Nach der Formel gilt für n=0 die Präzision 10E0, ent­spricht also der ersten Vorkommastelle (Einer). Die Wirkung entspricht exakt derjenigen beim Weglassen des Präzisionsarguments.

Präzisionsangabe kleiner 0:
Eine negative Ganzzahl als Präzisionsangabe bewirkt die Rundung auf Vorkommastellen. Nach der Formel ist für n=-2 die Präzision 10E-(-2), mit anderen Worten 10E2, also auf Hunderter (zwei Stel­len vor dem Komma). Die kleineren Vorkommastellen, hier also Zehner und Einer, werden genullt.

Beispiele:

Beispiel 1 – Rundung ohne Präzisionsargument:

fn:round-half-to-even(3.5)

ergibt 4.

Es wird Präzision 0 angenommen, da kein entsprechendes Argument überge­ben wurde. Es wird nach ganzen Zahlen gerundet. Da sich die Eingabezahl exakt auf der Rundungsschwelle befindet, wird sie nach 4 aufgerundet.

Beispiel 2 – Rundung mit Präzisionsargument 0:

fn:round-half-to-even(2.5, 0)

ergibt 2.

Es wird gemäß der übergebenen Präzision 0 nach ganzen Zahlen gerundet. Da sich die Eingabezahl exakt auf der Rundungsschwelle befindet, wird sie nach 2 abgerundet. (fn:round() gäbe mit gleichem Argument den Wert 3 zurück!)

Beispiel 3 – Rundung mit positivem Präzisionsargument:

fn:round-half-to-even(123.456, 2)

ergibt 123.46.

Es wird gemäß Präzision 2 nach Hunderstel (zwei Nachkommastellen) gerun­det. Da die Stelle hinter der letzten zu rundenden Stelle über der Rundungs­schwelle liegt, wird aufgerundet.

Beispiel 4 – Rundung mit positivem Präzisionsargument:

fn:round-half-to-even(3.4567E-3, 2)

ergibt 0.0E0.

Es wird gemäß Präzision 2 nach Hunderstel (zwei Nachkommastellen) gerun­det. Da die Zahl in Exponentialform vorliegt, wird ihre Mantisse zunächst in die dem Exponent +0 entsprechende Form gebracht und dann gerundet: 3.4567E-3 entspricht 0.0034567E+0. Im Rahmen der Präzision wird dieser Wert daher zu 0 abgerundet (genauer zu 0.0E0).

Beispiel 5 – Rundung mit negativem Präzisionsargument:

fn:round-half-to-even(116.57, -1)

ergibt 120.

Es wird gemäß Präzision -1 nach Zehnerstellen gerundet. Da sich die letzte zu rundende Stelle der Eingabezahl (die Einerstelle) über der Rundungsschwelle befindet, wird aufgerundet.

Beispiel 6 – Rundung mit negativem Präzisionsargument:

fn:round-half-to-even(15557.89, -2)

ergibt 15600.

Es wird gemäß Präzision -2 nach Hunderterstellen gerundet.

Funktionsdefinition:

XPath 1.0:

Funktion nicht verfügbar

XPath 2.0:

fn:round-half-to-even($arg as numeric?) as numeric?

fn:round-half-to-even($arg as numeric?,
                      $precision as xs:integer) as numeric?

   

<< zurück

vor >>