$INUMBER (ObjectScript)
構文
$INUMBER(fnumber,format,erropt)
$IN(fnumber,format,erropt)
引数
引数 | 説明 |
---|---|
fnumber | 内部形式に変換される数値。数値、文字列値、変数名、あるいは有効な ObjectScript 式にできます。 |
format | 有効な表現である外部数値形式を示す形式指定。任意の順序の 0 以上の形式コードで構成される引用符付きの文字列として指定されます。形式コードの詳細は後述します。一部の形式コードは互換性がなく、エラーが生じます。erropt 引数の有無によらず、既定の形式には、空の文字列 () を指定できます。 |
erropt | オプション — fnumber が format に基づいて無効であると見なされた場合に返される式。 |
概要
$INUMBER 関数は、format で指定した形式を使用して、数値 fnumber を検証します。そして、内部 InterSystems IRIS 形式に変換します。
fnumber が指定 format に対応していない場合で、erropt を指定していない場合、システムは <ILLEGAL VALUE> エラーを生成します。erropt を指定した場合、無効な数値は erropt 文字列を返します。
引数
format
利用可能な形式コードは、以下のとおりです。形式の制限に基づいて $INUMBER を指示するために単一、あるいは組み合わせて指定できます。形式コードが入力されない場合、$INUMBER は、fnumber を可能な限り柔軟に検証します (詳細は "最大の柔軟性を提供する NULL 形式" を参照)。
コード | 説明 |
---|---|
+ | 必須符号。fnumber 値には明示的な符合が必要です。0 にも符号を付ける必要があります (+0、または -0)。“L” もしくは “T” 形式コードによる規制がない限り、符号は先行でも後続でもかまいません。括弧を使用することはできません。符号を必要としない値は NAN のみです。これは、コード “D+” を使用している場合、符号を付けても付けなくても指定できます。 |
- | 符号なし。fnumber に符号がない場合もあります。 |
D | $DOUBLE の数値。このコードは fnumber を IEEE 浮動小数点数に変換します。これは $DOUBLE(fnumber) と同等です。“D” が指定されている場合、引用符付きの文字列 “INF” および “NAN” を fnumber 値として入力できます。INF と NAN は、大文字と小文字の任意の組み合わせで、先頭または末尾の符号や括弧があってもなくても指定できます (NAN の場合、符号は許可されますが無視されます)。変異形の INFINITY および SNAN もサポートされています。 |
E または G | E 記数法 (科学的記数法)。このコードでは、科学的記数法の形式の文字列として fnumber を指定できます。このコードは、科学的記数法で fnumber を指定することを許可しています (ただし必須ではありません)。 |
N | NumericGroupSeparator なし。数値グループ・セパレータを使用できないようにします。この形式コードには、コンマ (,) 形式コードとの互換性がありません。 |
O | ODBC ロケール。現在のロケールにオーバーライドし、代わりに PlusSign=+、MinusSign=-、DecimalSeparator=.、NumericGroupSeparator=,、NumericGroupSize=3 の値で標準 ODBC ロケールを使用します。この形式コードにはドット (.) 形式コードとの互換性がありません。 |
P | 負の数は括弧で囲む必要があります。非負数は符号を付けません。先頭または末尾の空白を付けても省略してもかまいません。 |
L | 先行符号。符号がある場合、fnumber の数字部分の前に置く必要があります。括弧は使用しません。 |
T | 後続符号。符号がある場合、fnumber の数字部分の後に置く必要があります。括弧は使用しません。 |
, | fnumber で、現在のロケールのプロパティによって指定された形式が使用されることを予期します。NumericGroupSeparator (既定は ",") は、fnumber に表示される場合と表示されない場合がありますが、表示される場合は、小数点の左側に NumericGroupSize (既定は 3) 桁ごとに一貫して表示されている必要があります。 |
. | 現在のロケール設定に関係なく、標準的なヨーロッパ形式を要求します。DecimalSeparator はコンマ (,)、NumericGroupSeparator はピリオド (.)、NumericGroupSize は 3、PlusSign はプラス記号 (+)、MinusSign はマイナス記号 (-) を要求します。ピリオドはオプションですが、ピリオドが存在する場合は常に、小数点の左側に 3 桁ごとに表示されなければなりません。 |
"+"、"-" および "P" 形式コードが存在しないとき
format に "+"、"-"、または "P" コードのいずれも含まれていないときには、fnumber に以下のいずれかを含めることができます。
-
符号や括弧はなし。
-
PlusSign 個別指定プロパティ (既定は "+") あるいは MinusSign 個別指定プロパティ (既定は "-") の両方ではなくどちらか一方。この符号の位置は、指定すれば、"L" あるいは "T" 形式コードのどちらかにより決定。
-
括弧で囲む。
"L"、"T" および "P" 形式コードが存在しないとき
format が "L"、"T" または "P" 形式コードのいずれも含まないときは、fnumber に付いている符号は先行でも後続でもかまいません (ただし、両方には付きません)。
形式コード “,” および “.” が存在しないとき
format に "," 形式コードまたは "." 形式コードのいずれも含まれないとき、オプションとして fnumber は、(存在する場合は) DecimalSeparator の左右いずれかの任意の場所に NumericGroupSeparator 記号を付けることができます。しかし、各 NumericGroupSeparator は、その左右両隣に少なくとも 1 桁を持たなければなりません。format が “N” を含む場合、NumericGroupSeparator 記号は使用できません。
相互排他的形式コード
形式コードには、お互いに競合するものもあります。形式コードの以下の各組み合わせは、相互排他的であり、エラーが発生します。
-
“-+” は <FUNCTION> エラーになります。
-
“-P” または “+P” は <SYNTAX> エラーになります。
-
“TP” または “LP” は <SYNTAX> エラーになります。
-
“TL” は <FUNCTION> エラーになります。
-
“,.” は <FUNCTION> エラーになります。
-
“,N” は <FUNCTION> エラーになります。
-
“.O” は <FUNCTION> エラーになります。
さらに、無効な形式コード文字を指定した場合、<FUNCTION> エラーが発生します。
最大の柔軟性を提供する NULL 形式
format を NULL 文字列として指定できます。これは、NULL 形式と呼ばれています。NULL 形式が指定されると、$INUMBERは以下の記号規則のうちのいずれかを使用して、fnumber 値を受け入れます。
-
符号や括弧はなし
-
前か後の両方ではなく、どちらか一方に MinusSign
-
前か後の両方ではなく、どちらか一方に PlusSign
-
括弧で囲む。
NULL 形式を指定したとき、fnumber は、オプションとして、(存在する場合は) DecimalSeparator の左右いずれかの任意の場所に NumericGroupSeparator 記号を持つことがあります。しかし、各 NumericGroupSeparator は、その左右両隣に少なくとも 1 桁を持たなければなりません。符号に関する規約は柔軟ですが、前と後の空白とゼロは無視されます。したがって、以下の 2 つのコマンド
WRITE !,$INUMBER("+1,23,456,7.8,9,100","")
WRITE !,$INUMBER("0012,3456,7.891+","")
は両方とも有効で、既定のロケールに対応してフォーマットされた同じ数を返します。しかし、以下の例はどうでしょうか。
WRITE $INUMBER("1,23,,345,7.,8,9,","")
これは、隣接したコンマ、隣接したピリオドとコンマ、末尾のコンマなので無効です。これによって <ILLEGAL VALUE> エラーが発生します。
すべての形式に共通する動作
指定した形式コードに関係なく、$INUMBER は常に前と後にある空白スペースやゼロを無視しますが、以下の特性のいずれかがある場合 fnumber は無効であると見なします。
-
PlusSign と MinusSign 両方
-
1 つ以上の PlusSign あるいは MinusSign
-
括弧と PlusSign
-
括弧と MinusSign
-
1 つ以上の DecimalSeparator
-
埋め込まれたスペース
-
下記以外の文字
-
数字
-
“(“
-
“)”
-
先行または後続スペース
-
現在のロケールで指定された DecimalSeparator (format が "." を含まない場合)
-
現在のロケールで指定された NumericGroupSeparator (format が "." を含まない場合)
-
現在のロケールで指定された PlusSign プロパティ (format が "."を含まない場合)
-
現在のロケールで指定された MinusSign プロパティ (format が "."を含まない場合)
-
“.” (format が "." を含む場合)
-
"," (format が "." を含む場合)
-
“+” (format が "." を含む場合)
-
“-” (format が "." を含む場合)
-
-
文字列 “INF” と “NAN” およびそれらの変異形 (format が “D” を含む場合)
例
これらの例は、異なる形式がどのように $INUMBER の動作に影響するかを示しています。すべて、現在のロケールが既定のロケールであると仮定します。
以下の例では、"L" 形式コードのため $INUMBER は先行マイナス符号を受け入れ、-123456789.12345678 を返します。
WRITE $INUMBER("-123,4,56,789.1234,5678","L")
以下の例では、符号が先行していながら、"T" 形式コードで後続符号を使用するように指定しているので、$INUMBER は <ILLEGAL VALUE> エラーを生じます。
WRITE $INUMBER("-123,4,56,789.1234,5678","T")
以下の例では、最初の $INUMBER は成功し、負の数を返します。2番目の $INUMBER では、fnumber は符号を含んでいますが、"P" 形式コードでは、負の数に符号を付けるのではなく括弧で囲むように指定されているので、<ILLEGAL VALUE> エラーが発生します。
WRITE !,$INUMBER("(123,4,56,789.1234,5678)","P")
WRITE !,$INUMBER("-123,4,56,789.1234,5678","P")
以下の例では、符号がありながら、"-" 形式コードで符号で使用しないように指定しているので、$INUMBER は <ILLEGAL VALUE> エラーを生じます。
WRITE $INUMBER("-123,4,56,789.1234,5678","-")
以下の例では、$INUMBER は失敗しますが、符号の不正使用を原因とするエラーは発生せず、erropt として指定されている文字列 "ERR" をその値として返します。
WRITE $INUMBER("-123,4,56,789.1234,5678","-","ERR")
以下の例は、-23456789.123456789 を返します。先行符号の使用は、"L" で指定される形式に従っており、小数点の左側に 3 桁ごとに必ずコンマがあり、右側にはコンマがないことは、"," コードで指定される厳密な形式に従っているため、$INUMBER は指定した fnumber を有効な値として受け入れます。
WRITE $INUMBER("-23,456,789.123456789","L,")
以下の例で、“E” コードは科学的記数法の文字列の数値への変換を許可しています。すべての形式コードは数値リテラルとして科学的記数法をサポートしますが、文字列として科学的記数法をサポートするのは “E” (または “G”) のみです。この例では、変数および連結を使用して科学的記数法の文字列値を提供します。
SET num=1.234
SET exp=-14
WRITE $INUMBER(1.234E-14,"E","E-lit-err"),!
WRITE $INUMBER(num_"E"_exp,"E","E-string-err"),!
WRITE $INUMBER(1.234E-14,"L","L-lit-err"),!
WRITE $INUMBER(num_"E"_exp,"L","L-string-err"),!
以下の例では、小数および定数 pi の “L” コードおよび “D” コードにより返される値を比較します。“D” コードは IEEE 浮動小数点 ($DOUBLE) 数に変換します。
WRITE $INUMBER(1.23E-23,"L"),!
WRITE $INUMBER(1.23E-23,"D"),!
WRITE $INUMBER($ZPI,"L"),!
WRITE $INUMBER($ZPI,"D"),!
$INUMBER と $FNUMBER の相違点
大半の形式コードは、$INUMBER と $FNUMBER で類似した意味を持ちますが、各コードによって引き起こされる正確な動作は、実行される検証と変換の性質により、関数によって異なります。
特に、$INUMBER での “-” と “+” の形式コードは、$FNUMBER の場合と同じ意味になるわけではありません。$FNUMBER で、"-" と "+" は相互排他的ではありません。"-" は (抑制することによって) MinusSign にのみ影響し、"+" は (挿入することによって) PlusSign にのみ影響します。$INUMBER では、"-" と "+" は相互排他的です。"-" は符号が許可されないという意味であり、"+" は符号が必ず必要であるという意味です。
小数点区切り文字
$INUMBER は、fnumber の整数部分および小数部分の間の区切り文字として、現在のロケールの DecimalSeparator プロパティの値を使用します (既定は ".")。“.” 形式コードが指定されると、現在のロケールに関係なくこの区切り文字は “,” です。
ユーザのロケールの DecimalSeparator 文字を決定するには、以下のように GetFormatItem()Opens in a new tab メソッドを呼び出します。
WRITE ##class(%SYS.NLS.Format).GetFormatItem("DecimalSeparator")
数値グループ・セパレータおよびサイズ
$INUMBER は、fnumber の整数部分の桁のグループ間の区切り文字として、現在のロケールの NumericGroupSeparator プロパティの値を使用します (既定は ",")。これらのグループの大きさは、現在のロケールの NumericGroupSize プロパティによって決まります (既定は “3”)。"." 形式コードが指定されると、この区切り文字は "." であり、現在のロケールに関係なく 3 桁ごとに表示されます。
ユーザのロケールの NumericGroupSeparator 文字と NumericGroupSize 数を決定するには、以下のように GetFormatItem()Opens in a new tab メソッドを呼び出します。
WRITE ##class(%SYS.NLS.Format).GetFormatItem("NumericGroupSeparator"),!
WRITE ##class(%SYS.NLS.Format).GetFormatItem("NumericGroupSize")
プラス記号とマイナス記号
$INUMBER は、現在のロケールの PlusSign プロパティ値および MinusSign プロパティ値 (既定では “+” と “-”) を使用します。“.” 形式コードが指定されると、これらの記号は、現在のロケールに関係なく、“+” と “-” に設定されます。
ユーザのロケールの PlusSign 文字および MinusSign 文字を決定するには、以下のように GetFormatItem()Opens in a new tab メソッドを呼び出します。
WRITE ##class(%SYS.NLS.Format).GetFormatItem("PlusSign"),!
WRITE ##class(%SYS.NLS.Format).GetFormatItem("MinusSign")
関連項目
-
$DOUBLE 関数
-
$FNUMBER 関数
-
$ISVALIDNUM 関数
-
$NORMALIZE 関数
-
$NUMBER 関数