Altova MapForce 2024 Basic Edition

Converts a number into a string and formats it according to the specified options.

mf-func-format-number

 

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.

mf_map_PreserveFormatting

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\MapForce2024\MapForceExamples\PreserveFormatting.mfd.

© 2017-2023 Altova GmbH