Numeric Format
When a text is parsed as any numeric data type or any numeric data type should be formatted to a text, format pattern must be specified.
Parsing and formatting is locale sensitive.
In CloudConnect, Java decimal format is used.
Table 28.8. Numeric Format Pattern Syntax
| Symbol | Location | Localized? | Meaning |
|---|---|---|---|
| # | Number | Yes | Digit, zero shows as absent |
| 0 | Number | Yes | Digit |
| . | Number | Yes | Decimal separator or monetary decimal separator |
| - | Number | Yes | Minus sign |
| , | Number | Yes | Grouping separator |
| E | Number | Yes | Separates mantissa and exponent in scientific notation. Need not be quoted in prefix or suffix. |
| ; | Subpattern boundary | Yes | Separates positive and negative subpatterns |
| % | Prefix or suffix | Yes | Multiply by 100 and show as percentage |
| ‰ (\u2030) | Prefix or suffix | Yes | Multiply by 1000 and show as per mille value |
| ¤ (\u00A4) | Prefix or suffix | No | Currency sign, replaced by currency symbol. If doubled, replaced by international currency symbol. If present in a pattern, the monetary decimal separator is used instead of the decimal separator. |
| ' | Prefix or suffix | No | Used to quote special characters in a prefix or suffix, for example, "'#'#" formats 123 to "#123". To create a single quote itself, use two in a row: "# o''clock". |
Both prefix and suffix are Unicode characters from \u0000 to \uFFFD, including the margins, but excluding special characters.
Format pattern composes of subpatterns, prefixes, suffixes, etc. in the way shown in the following table:
Table 28.9. BNF Diagram
| Format | Components |
|---|---|
| pattern | subpattern{;subpattern} |
| subpattern | {prefix}integer{.fraction}{suffix} |
| prefix | '\\u0000'..'\\uFFFD' - specialCharacters |
| suffix | '\\u0000'..'\\uFFFD' - specialCharacters |
| integer | '#'* '0'* '0' |
| fraction | '0'* '#'* |
Explanation of these symbols follow:
Table 28.10. Used Notation
| Notation | Description |
|---|---|
| X* | 0 or more instances of X |
| (X | Y) | either X or Y |
| X..Y | any character from X up to Y, inclusive |
| S - T | characters in S, except those in T |
| {X} | X is optional |
![[Important]](figures/important.png) | Important |
|---|---|
The grouping separator is commonly used for thousands, but in some countries it separates ten-thousands. The grouping size is a constant number of digits between the grouping characters, such as 3 for 100,000,000 or 4 for 1,0000,0000. If you supply a pattern with multiple grouping characters, the interval between the last one and the end of the integer is the one that is used. So "#,##,###,####" == "######,####" == "##,####,####". |
Remember also that formatting is locale senistive. See the following table in which results are different for different locales:
Table 28.11. Locale-Sensitive Formatting
| Pattern | Locale | Result |
|---|---|---|
| ###,###.### | en.US | 123,456.789 |
| ###,###.### | de.DE | 123.456,789 |
| ###,###.### | fr.FR | 123 456,789 |
![[Note]](figures/note.png) | Note |
|---|---|
For a deeper look on handling numbers, consult the official Java documentation. |
Scientific Notation
Numbers in scientific notation are expressed as the product of a mantissa and a power of ten.
For example, 1234 can be expressed as
1.234 x 103.
The mantissa is often in the range 1.0 <= x <
10.0, but it need not be.
Numeric data types can be instructed to format and parse scientific notation only via a pattern. In a pattern, the exponent character immediately followed by one or more digit characters indicates scientific notation.
Example: "0.###E0" formats the number 1234 as "1.234E3".
Examples of numeric pattern and results follow:
Table 28.12. Numeric Format Patterns and Results
| Value | Pattern | Result |
|---|---|---|
| 1234 | 0.###E0 | 1.234E3 |
| 12345 | ##0.#####E01) | 12.345E3 |
| 123456 | ##0.#####E01) | 123.456E3 |
| 1234567 | ##0.#####E01) | 1.234567E6 |
| 12345 | #0.#####E02) | 1.2345E4 |
| 123456 | #0.#####E02) | 12.3456E4 |
| 1234567 | #0.#####E02) | 1.234567E6 |
| 0.00123 | 00.###E03) | 12.3E-4 |
| 123456 | ##0.##E04) | 12.346E3 |
Legend:
1): Maximum number of integer digits is 3, minimum number of integer digits is 1, maximum is greater than minimum, thus exponent will be a multiplicate of three (maximum number of integer digits) in each of the cases.
2): Maximum number of integer digits is 2, minimum number of integer digits is 1, maximum is greater than minimum, thus exponent will be a multiplicate of two (maximum number of integer digits) in each of the cases.
3): Maximum number of integer digits is 2, minimum number of integer digits is 2, maximum is equal to minimum, minimum number of integer digits will be achieved by adjusting the exponent.
4): Maximum number of integer digits is 3, maximum number of fraction digits is 2, number of significant digits is sum of maximum number of integer digits and maximum number of fraction digits, thus, the number of significant digits is as shown (5 digits).
Binary Formats
The table below presents a list of available formats:
Table 28.13. Available Binary Formats
| Type | Name | Format | Length |
|---|---|---|---|
| integer | BIG_ENDIAN | two's-complement, big-endian | variable |
LITTLE_ENDIAN | two's-complement, little-endian | ||
PACKED_DECIMAL | packed decimal | ||
| floating-point | DOUBLE_BIG_ENDIAN | IEEE 754, big-endian | 8 bytes |
DOUBLE_LITTLE_ENDIAN | IEEE 754, little-endian | ||
FLOAT_BIG_ENDIAN | IEEE 754, big-endian | 4 bytes | |
FLOAT_LITTLE_ENDIAN | IEEE 754, little-endian |
The floating-point formats can be used with
numeric and decimal datatypes.
The integer formats can be used with integer and
long datatypes. The exception to the rule is the
decimal datatype, which also supports integer
formats (BIG_ENDIAN,
LITTLE_ENDIAN and
PACKED_DECIMAL). When an integer format is used
with the decimal datatype, implicit decimal point
is set according to the Scale attribute. For
example, if the stored value is 123456789 and
Scale is set to 3, the value of the field will be
123456.789.
To use a binary format, create a metadata field with one of the
supported datatypes and set the Format attribute
to the name of the format prefixed with "BINARY:",
e.g. to use the PACKED_DECIMAL format, create a
decimal field and set its Format to
"BINARY:PACKED_DECIMAL" by choosing it from the
list of available formats.
For the fixed-length formats (double and float) also the Size attribute must be set accordingly.
Currently, binary data formats can only be handled by ComplexDataReader and the deprecated FixLenDataReader.