format-number
Converts a number into a string and formats it according to the specified options.
Languages
Built-in, C++, C#, Java, XSLT 1.0, XSLT 2.0, XSLT 3.0.
Parameters
Argument | Description |
|---|---|
value | Mandatory argument. Supplies the number to be formatted. |
format | Mandatory argument. Supplies a format string that identifies the way in which the number is to be formatted. See "Remarks" below. |
decimal-point-format | Optional argument. Supplies the character to be used as the decimal point character. The default value is the full stop ( . ) character. |
grouping-separator | Optional argument. Supplies the character used to separate groups of numbers. The default value is the comma ( , ) character. |
| Note: | If the function’s output (result) is connected to an item of type other than string, the formatting may be lost as the value is cast to the target type. To disable this automatic cast, clear the Cast target values to target types check box in the Component Settings of the target component. |
Remarks
The format argument takes the following form:
format := subformat (;subformat)? subformat := (prefix)? integer (.fraction)? (suffix)? prefix := any characters except special characters suffix := any characters except special characters integer := (#)* (0)* ( allowing ',' to appear) fraction := (0)* (#)* (allowing ',' to appear) |
The first subformat is used for formatting positive numbers, and the second subformat for negative numbers. If only one subformat is specified, then the same subformat will be used for negative numbers, but with a minus sign added before the prefix.
Special Character | Default | Description |
|---|---|---|
zero-digit | 0 | A digit will always appear at this point in the result |
digit | # | A digit will appear at this point in the result string unless it is a redundant leading or trailing zero |
decimal-point | . | Separates the integer and the fraction part of the number. |
grouping-separator | , | Separates groups of digits. |
percent-sign | % | Multiplies the number by 100 and shows it as a percentage. |
per-mille | ‰ | Multiplies the number by 1000 and shows it as per-mille. |
The table below illustrates examples of format strings and their result.
| Note: | The rounding method used by the format-number function is "half up", which means that the value gets rounded up if the fraction is greater than or equal to 0.5. The value gets rounded down if the fraction is less than 0.5. This method of rounding applies only to generated program code and the built-in execution engine. In XSLT 1.0, the rounding mode is undefined. In XSLT 2.0, the rounding mode is "round-half-to-even". |
Number | Format String | Result |
|---|---|---|
1234.5 | #,##0.00 | 1,234.50 |
123.456 | #,##0.00 | 123.46 |
1000000 | #,##0.00 | 1,000,000.00 |
-59 | #,##0.00 | -59.00 |
1234 | ###0.0### | 1234.0 |
1234.5 | ###0.0### | 1234.5 |
.00025 | ###0.0### | 0.0003 |
.00035 | ###0.0### | 0.0004 |
0.25 | #00% | 25% |
0.736 | #00% | 74% |
1 | #00% | 100% |
-42 | #00% | -4200% |
-3.12 | #.00;(#.00) | (3.12) |
-3.12 | #.00;#.00CR | 3.12CR |
Example
The mapping illustrated below reads data from source XML and writes it to a target XML. There are multiple SinglePrice elements in the source that contain the following decimal values: 25, 2.30, 34, 57.50. The mapping has two goals:
1.Pad all values with zeros to the left so that the significant part takes 5 digits exactly
2.Pad all values with zeros to the right so that the decimal part takes 2 digits exactly
To achieve this, the format string 00000.00 was supplied as argument to the format-number function.
PreserveFormatting.mfd
Consequently, the values in the target have become:
00025.00
00002.30
00034.00
00057.50
You can find the mapping design file at the following path: <Documents>\Altova\MapForce2023\MapForceExamples\PreserveFormatting.mfd.