# Number Formatting

NOTE: Starting with build 7.0.7252, Inaport uses a new set of formatting controls for date/time and number formatting, and a new set of functions. The following codes are OBSOLETE - see Formatting Overview for current information.

The number formatting functions in Inaportuse format patterns to control how numbers are either displayed or recognised. There are several functions available for converting strings to numbers or vice versa:

- ston(string, pattern) - uses the pattern to convert string to a number
- val(string) - converts a string to a number - assumes that the string is a plain decimal number
- ntos(number, pattern) - converts a number to a string using the pattern.
- str(number [,length, decimal, pad character]) - converts a number to a string, optionally specifying the length of the string, the number of decimal places, and the leading pad character

ntos() and ston() are considerably more powerful than str() and val(), because they allow complete control over the format of the numbers, and they handle negative numbers. For example, suppose we have a field with the number 11,234.567. We can display that in many different ways:

Format Pattern | Number displayed
"#0" | 11234
"#,##0" | 11,234
"USD $##,##0.00" | USD $11,234.57

Notice that in the last example we added some text and specified 2 decimal points, and the number was correctly rounded.

The format patterns are used in exactly the same way to translate a string into a number. For example:

String | Format Pattern | Result
"123456.89" | "0.0" | 123456.89
"123,456.89" | "#,##0.0" | 123456.89
"aa123456.89zz" | "aa0.0zz" | 123456.89

Notice that in the last example, we were able to pick the number out of the string even though it had letters either side. This would allow us, for example, to pick a number out of an account id field.

### The Patterns

The general format of the pattern is:

positive pattern {; negative pattern } (the '{' and '}' mean that the negative pattern is optional)

where the positive and the negative patterns are used to describe positive and negative numbers respectively.

Each of the positive and negative patterns have the form:

{prefix}integer{.fraction}{suffix} (again, anything inside {} is optional)

The prefix and the suffix are any characters in the string that do not actually belong to the number; for example, the "aa" and the "zz" in the last example in the table above.

The integer and the fraction parts describe the parts of the number, and use combinations of '#' and '0'. A '#' means a digit may or may not appear; a '0' means that a digit must appear. Within the integer portion, the ',' character is used to indicate grouping.

The following table provides some examples of different format patterns on the same number or string.

Format pattern | ntos(123456.78, pattern) | ston("123,456.78", pattern)
"0" | "123457" - note the rounding | 123 - stops on the comma
"#,##0" | "123,457" | 123456.78
"#,##0.0#" | "123,456.78" | 123456.78
"#,##0.0" | "123,456.8" - forces one decimal place | 123456.78

### Positive and Negative Numbers

The format pattern can include a pattern for positive number and a separate pattern for negative numbers. If the negative pattern is not supplied, then it is assumed to be the same as the positive pattern, with "-" in front.

Function | Result
ston("-123", "0") | -123
ntos(-123, "0") | "-123"
ntos(123, "0;(0)") | "123"
ntos(-123, "0;(0)") | "(123)" - brackets around negative number - common in accounting
ntos(1234, "pos#,##0;neg0") | "pos1,234"
ntos(-1234, "pos#,##0;neg0") | "neg1234" - completely different format for negative number

### Special Characters

The patterns use some special characters. The tables below summarises the special characters and their meanings. the first table shows their meaning when used in ston() i.e. converting a string to a number.

Character | Meaning | Example | Result
0 | Digit. | ston("123", "0") |
# | Digit, but may or may not be present | ston("$30", "$#,##0") ston("$3,000", "$#,##0" ston("$3,000", "$0") | 30 3000 3 - stops at the comma
, | Indicates that the string may have a grouping character - in some locales, this grouping character may be different from ',' |  |
. | Indicates that the string may have a decimal character - in some locales, this decimal character may be different from '.' |  |
; | Separates positive and negative patterns |  |
' | Used to quote special characters in the prefix or suffix | ston("123#", "0") ston("123#", "0'#") | Not recognised 123
Any other character | Ignored - allows us to skip characters next to numbers | ston("a123z", "a0z") | 123

The following table shows the use of the special characters when producing strings.

Character | Meaning | Example | Result
0 | Digit. If the source number is not long enough, a '0' will be added. | ntos(123, "0") ntos(123, "0000") | "123" "0123"
# | Digit, but may or may not be present | ntos(30, "$#,##0") ntos(3000, "$#,##0" ntos(3000, "$0") | "$30" "$3,000" "$3000"
, | Indicates that the string may have a grouping character - in some locales, this grouping character may be different from ',' |  |
. | Indicates that the string may have a decimal character - in some locales, this decimal character may be different from '.' |  |
; | Separates positive and negative patterns |  |
' | Used to quote special characters in the prefix of suffix | ntos(123, "0'#") | "123#"
Any other character | Put into the output literally | ntos(123, "a0z") | "a123z"