第二十章 Caché 函数大全 $INUMBER 函数

验证数字值并将其转换为内部格式。

大纲

$INUMBER(fnumber,format,erropt)
$IN(fnumber,format,erropt)

参数

• fnumber 要转换为内部格式的数值。它可以是数字或字符串值，变量名或任何有效的CachéObjectScript表达式。
• format 格式规范，指示哪些外部数字格式是数字的有效表示形式。指定为带引号的字符串，该字符串由零个或多个格式代码组成（以任意顺序）。格式代码如下所述。请注意，某些格式代码不兼容并导致错误。对于默认格式，无论是否带有erropt参数，都可以指定空字符串（“”）。
• erropt 可选-如果根据格式认为fnumber无效，则返回表达式。

描述

$INUMBER函数使用格式指定的格式来验证数值fnumber。然后将其转换为内部Caché格式。

如果fnumber与指定的格式不对应，并且未指定erropt，则Caché会生成<ILLEGAL VALUE>错误。如果指定了erropt，则无效的数值将返回erropt字符串。

参数

format

可能的格式代码如下。可以单独指定或组合指定它们，以指示$iNumber严格遵守格式规则。如果未输入格式代码，$iNumber将在验证fnumber时尽可能灵活

代码	描述
+	强制性标志。 fnumber值必须有一个明确的符号。即使数字0也必须签名（+0或-0）。除非受“L”或“T”格式代码的限制，否则该符号可以是开头或结尾。不能使用括号。唯一不需要符号的值是NAN，使用代码“D +”时可以指定带或不带符号。
-	未签名。 fnumber中可能没有符号。
D	$DOUBLE数字。此代码将数字转换为IEEE浮点数。这等效于$DOUBLE（fnumber）。 如果指定“D”，则可以输入带引号的字符串“INF”和“ NAN”作为fnumber值。INF和NAN可以以大小写字母的任意组合指定，带有或不带有前导或尾随符号或括号。（对于NAN，可接受但忽略符号。）还支持变体形式INFINITY和SNAN。
E 或 G	电子记数法(科学记数法)。此代码允许将fnumber指定为科学记数法格式的字符串。此代码允许(但不要求)使用科学记数法指定fnumber。
N	没有NumericGroupSeparator。不允许使用数字组分隔符。此格式代码与逗号(，)格式代码不兼容。
O	ODBC区域设置。覆盖当前区域设置，而使用具有下列值的标准ODBC区域设置：PlusSign=+；MinusSign=-；DecimalSeparator=.；NumericGroupSeparator=，；NumericGroupSize=3。此格式代码与点(.)不兼容。格式化代码。
P	负数必须用括号括起来。非负数必须是无符号的，并且可以包含或省略前导空格和尾随空格。
L	先导标志。符号(如果存在)必须在fnumber的数字部分之前。不允许使用括号。
T	尾部标志。符号(如果有)必须跟在fnumber的数字部分之后。不允许使用括号。
,	期望fnumber使用当前语言环境中的属性指定的格式。 NumericGroupSeparator（默认情况下为“，”）可能会出现也可能不会出现在fnumber中，但如果存在，它必须始终出现在小数点左边的每个NumericGroupSize（默认情况下为3）位。
.	无论当前的区域设置如何，都需要标准的欧洲格式。要求将DecimalSeparator作为逗号(，)，将NumericGroupSeparator作为句点(.)，将NumericGroupSize作为3，将PlusSign作为加号(+)，将MinusSign作为减号(-)。句点是可选的，但如果存在，则必须始终每三位出现在小数点逗号左侧。

当没有“+”、“-”和“P”格式代码时

如果FORMAT不包括任何“+”、“-”或“P”代码，则fnumber可以包含以下任一代码：

• 没有符号或括号。
• PlusSign区域设置属性(默认为“+”)或MinusSign区域设置属性(默认为“-”)，但不能同时使用这两个属性。此标志的位置由“L”或“T”格式代码(如果指定)确定。
• 前导括号和尾随括号。

当没有“L”、“T”和“P”格式代码时

当FORMAT不包括任何“L”、“T”或“P”格式代码时，fnumber中出现的任何符号可以是前导或尾随(但不能同时为两者)。

何时“、”和“。”缺少格式代码

当格式既不包括“，”也不包括“”时。"。"格式代码，fnumber可以选择让NumericGroupSeparator符号出现在DecimalSeparator(如果有的话)左侧或右侧的任何位置。但是，每个NumericGroupSeparator的左边和右边都必须至少有一个数字。当FORMAT包含“N”时，不允许使用NumericGroupSeparator符号。

互斥格式代码

某些格式代码相互冲突。以下格式代码对中的每一对都是互斥的，并会导致错误：

• “-+”导致<FUNCTION>错误
• “ -P”或“ + P”导致<SYNTAX>错误
• “ TP”或“ LP”导致<SYNTAX>错误
• “ TL”导致<FUNCTION>错误
• “、。”导致<FUNCTION>错误
• “，N”导致<FUNCTION>错误
• “.o”导致<FUNCTION>错误

如果指定无效的格式代码字符，也会生成<FUNCTION>错误。

NULL格式提供了最大的灵活性

可以将格式指定为空字符串。这称为空格式。指定空格式时，$INUMBER接受具有以下符号约定中的任何一种的fnumber值：

