$number

Returns a numeric value derived from a numeric string.

$number(NumericString)

Parameters

Parameters
Parameter Data Type Description
NumericString String String containing a number or scientific notation. If the number appears after alphabetic data, it is not converted.

Return Values

  • Value of the leading numeric part it encounters in String.

    The actual value returned depends on the locale, as determined by the values of $nlsformat and $nlslocale.

  • 0, if String contains no numeric text, if it starts with alphabetic text, or if it starts with a round bracket (open parenthesis) in classic mode.
  • "", if the input of $number is a Numeric or Float with value "".

Use

Allowed in all component types.

Description

$number returns a numeric value derived from the numeric string given as a parameter.

The numeric string is modified based whether the NLS format or locale is set, and then interpreted as a number. If the numeric string is considered in error, a value of zero is returned.

Locale-Based Processing

The value of $nlsformat determines how $number converts the input string, including the numeric separators it recognizes, and how it handles the minus sign and non-numeric characters.

  • If $nlsformat is set to nlslocale, it uses the value of $nlslocale to determine the numeric separators. See NLS Conversion Rules.
  • If it is not set or is set to classic, it uses the dot ( . ) as the decimal separator. See Classic Conversion Rules.

Numeric forms

The $number function recognizes the following numeric forms, which are interpreted according to the NLS format, the NLS locale, or classic mode:

  • Basic numeric such as 123.45.
  • Bracketed numbers, which means the value is the enclosed number, negated. For example (123.45) is treated as -123.45.
  • Scientific notation, which consists of two number parts separated by the exponent symbol pattern. The left is the mantissa and right is the exponent. The value is the mantissa multiplied by the exponent as a power of ten. For example, 123.45e2 returns 12345.

Note: If a number is not bracketed, it is interpreted as a basic numeric. It is only considered a scientific notation number if a valid exponent pattern is found.

These three forms are interpreted according to the NLS format, the NLS locale, or classic mode.

NLS Conversion Rules

All NLS numeric strings

  • All symbols are interpreted according to the NLS locale.
  • All white space is ignored.
  • All group separators (also called thousand separators) are ignored.

Basic number

  • Valid characters are white space, sign, decimal separator, group separator, and digits.
  • Any invalid character causes truncation of the string at that character's position.
  • The minus or plus sign may appear as the first or last character of the string. If it appears anywhere else, the string will be truncated directly after the sign.
  • The decimal separator may appear once. After that, it is considered an invalid character.

Bracketed number

  • Valid characters are white space, decimal separator, group separator, digits, and opening and closing parentheses (round brackets).
  • Any invalid character is considered an error and zero is returned.
  • Opening round bracket must be the first character and the closing round bracket must be the last character.
  • The decimal separator may appear once. After that, it is considered an invalid character.

Scientific notation

  • Valid characters are the valid characters for the mantissa and exponent and an exponent symbol pattern.
  • The exponent symbol pattern consists of an exponent symbol, an e, E, or the NLS exponent. It is only recognized if it is preceded by a valid character for the mantissa and followed by a valid character for the exponent.
  • Negative exponents that result in more than three decimal places, are rounded to three decimal places. Positive exponents that result in more than 49 digits are truncated at 49 digits.
  • The mantissa is interpreted as a basic numeric and is terminated by the exponent pattern.

    Note: Truncation can cause the whole numeric string not to be seen as scientific notation.

  • For the exponent:
    • Valid characters are white space, sign, group separator and digits. (The decimal separator is an invalid character.)
    • Any invalid character causes truncation of the string at that character's position.
    • The sign may appear as the first character. If it is a minus sign, the exponent is interpreted as a negative power of ten.
    • A second occurrence of the sign, truncates the numeric string after the sign and applies to the whole number, not the exponent.

Classic Conversion Rules

For all classic numeric strings

  • The decimal separator is the dot ( . ) character.
  • Only leading spaces are ignored.
  • Any invalid character causes truncation of the string at that character's position.

Basic Numeric

  • Valid characters are the plus or minus sign, decimal separator, and digits.
  • The sign may appear as the first character. After that, it is considered an invalid character.
  • The decimal separator may appear once. After that, it is considered an invalid character.

Bracketed Number

Not supported in classic mode. Zero is always returned.

Scientific Notation

  • Valid characters are the valid characters for the mantissa and exponent and an exponent symbol pattern.
  • The exponent symbol pattern consists of an exponent symbol, an e or E. It is only recognized if it is preceded by a valid character for the mantissa and followed by a valid character for the exponent.
  • If the exponent is longer than 4 digits, the scientific notation format is preserved but the exponent is truncated after 4 digits.
  • Mantissa is interpreted as a classic basic numeric and is terminated by the exponent pattern.

    Note: Truncation can cause the whole numeric string not to be seen as scientific notation.

  • Exponent:
    • Valid characters are sign and digits
    • The sign may appear as the first character and is interpreted as a negative power of ten
    • A second occurrence of the sign, truncates the numeric string after the sign and applies to the whole number, not the exponent

    Note: White space and group and decimal separators are invalid characters and cause truncation.

Using scan and $number

You can use a combination of the scan statement and $number to extract numeric data that is preceded by alphabetic data, as shown in the following example:

; find start of numeric data
; string ($1) contains numeric data
; save $result (start position of numeric data)

clrmess
$1 = "Amsterdam123jim"
scan $1,'#'
if ($result > 0)
   $3 = $result
else
   message "%%$1 does not contain numeric data"
   return -1
endif
$2 = $number($1[$3])
putmess "numeric part of %%$1 is %%$2"
History
Version Change
10.3.02.006 NLS locale applied to scientific notation.
9.6.01 Returns "" if the input is a Numeric or Float with value "".

Related Topics