$INUMBER; $INUMBER

Validates numeric values and converts them to internal formats.

The outline

$INUMBER(fnumber,format,erropt)
$IN(fnumber,format,erropt)
Copy the code

parameter

• Fnumber Specifies the value to be converted to internal format. It can be a number or string value, a variable name, or any valid CacheObjectScript expression.
• Format A format specification that indicates which external number formats are valid representations of numbers. Specifies a quoted string consisting of zero or more format codes (in any order). The format code is described below. Note that some format codes are incompatible and cause errors. For the default format, you can specify an empty string with or without the erropt argument ("").
• Erropt Optional – Returns an expression if fnumber is considered invalid by format.

describe

The $INUMBER function validates the numeric fnumber using the format specified by the format. It is then converted to internal Cache format.

If the fnumber does not match the specified format and erropt is not specified, the Cache generates an

error. If erROpt is specified, an invalid value returns an ERropt string.

parameter

format

The possible format codes are as follows. They can be specified individually or in combination to indicate that $iNumber strictly adheres to formatting rules. If no format code is entered, $iNumber will be as flexible as possible in validating fnumbers

When there is no “+”, “-” and “P” format code

If FORMAT does not include any “+”, “-“, or “P” codes, then fnumber can contain any of the following codes:

• No symbols or parentheses.
• PlusSignLocale property (default is"+") orMinusSignLocale property (default is"-"), but you cannot use both attributes together. The location of this flag is determined by"L"or"T"The format code (if specified) is determined.
• Leading and trailing parentheses.

When there is no “L”, “T” and “P” format code

When FORMAT does not include any “L”, “T”, or “P” FORMAT codes, any symbol appearing in fnumber can be leading or trailing (but not both).

When “, “and”. Missing format code

When format does not include either ‘, ‘or’ ‘. .” Format code, fnumber can choose to have the NumericGroupSeparator symbol appear anywhere to the left or right of DecimalSeparator(if any). However, each NumericGroupSeparator must have at least one number to the left and right. The NumericGroupSeparator symbol is not allowed when FORMAT contains “N”.

Mutex format code

Some of the format codes conflict with each other. Each of the following pair of format code pairs is mutually exclusive and causes an error:

• "- +"Lead to<FUNCTION>error
• "-p" or "+ P"Lead to<SYNTAX>error
• TP or LPLead to<SYNTAX>error
• "TL"Lead to<FUNCTION>error
• "And."Lead to<FUNCTION>error
• "N"Lead to<FUNCTION>error
• "O".Lead to<FUNCTION>error

A

error is also generated if an invalid format code character is specified.

The NULL format provides the greatest flexibility

The format can be specified as an empty string. This is called space. When a space is specified, $INUMBER accepts an fnumber value with one of the following symbolic conventions:

• No symbols or parentheses.
• Leading or trailingMinusSign, but not both.
• Leading plus or trailing plus, but not both.
• Leading and trailing parentheses.

If null format is specified, fNumber can choose to have the NumericGroupSeparator symbol appear anywhere to the left or right of DecimalSeparator (if any). However, each NumericGroupSeparator must have at least one number to the left and at least one number to the right. The signature rules are flexible; leading and trailing Spaces and zeros are ignored. Therefore, the following two commands:

DHC-APP>WRITE ! ,$INUMBER("9100 + 1,23,456,7.8,"."")
 
1234567.891DHC-APP> WRITE ! ,$INUMBER("0012345,7.891 + 6"."")
 
1234567.891
Copy the code

Both are valid and return the same number, formatted according to the default locale. However,

DHC-APP>WRITE $INUMBER("1, 23, 345, 7., 8, 9,"."")
 
WRITE $INUMBER("1, 23, 345, 7., 8, 9,"."")
^
<ILLEGAL VALUE>
Copy the code

Invalid due to adjacent commas, adjacent periods and commas, and ending commas. It generates an error.

Common behavior for all formats

Regardless of the format code specified, $INUMBER always ignores starting and ending Spaces or zeros, but fnumber is considered invalid if it has any of the following characteristics:

• Plus and minus
• Multiple plus or minus signs
• Parentheses and plus signs
• Parentheses and minus signs
• Multiple decimal separators
• Embedded Spaces
• Any character other than the following:
  • Digital digits
  • "("
  • ")"
  • Leading or trailing space
  • Specified by the current localeDecimalSeparator(If the format does not include".")
  • Specified by the current localeNumericGroupSeparator(If the format does not contain".")
  • Specified by the current localePlusSignProperty if the format does not contain".")
  • Specified by the current localeMinusSignProperty if the format does not contain".")
  • "."(If the format includes".")
  • ","(If the format includes".")
  • "+"(If the format includes".")
  • "-"(If the format includes".")
• If the format includes"D", then string"INF"and"NAN"(and variations).

The sample

These examples illustrate how different formats affect the behavior of $INUMBER. All of these examples assume the current locale is the default locale.

In the following example, $INUMBER accepts a minus sign for using the “L” format code and returns -123456789.12345678:

DHC-APP>WRITE $INUMBER("-123,4,56,789.1234,5678"."L")
-123456789.12345678
Copy the code

In the following example, $INUMBER generates an error because the symbol comes first, but the “T” format code specifies that the ending symbol must be used:

DHC-APP>WRITE $INUMBER("-123,4,56,789.1234,5678"."T")
 
WRITE $INUMBER("-123,4,56,789.1234,5678"."T")
^
<ILLEGAL VALUE>
Copy the code