• 没有符号或括号。
• 前导或尾随的MinusSign，但不能同时使用。
• 前导加号或尾随加号，但不能同时使用。
• 前导括号和尾随括号。

如果指定了null格式，则fnumber可以选择使NumericGroupSeparator符号出现在DecimalSeparator左侧或右侧的任何位置（如果有）。但是，每个NumericGroupSeparator的左端必须至少有一个数字，而其右端必须至少有一个数字。签名规则很灵活，前导空格和尾随空格和零都将被忽略。因此，以下两个命令：

DHC-APP>WRITE !,$INUMBER("+1,23,456,7.8,9,100","")
 
1234567.891
DHC-APP> WRITE !,$INUMBER("0012,3456,7.891+","")
 
1234567.891

都有效，并且返回相同的数字，并根据默认语言环境设置格式。然而，

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

由于相邻的逗号，相邻的句点和逗号以及结尾的逗号而无效。它生成一个错误。

所有格式的共同行为

不管指定的格式代码如何，$INUMBER始终忽略开头和结尾的空格或零，但是如果fnumber具有以下任何特征，则认为fnumber无效：

• 加号和减号都有
• 多个加号或减号
• 括号和加号
• 括号和减号
• 多个小数分隔符
• 嵌入空格
• 以下字符以外的任何字符：
  • 数字位数
  • “(“
  • “)”
  • 前导空格或尾随空格
  • 由当前区域设置指定的DecimalSeparator(如果格式不包括“.”)
  • 当前语言环境指定的NumericGroupSeparator（如果格式不包含“。”）
  • 当前语言环境指定的PlusSign属性（如果格式不包含“。”）
  • 当前语言环境指定的MinusSign属性（如果格式不包含“。”）
  • “.” (如果格式包括 “.”)
  • “,” (如果格式包括 “.”)
  • “+” (如果格式包括 “.”)
  • “-” (如果格式包括 “ .”)
• 如果格式包括“D”，则字符串“INF”和“NAN”（及其变体）。

示例

这些示例说明了不同的格式如何影响$INUMBER的行为。所有这些示例均假定当前语言环境为默认语言环境。

在下面的示例中，$INUMBER由于使用“L”格式代码而接受一个减号，并返回-123456789.12345678：

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

在以下示例中，$INUMBER生成一个错误，因为该符号在前，但是“T”格式代码指定必须使用结尾的符号：

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

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

在下面的示例中，第一个$INUMBER成功并返回负数。第二个$INUMBER生成一个错误，因为fnumber包含一个符号，但是“P”格式代码指定负数必须用括号括起来而不是带符号：

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

在下面的示例中，$INUMBER生成错误，因为存在符号，但是“-”格式代码指定数字必须为无符号：

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

在以下示例中，$INUMBER失败，但由于非法使用符号而不会产生错误，而是返回指定为错误的字符串“ERR”作为其值：

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

以下示例返回-23456789.123456789; $INUMBER将指定的fnumber视为有效，因为前导符号遵循“L”指定的格式，并且小数点左边每三位数的逗号严格间隔，其右无逗号遵循 “,”指定的严格格式”代码：

DHC-APP> WRITE $INUMBER("-23,456,789.123456789","L,")
-23456789.123456789

在以下示例中，“E”代码允许将科学符号字符串转换为数字。请注意，所有格式代码都支持科学记数法作为数字文字，但是只有“E”（或“G”）支持科学记数法作为字符串。本示例使用变量和串联来提供科学计数字符串值：

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

下面的示例比较“L”代码和“D”代码返回的值的分数和常数pi。 “D”代码转换为IEEE浮点数（$DOUBLE）：

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

注意

$NUMBER和$FNUMBER之间的差异

大多数格式代码在$INUMBER和$FNUMBER函数中具有相似的含义，但是由于执行的验证和转换的性质，每个代码触发的确切行为因函数而异。

特别是，“-”和“+”格式代码对$INUMBER的含义与对$FNUMBER的含义完全不同。对于$FNUMBER，“-”和“+”不互斥，“-”仅影响MinusSign（通过抑制它），而“+”仅影响PlusSign（通过插入它）。对于$INUMBER，“-”和“+”是互斥的。 “-”表示不允许使用符号，“+”表示必须使用符号。

小数点分隔符

$INUMBER使用当前区域设置(“.”)的DecimalSeparator属性值。默认情况下)作为fnumber的整数部分和小数部分之间的分隔符。当“。”如果指定了格式代码，则此分隔符为“，”，而与当前区域设置无关。

若要确定区域设置的DecimalSeparator字符，请调用GetFormatItem()方法：

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

数字分组分隔符和大小

$INUMBER使用当前区域设置中的NumericGroupSeparator属性值(默认情况下“，”)作为fnumber整数部分中数字组之间的分隔符。这些组的大小由当前区域设置的NumericGroupSize属性(默认情况下为“3”)确定。当“。”指定了格式码，则此分隔符为“。并且每三位数显示一次，与当前区域设置无关。

要确定区域设置的NumericGroupSeparator字符和NumericGroupSize编号，请调用GetFormatItem()方法：

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

加号和减号

$iNumber使用当前区域设置中的PlusSign和MinusSign属性值(默认情况下为“+”和“-”)。当“。”如果指定了格式代码，则无论当前区域设置如何，这些符号都将设置为“+”和“-”。

要确定的区域设置的PlusSign和MinusSign字符，请调用GetFormatItem()方法：

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