Wertauflöser - Kurzfassung

Zweck: Erzeugt ausgehend von einem numerischen Eingabewert eine Zeichenfolge mit der durch die Parameter definierten Formatierung.

images/download/attachments/169634165/image2022-7-4_9-20-18-version-1-modificationdate-1710758471299-api-v2.png

Der Zahl formatieren-Wertauflöser erzeugt ausgehend von einem numerischen Eingabewert eine Zeichenfolge mit der durch die Parameter definierten Formatierung.

Liegt kein Wert ($null) als Eingabewert vor, wird kein Wert ($null) zurückgegeben.
Ist der Eingabewert nicht-leer (nicht $null), aber nicht-numerisch dann tritt einer Fehler auf (IllegalArgumentException).

►ACHTUNG◄ Eine "Zahl mit Einheit" gilt nicht als numerischer Eingabewert. Nur das enthaltene Feld "Wert" (value)eignet sich als direkter Eingabewert für den .Zahl formatieren v4.12.0-Wertauflöser. Das Beispiel unten zeigt, wie der Wertauflöser verwendet werden kann, um eine "Zahl mit Einheit" zu formatieren.

Konfiguration

Der Zahl formatieren-Wertauflöser erwartet einen numerischen Eingabewert und gibt eine Zeichenfolge (oder $null) zurück.

Für die Definition des gewünschten Zahlenformats werden folgende Parameter angeboten:

