Displaying a number as a formatted string.
A. Function Overview
The PeopleCode function ‘NumberToString’ can be used to display an existing numeric value as a formatted string. Typical examples include right-justifying a number (by padding with spaces), showing ‘DR’ or ‘CR’ for accounting values, and including separators for large numbers. Similar to the ‘DateTimeToLocalizedString’ function (refer to Tip 023), the string format is specified via the use of pattern symbols, each of which has a special meaning within the parameter string. Some of the more commonly-used symbols are included in the examples below.
The basic usage of the ‘NumberToString’ Function is as follows:
&char_object = NumberToString(“format”, &number_object);
The “format” string pattern consists of one or more flag values, such as:
%8.2v
This specifies that the display should contain a minimum of eight places, two of which must appear after the decimal point. In this context, a ‘place’ can be a numeric digit before or after the decimal point, as well as a punctuation symbol. So for instance ‘-12’ consists of three places, ‘123.45’ consists of six places, while ‘1,234.56’ consists of eight places.
The ‘v’ specifies that thousands should be separated by a comma (or whatever is specified in your system for number separation).
Refer to PeopleBooks for a full list of the flag values.
PeopleCode also provides a similar, related function: ‘NumberToDisplayString’. This is almost identical to ‘NumberToString’, except that ‘NumberToDisplayString’ will use the current user’s personalization settings to determine the display format for large numbers and decimal values. ‘NumberToString’, on the other hand, is based purely on the format string passed to the function at run-time.
B. Examples
For ease of reference, a tilde character (~) is used to mark a space in the examples below.
i. String with Thousand Separators and Two Decimal Places
&fees_char = NumberToString("%8.2v", &fees);
This will produce the following results:
- 123 will appear as: ~~123.00
- -123.45 will appear as: ~-123.45
- 123.4567 will appear as: ~~123.46 (note rounding for two decimal places)
- 1234.56 will appear as: 1,234.56
- 12345678.9 will appear as: 12,345,678.90
ii. Left-Padding a String with Zeroes (to 8 places in total)
&fees_char = NumberToString("%08", &fees);
This will produce the following results:
- 123 will appear as: 00000123
- -123 will appear as: -0000123
- 123.45 will appear as: 00123.45
- 12345678.9 will appear as: 12345678.9
iii. String with Brackets for Negative Numbers (to 10 places in total)
&fees_char = NumberToString("%10.2a", &fees);
This will produce the following results:
- 123 will appear as: ~~~123.00~ (note that a space is reserved at the start and the end for the bracket. For positive numbers, this will remain as a space.)
- -123 will appear as: ~~(123.00)
- -123.456 will appear as: ~~(123.46)
- 12345678.9 will appear as: ~12345678.90~ (additional spaces still included for a positive number exceeding ten places)
See Also:
Tip 023: Function DateTimetoLocalizedString
Tip 057: LPad and RPad Function