Value resolver – Abstract

Purpose: Generates a string from a numeric input value with the formatting defined by the parameters.

images/download/attachments/169634165/image2022-7-4_18-38-40-version-1-modificationdate-1710758471274-api-v2.png

The Format number value resolver generates a string with the formatting defined by the parameters, starting from a numeric input value.

If no value ($null) is present as input value, no value ($null) is returned.
If the input value is not empty (not $null) and non-numeric,, then an error occurs (IllegalArgumentException).

►CAUTION◄ A 'Unit number' is not considered a numeric input value. Only the included 'Value' (value) field is suitable as a direct input value for the Format number value resolver. The example below shows how the value resolver can be used to format a 'Unit number'.

Configuration

The Format number value resolver expects a numeric input value and returns a string (or $null).

The following parameters are offered for defining the desired number format:

Parameter	Default value	Effect	Examples
Force sign (optional)	unchecked	If the option is checked, then the plus symbol (`+`) appears in connection with values that are >=0. If the option is unchecked, then the symbol (`-)` appears only for values <0.	`+123` `-0,123`
Use thousands separator (optional)	unchecked	If the option is checked, then the integer digits in the return value appear in groups of 3 digits separated by the applicable thousands separator. The Localization defines per Bundle/Resource `lobsterui/thousandsSeparator` the applicable thousand separator for the Current locale, which may be overridden for the Company of session by a Company specific localization.	`12.345.678,98765`
Integer digits (integer)	1	Defines the minimum number of displayed digits for the integer part of the return value. Line items not occupied by the input value are 'populated' with the digit `0`. The default value `1` causes values in the range `]-1;+1[` to have the digit `0` displayed in front of the decimal separator, if any (penultimate example on the right). A value of `0` (or the input of a negative value) does not force a digit in front of the decimal separator (see last example on the right). However, the input value 0 results in the output of '`0`' if no decimals are output. ►NOTE◄ The specified number of Integer digits has no limiting effect. All digits are always output that are required to reflect the integer component of the input value.	`03046001.234,56700,12-0,36,12-,36`
Precision	2	Integers `>-1` define the number of digits to be displayed as decimals. Digits not provided by the input value are 'populated' with the digit `0`. If the input value defines more decimals than should be displayed, rounding is performed. With negative Precision values, the decimals are adopted unchanged from the input value. The examples on the right show the return values for the input value `0,5196` with increasing Precision (in brackets). ►CAUTION◄ For the treatment of midpoint values (e.g. 0.5195 between 0.520 and 0.19) their data type may be crucial. Basically, the rounding uses the HALF_EVEN principle, so that each midpoint value is rounded to the even final digit. If the input value 0.5195 is generated via a Floating number value resolver, a double value is generated that is very close to this value, but despite the high resolving power (due to the double number of bits) is not considered as a midpoint value during rounding. Therefore, for the input value `0,5195` (double) with a Precision of 3, the output is '`0,519`' while the formatting returns the value '`0,520`' if the double value is still converted to the BigDecimal data type in advance via an Input object (type safe) value resolver. An input value of `0,5205` results in the output '`0,520`' independent of the data type (double, BigDecimal) according to the HALF_EVEN logic. .	`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)`

Examples

In the following examples, the Format number value resolver is used in each case to convert a statically defined input value into a specific target format.

The left column ('Configuration') shows in each case the configuration for the Message within a Show alert (Popup) event action. the right column ('Result') shows the output as an 'Alert'.

Configuration	Result
	The Integer digits parameter is assigned the value 3 here to generate a text output with at least three digits starting from an integer input value. In this specific use case, the numeric identifier identifies a particular 'Employee'. The 'leading zeros' in this context ensure that a sequence (according to the formatted text value) results in the same order as a sequence based on the underlying numerical values (i.e. '007' before '010', while a text sequence would place '10' before '7'). ►NOTE◄ The numbers of employees with more than three digits (>999) would be displayed completely (with all digits) with the formatting demonstrated here.
	The caliber of handguns is often given in inches, rarely involving calibers of more than half an inch but, for obvious reasons, involving relatively high precision in diameter. Therefore, specifications in hundredths or thousandths of an inch are common, typically without the otherwise usual zero in front of the decimal point. The configuration demonstrates the formatting for the corresponding notation: `0` Integer digits (as a minimum) are required, so the return value for input value with an absolute value <1 the decimal separator without preceding `0` appears. For Precision, 3 digits are given in the example, so for a '.45 Colt' the caliber would be '.450', which is not usual. Any negative value for Precision could also be specified to achieve the output of calibers such as '.357' and '.45'. However, a half-inch caliber would then be issued as '.5' and not – as usual – as '.50'. ►NOTE◄ With regard to the imperial unit of measurement, the separator would be expected to appear as a decimal point even if a comma was specified as a decimal separator for the Current locale. This is where the Format number value resolver reaches its limits, since it always obtains the decimal separator for the Current locale from the Localization or Company specific localization (per Bundle/Resource `lobsterui/decimalSeparator`).
	The configuration on the left shows a typical formatting for numerical values that concern monetary amounts for which the sign is an essential piece of information, such as surcharges/discounts or (as here) an operating result that can be positive or negative: The Force sign option specifies that a positive sign (see figure) should also appear explicitly. The Use thousands separator option 'orders' the grouping, which is especially helpful for larger sums. For the number of Integer digits the default value (`1`) has been kept, so that at least one zero is output before the decimal separator if necessary.
	The formatting from the previous example is now used to format the EBITDA parameter as the result of a calculation (per Calculate value value resolver), where the 'unit' (`unit`) contained in the calculation result is specified. The Calculate value value resolver returns the result of the addition (`EBIT+DEP+AMO`) as a value of the 'Unit number' data type, i.e. an object that specifies a numerical value in the 'Value' (`value`) field on the one hand and a reference to a unit of measurement in the 'Unit' (`unit`) field on the other. In this example, the unit 'EUR' most likely originates from the dynamic enumeration Currency. In order for the numeric value formatted as text and the localization for the unit to appear together in the final result, although the Format number value resolver can only process purely numeric input values, the Calculate value value resolver must pass its result to Concat strings. The input value of the Concat strings (of the 'Unit number' type) can be used for the definition of substrings: The first substring accesses the 'Value' (`value`) as input value for the Format number value resolver, which is parameterized in the same way as in the previous example. The second substring defines a space as static text. The third substring accesses the 'Unit' (`unit`) from the calculation result, returning its internal name and not the associated localization. The Value from localization value resolver could be used to output the localization (such as the currency symbol '€' or plain text like 'Euro') instead.