Parameter	Standardwert	Effekt	Beispiele
Erzwinge Vorzeichen (Option)	abgewählt	Wird die Option ausgewählt, dann erscheint das Plus-Symbol (`+)` in Verbindung mit Werten, die >=0 sind. Ist die Option abgewählt, dann erscheint nur für Werte <0 das Symbol (`-`).	`+123` `-0,123`
Verwende Tausendertrennzeichen (Option)	abgewählt	Ist die Option ausgewählt, dann erscheinen die Ganzzahlstellen im Rückgabewert in Gruppen á 3 Ziffern separiert durch das anwendbare Tausendertrennzeichen. Die Sprachverwaltung definiert per Bundle/Resource `lobsterui/thousandsSeparator` das für die Aktuelle Sprache anwendbare Tausendtrennzeichen, das für die Firma der Session durch Firmenspezifische Sprachanpassungen übersteuert sein kann.	`12.345.678,98765`
Ganzzahlstellen (Ganzzahl)	1	Definiert die Mindestanzahl der angezeigten Ziffern für den ganzzahligen Teil des Rückgabewerts. Vom Eingabewert nicht besetzte Positionen werden mit der Ziffer `0` "aufgefüllt". Der Standardwert `1` bewirkt, dass für Werte im Bereich `]-1;+1[` die Ziffer `0` vor dem ggf. angezeigten Dezimaltrenner erscheint (vorletztes Beispiel rechts). Ein Wert von `0` (oder auch die Eingabe eines negativen Werts) erzwingt dagegen keine Ziffer vor dem Dezimaltrenner (s. letztes Beispiel rechts). Allerdings ergibt der Eingabewert 0 die Ausgabe von "`0`", wenn keine Dezimalen auszugeben sind. ►HINWEIS◄ Die angegebene Anzahl Ganzzahlstellen wirkt nicht limitierend. Es werden immer alle Ziffern ausgegeben, die erforderlich sind, um die Ganzzahlkomponente des Eingabewerts wiederzugeben.	`03046001.234,56700,12-0,36,12-,36`
Genauigkeit	2	Ganzzahlen `>-1` definieren die Anzahl der als Dezimalen anzuzeigenden Ziffern. Durch den Eingabewert nicht bereitgestellte Ziffern werden mit der Ziffer `0` "aufgefüllt". Definiert der Eingabewert mehr Dezimalen als angezeigt werden sollen, wird gerundet. Mit negativen Werten für die Genauigkeit werden die Dezimalen unverändert aus dem Eingabewert übernommen. Die Beispiele rechts zeigen die Rückgabewerte für den Eingabewert `0,5196` mit aufsteigender Genauigkeit (in Klammern). ►ACHTUNG◄ Für die Behandlung Mittelpunktwerten (z. B. 0,5195 zwischen 0,520 und 0,19) ist unter Umständen deren Datentyp entscheidend. Grundsätzlich verwendet die Rundung das HALF_EVEN-Prinzip, so dass jeder Mittelpunktwert zur geradzahligen Endziffer hin gerundet wird. Wenn man den Eingabewert 0,5195 über einen Kommazahl-Wertauflöser erzeugt, wird ein Double-Wert generiert, der diesem Wert sehr nahe kommt, aber trotz des hohen Auflösungsvermögens (durch die doppelte Anzahl Bits) beim Runden nicht als Mittelpunktwert gilt. Daher lautet für den Eingabewert `0,5195` (Double) mit einer Genauigkeit von 3 die Ausgabe "`0,519`" während die Formatierung den Wert "`0,520`" liefert, wenn der Double-Wert noch vorab per Eingabeobjekt (Typsicher)-Wertauflöser in den Datentyp Big Decimal konvertiert wird. Ein Eingabewert von `0,5205` ergibt unabhängig vom Datentyp (Double, Big Decimal) nach der HALF_EVEN-Logik die Ausgabe "`0,520`".	`0,5196` → `1 (0)0,5196` → `0,5 (1)0,5196` → `0,52 (2)0,5196` → `0,520 (3)0,5196 → 0,5196 (4)0,5196 → 0,51960 (5)`

Beispiele

In den folgenden Beispielen wird der Zahl formatieren-Wertauflöser jeweils eingesetzt, um einen statisch definierten Eingabewert in ein bestimmtes Zielformat umzuwandeln.

Die linke Spalte ("Konfiguration") zeigt jeweils die Konfiguration für die Meldung innerhalb einer Hinweis anzeigen (Popup)-Ereignisaktion. die rechte Spalte ("Ergebnis") zeigt die Ausgabe als "Alert".

Konfiguration	Ergebnis
	Dem Parameter Ganzzahlstellen wird hier der Wert 3 zugeordnet, um ausgehend von einem ganzzahligen Eingabewert eine Textausgabe mit mindestens drei Ziffern zu erzeugen. Im konkreten Anwendungsfall soll die numerische Kennung einen bestimmten "Mitarbeiter" identifizieren. Die "Vornullen" sichern in diesem Kontext ab, dass eine Sortierung (nach dem formatierten Textwert) dieselbe Reihenfolge ergibt, wie eine Sortierung anhand der zugrundliegenden Zahlenwerte (also "007" vor "010", während bei einer Textsortierung "10" vor "7" einordnen würde). ►HINWEIS◄ Die Nummern von Mitarbeitern mit mehr als drei Ziffern (>999) würden mit der hier demonstrierten Formatierung vollständig (mit allen Ziffern) angezeigt.
	Das Kaliber von Handfeuerwaffen wird häufig in Zoll angegeben, wobei es selten um Kaliber von mehr als einem halben Zoll, aber dafür aus naheliegenden Gründen um relativ hohe Präzision beim Durchmesser geht. Daher sind Angaben in hundertstel oder tausendstel Zoll üblich, die typischerweise ohne die sonst übliche Null vor dem Komma angegeben werden. Die Konfiguration demonstriert die Formatierung für die entsprechende Schreibweise: Es werden `0` Ganzzahlstellen (als Minimum) gefordert, so dass der Rückgabewert für Eingabewert mit einem Absolutbetrag <1 der Dezimaltrenner ohne vorangestellte `0` erscheint. Für die Genauigkeit werden im Beispiel 3 Stellen vorgegeben, so dass für einen "45er Colt" das Kaliber ",450" lauten würde, was nicht üblich ist. Man könnte auch einen beliebigen negativen Wert für die Genauigkeit angeben, um die Ausgabe von Kalibern wie ",357" und ",45" zu erreichen. Allerdings würde dann ein halbzölliges Kaliber als ",5" ausgegeben und nicht - wie üblich - als ",50". ►ANMERKUNG◄ Mit Rücksicht auf den angelsächsischen Bezug zur Maßeinheit Zoll würde in der Regel eher Punkt anstelle des Kommas als Dezimaltrenner erwartet. Hier stößt der Zahl formatieren-Wertauflöser an Grenzen, da er den Dezimaltrenner grundsätzlich für die Aktuelle Sprache aus der Sprachverwaltung bzw. Firmenspezifische Sprachanpassungen (per Bundle/Resource `lobsterui/decimalSeparator`) bezieht.
	Die Konfiguration links zeigt eine typische Formatierung für Zahlenwerte, die Geldbeträge betreffen, für die das Vorzeichen eine wesentliche Information darstellt, wie Zuschläge/Abschläge oder (hier) ein Betriebsergebnis, das positiv oder negativ sein kann: Die Option Erzwinge Vorzeichen legt fest, dass auch ein positives Vorzeichen (s. Bild) explizit erscheinen soll. Die Option Verwende Tausendertrennzeichen "bestellt" die v. a. für größere Summen hilfreiche Gruppierung. Für die Anzahl der Ganzzahlstellen wurde der Standardwert (`1`) beibehalten, so dass ggf. mindestens eine Null vor dem Dezimaltrenner ausgegeben wird.
	Die Formatierung aus dem vorigen Beispiel soll nun verwendet werden, um die Kenngröße EBITDA als Ergebnis einer Berechnung (per Berechne Wert-Wertauflöser) zu formatieren, wobei die im Berechnungsergebnis enthaltene "Einheit" (`unit`) angegeben werden soll. Der Berechne Wert-Wertauflöser liefert das Ergebnis der Addition (`EBIT+DEP+AMO`) als Wert des Datentyps "Zahl mit Einheit", also einem Objekt, das einerseits einen Zahlenwert im Feld "Wert" (`value`) und andererseits einen Verweis auf eine Maßeinheit im Feld "Einheit" (`unit`) angibt. Im vorliegenden Beispiel entstammt die Einheit "EUR" sehr wahrscheinlich der Dynamischen Aufzählung Währung. Damit im Endergebnis der als Text formatierte Zahlenwert und die Lokalisierung für die Einheit gemeinsam erscheinen können, obwohl der Zahl formatieren-Wertauflöser nur rein numerische Eingabewerte verarbeiten kann, muss der Berechne Wert-Wertauflöser sein Ergebnis an eine Textverkettung übergeben. Innerhalb der Textverkettung steht deren Eingabewert (vom Typ "Zahl mit Einheit") für die Definition von Teilzeichenfolgen zur Verfügung: Die erste Teilzeichenfolge greift auf den "Wert" (`value`) als Eingabewert für den Zahl formatieren-Wertauflöser zu, der wie im vorigen Beispiel parametriert ist. Die zweite Teilzeichenfolge definiert ein Leerzeichen als statischen Text. Die dritte Teilzeichenfolge greift auf die "Einheit" (`unit`) aus dem Berechnungsergebnis zu, wobei deren interner Name zurückgegeben wird und nicht etwa die zugehörige Lokalisierung. Der Wert aus Sprachverwaltung-Wertauflöser könnte verwendet werden, um stattdessen ggf. die Lokalisierung (etwa das Währungssymbol "€" oder ein Klartext wie "Euro") auszugeben.