Class: String
Description
This method converts a string to a number.
If the string contains a number created with Number.toString(), then this method will inverse the operation and return the original number. However, if the string contains an arbitrary sequence of characters, then the number returned is derived by applying the following algorithm to the string:
All occurrences of the decimal character are replaced by a dot.
All occurrences of the thousands separator (if specified) and the currency character are removed.
If the negative format mask specified P, all spaces and parenthesis are removed.
If stripSpace=1, all spaces are removed.
The result of applying the above steps is now decomposed from left to right in the following elements:
|
Element |
Description or Associated Action |
|
signs |
Any sequence of plus sign and minus signs. If the total number of minus signs is odd, the result of the following elements will be negated. |
|
zero or more digits |
The integer part of the number. |
|
decimal dot |
A single decimal dot is expected. |
|
optional fractional digits |
Zero or more can appear. |
|
uppercase E |
An exponent. |
|
Optional single sign |
The sign of the exponent. |
|
One or more digits of the exponent |
|
If the result of the first four elements above does not contain digits, then the numeric interpretation is zero. Otherwise, the numeric interpretation is derived by applying the optional exponent, and then removing any insignificant leading and trailing zeros. If an odd number of minus signs was detected, the result is negated.
If the negative number format character specified T and the original string ended with a minus sign, the result of the above steps is negated.
If the negative number format character specified P and the original string ended with a closing parenthesis, the result of the above steps is negated.
Note that these operations may transform a negative numeric interpretation into a positive value.
Syntax
StringObject.toNumber(String mask,Boolean stripSpace)
Parameters
|
mask |
An editing mask that describes how the number is formatted within the string. This uses mask syntax from $$NUM^%ZM. |
|
|
Position |
Interpretation |
|
|
1 |
Decimal representation. Translates to a decimal dot. If you supply a mask, always supply the correct value used within the string, even if the default (dot) is used. |
|
|
2 |
Thousands separator. This character will be unconditionally removed when translating the string into a number. Use the , symbol for most applications. |
|
|
3 |
Formatting used for negative numbers. This character can have the following values:
|
|
|
4 |
Character used to represent currencies. This character will be unconditionally removed when translating the string into a number. |
|
stripSpace |
An option that indicates whether spaces are removed when the string is converted to a number. Valid values are 1 (remove spaces) and 0 (do not remove spaces). The default is 0. |
Returns
If the string is empty, then it returns the empty string. Otherwise, it returns the canonic representation of the numeric interpretation of the string, after applying mask and stripSpace.
When Became Available
v7.0
Example
type String STR = "(12.345,67)" // negative, European
type Number NUM = STR.toNumber(",.P") // -12345.67
set STR = " (12.345,67)" // add. space ignored by "P"
set NUM = STR.toNumber(",.P") // -12345.67
set STR = " 12.235,67 " // same number, but positive
set NUM = STR.toNumber(",.P") // 12345.67
set STR = "$12,345.67-" // negative trailing, US format
set NUM = STR.toNumber(".,T$") // -12345.67
set STR = " $12,345.67-" // add. space NOT ignored by "T"
set NUM = STR.toNumber(".,T$") // 0
set NUM = STR.toNumber(".,T$",1) // stripSpace: -12345.67
set STR = "-123.45E6" // exponent
set NUM = STR.toNUmber() // -123450000
set STR = "-123.45e6" // lowercase e!
set NUM = STR.toNUmber() // -123.45
set STR = "-0123.4560" // insignificant zeros
set NUM = STR.toNUmber() // -123.456
set STR = "123.456ABC" // trailing alphas
set NUM = STR.toNUmber() // 123.456
set STR = "-123.456ABC-" // "T" AND minus sign
set NUM = STR.toNumber(",.T") // 124.456