DHC-APP>WRITE $INUMBER("5678 + 123,4,56,789.1234,"."T")
123456789.12345678
DHC-APP>WRITE $INUMBER("123,4,56,789.1234,5678-"."T")
-123456789.12345678
Copy the code

In the example below, the first $INUMBER succeeds and returns a negative number. The second $INUMBER generates an error because fnumber contains a symbol, but the “P” format code specifies that negative numbers must be enclosed in parentheses rather than signed:

DHC-APP>WRITE ! ,$INUMBER("(5678) 123,4,56,789.1234,"."P")
 
-123456789.12345678DHC-APP>WRITE ! ,$INUMBER("-123,4,56,789.1234,5678"."P") WRITE ! ,$INUMBER("-123,4,56,789.1234,5678"."P")
        ^
<ILLEGAL VALUE>
Copy the code

In the following example, $INUMBER generates an error because symbols exist, but the “-” format code specifies that the number must be unsigned:

DHC-APP>WRITE $INUMBER("-123,4,56,789.1234,5678"."-")
 
WRITE $INUMBER("-123,4,56,789.1234,5678"."-")
^
<ILLEGAL VALUE>
DHC-APP>WRITE $INUMBER("123,4,56,789.1234, 5678"."-")
123456789.12345678
Copy the code

In the following example, $INUMBER fails, but does not generate an error due to the illegal use of symbols, but instead returns the string “ERR” as its value:

DHC-APP>WRITE $INUMBER("-123,4,56,789.1234,5678"."-"."ERR")
ERR
Copy the code

The following example returns -23456789.123456789; $INUMBER treats the specified fnumber as valid because the leading symbol follows the format specified by “L” and every three-digit comma to the left of the decimal point is strictly spaced and no comma to the right follows the “, “specified strict format code:

DHC-APP> WRITE $INUMBER("89-23456789123567"."L,")
-23456789.123456789
Copy the code

In the following example, the “E” code allows the conversion of the scientific symbol string to a number. Note that all format codes support scientific notation as numeric literals, but only “E” (or “G”) supports scientific notation as strings. This example uses variables and concatenation to provide scientific count string values:

DHC-APP>SET num=1.234
 
DHC-APP>SET exp=-14
 
DHC-APP>WRITE $INUMBER(1.234 e-14."E"."E-lit-err"),!
00000000000001234.
 
DHC-APP>WRITE $INUMBER(num_"E"_exp,"E"."E-string-err"),!
00000000000001234.
 
DHC-APP>WRITE $INUMBER(1.234 e-14."L"."L-lit-err"),!
00000000000001234.
 
DHC-APP>WRITE $INUMBER(num_"E"_exp,"L"."L-string-err"),!
L-string-err
Copy the code

The following example compares the fraction and constant PI of the value returned by the “L” and “D” codes. The “D” code converts to an IEEE float number ($DOUBLE) :

DHC-APP>WRITE $INUMBER(1.23 e-23."L"),!
0000000000000000000000123.
 
DHC-APP>WRITE $INUMBER(1.23 e-23."D"),!
000000000000000000000012299999999999999704.
 
DHC-APP>WRITE $INUMBER($ZPI,"L"),!
3.141592653589793238
 
DHC-APP>WRITE $INUMBER($ZPI,"D"),!
3.1415926535897931159
Copy the code

Pay attention to

$NUMBERand$FNUMBERThe difference between

Most formatting codes have similar meanings in the $INUMBER and $FNUMBER functions, but the exact behavior triggered by each code varies from function to function due to the nature of the validation and transformation performed.

In particular, the “-” and “+” format codes have a completely different meaning for $INUMBER than they do for $FNUMBER. For $FNUMBER, “-” and “+” are not mutually exclusive, “-” only affects MinusSign (by suppressing it) and “+” only affects PlusSign (by inserting it). For $INUMBER, “-” and “+” are mutually exclusive. – indicates that the symbol is not allowed, and + indicates that the symbol must be used.

Decimal separator

$INUMBER uses the current locale (“. ), the DecimalSeparator property value. By default) as a separator between the integer and fractional parts of the fnumber. When the “.” If a format code is specified, the delimiter is, regardless of the current locale.

To determine the DecimalSeparator character for the locale, call the GetFormatItem() method:

DHC-APP> WRITE ##class(%SYS.NLS.Format).GetFormatItem("DecimalSeparator").Copy the code

Number grouping separator and size

$INUMBER uses the NumericGroupSeparator property value from the current locale (“, “by default) as the separator between groups of digits in the integer part of the fnumber. The size of these groups is determined by the NumericGroupSize property (” 3 “by default) set by the current locale. When the “.” If the format code is specified, the delimiter is “. And displays every three digits, regardless of the current locale.

To determine the NumericGroupSeparator character and NumericGroupSize number for the locale, call the GetFormatItem() method:

DHC-APP>WRITE ##class(%SYS.NLS.Format).GetFormatItem("NumericGroupSeparator"),! .DHC-APP> WRITE# #class(%SYS.NLS.Format).GetFormatItem("NumericGroupSize")
3
Copy the code

Plus and minus

$iNumber uses the PlusSign and MinusSign attribute values in the current locale (+ and – by default). When the “.” If a format code is specified, the symbols will be set to + and – regardless of the current locale.

To determine the PlusSign and MinusSign characters for the locale, call the GetFormatItem() method:

DHC-APP> WRITE ##class(%SYS.NLS.Format).GetFormatItem("PlusSign"),!
+
 
DHC-APP>WRITE# #class(%SYS.NLS.Format).GetFormatItem("MinusSign")
-
Copy the code