$NORMALIZE

数値を検証して返し、指定された小数桁数に丸めます。

Synopsis

$NORMALIZE(num,scale)

パラメータ

num	検証される数値。数値、文字列値、変数名、あるいは有効な Caché ObjectScript 式です。
scale	返り値としてnum が丸められる有効な小数桁数。この数は、num の実際の小数桁数より大きい場合も、小さい場合もあります。

概要

$NORMALIZE 関数は num を検証し、num を正規化した形式を返します。また、scale パラメータを使用して、小数桁数の丸め (または切り捨て) を行います。scale パラメータを使用して 10 進数を指定した小数桁数に丸めたり、10 進数を整数に丸めたり、10 進数を整数に切り捨てたりすることができます。

パラメータ

num

検証される数は整数、10 進数、または指数 (文字 "E" または "e") のいずれかです。文字列、式、または数に解釈される変数のいずれかになることもあります。符号付きや符号なし、先頭、または末尾に 0 がついていることもあります。$NORMALIZE は、文字ごとに検証を行います。以下の場合は、検証を中止し、文字列の検証された部分を返します。

num が 0–9、+ 符号、– 符号、小数点(.)、および指数を表す "E" または "e" 以外の任意の文字を含む場合。
num が複数の小数点、文字 "E" または "e" を含む場合。
num で + 符号または – 符号が数値の後にある場合、これらは末尾の符号とみなされ、それ以降の数値は解析されません。
指数を表す文字 "E"、もしくは "e" に数値の整数が続いていない場合。

scale パラメータ値を使用すると、返り値は、num 値を丸めた、または切り捨てた値となります。num 変数の実際の値は、$NORMALIZE 処理によって変更されません。

scale

必須の scale パラメータは、丸める小数桁数を指定するために使用されます。指定された値に応じて、scale は、小数桁数に影響を与えない、指定された小数桁数に丸める、整数に丸める、または整数に切り捨てる場合があります。

非負数の scale 値を使用して、numを指定された小数桁数に丸めることができます。丸めるとき、値 5、またはそれ以上の値は切り上げられます。小数桁数の丸めを避けるには、scale を num で可能な小数桁数よりも大きい値に設定します。scale 値に 0 を指定すると、num は整数値 (3.9 = 4) に丸められます。scale 値に –1 を指定すると、num は整数値 (3.9 = 3) に切り捨てられます。非数値の scale 値や NULL 文字列は、scale 値 0 に相当します。

scale には整数値を指定します。scale 値の小数桁数は無視されます。num で指定された小数桁数よりも大きい scale 値を指定することができます。–1 の scale 値を指定することもできます。それ以外の負の scale 値はすべて、<FUNCTION> エラーが返されます。

例

以下の例では、$NORMALIZE の各呼び出しで、指定された丸め (または整数切捨て）を使用して正規化された num が返されます。

   WRITE !,$NORMALIZE(0,0)       ; All integers OK
   WRITE !,$NORMALIZE("",0)      ; Null string is parsed as 0
   WRITE !,$NORMALIZE(4.567,2)   ; Decimal numbers OK
   WRITE !,$NORMALIZE("4.567",2) ; Numeric strings OK
   WRITE !,$NORMALIZE(-+.0,99)   ; Leading/trailing signs OK
   WRITE !,$NORMALIZE(+004.500,1) ; Leading/trailing 0's OK
   WRITE !,$NORMALIZE(4E2,-1)     ; Exponents OK

以下の例で、$NORMALIZE の各呼び出しは、num の数値サブセットを返します。

   WRITE !,$NORMALIZE("4,567",0)
     ; NumericGroupSeparators (commas) are not recognized
     ; here validation halts at the comma, and 4 is returned.
   WRITE !,$NORMALIZE("4A",0)
     ; Invalid (non-numeric) character halts validation
     ; here 4 is returned.

以下の例は、scale パラメータを使用して、返り値を丸める (または切り捨てる) 方法を示します。

   WRITE !,$NORMALIZE(4.55,2)
     ; When scale is equal to the decimal digits of num,
     ; all digits of num are returned without rounding.
   WRITE !,$NORMALIZE(3.85,1)
     ; num is rounded to 1 decimal digit, 
     ; (with values of 5 or greater rounded up) 
     ; here 3.9 is returned.
   WRITE !,$NORMALIZE(4.01,17) 
     ; scale can be larger than number of decimal digits,
     ; and no rounding is peformed; here 4.01 is returned.
   WRITE !,$NORMALIZE(3.85,0)
     ; When scale=0, num is rounded to an integer value.
     ; here 4 is returned.
   WRITE !,$NORMALIZE(3.85,-1)
     ; When scale=-1, num is truncated to an integer value.
     ; here 3 is returned.

メモ

$NORMALIZE と $NUMBER の比較

$NORMALIZE 関数と $NUMBER 関数は両方とも数を検証し、指定された数を検証して返します。

これら 2 つの関数では、検証の条件は異なります。必要に応じて、それぞれの関数を使いわけてください。

これら 2 つの関数は、符号付き、または符号なしの整数 (- 0 を含む)、指数 ("E" または "e" 付き)、および 10 進数を解析します。ただし、$NUMBER は 10 進数 (10 進数になる負の指数を含む) を拒否するように ("I" 形式を使用して) 設定できます。2 つの関数は両方とも、数 (123.45) と数値文字列 ("123.45") を解析します。
どちらの関数も、先頭と末尾のゼロを削除します。10 進文字は、ゼロでない値が続かない限りストリッピングされます。
NumericGroupSeparator を含む数値文字列。$NUMBER は format パラメータ (または現在のロケールに対する既定値) を基にして、NumericGroupSeparator 文字 (アメリカ形式はコンマ (,)、ヨーロッパ形式はピリオド (.) もしくはアポストロフィ (') と 10 進文字 (アメリカ形式はピリオド (.)、ヨーロッパ形式はコンマ (,)) を解析します。また、NumericGroupSeparator 文字の任意の数を許可し、削除します。例えばアメリカ形式は、数 123456.99 として "123,,4,56.99" を検証します。$NORMALIZE は、NumericGroupSeparator 文字を認識しません。これは、非数値文字に出会うまで文字ごとに検証します。例えば "123,456.99" を、数 123 として検証します。
先頭の複数の符号 (+ と - ) は、数に対する 2 つの関数両方によって解釈されます。$NORMALIZE だけは、引用符付き数値文字列に入った先頭の複数の符号を受け入れます。
末尾の + と - 符号。両方の関数は、数の末尾の符号を受け入れません。引用符付きの数値文字列では、$NUMBER は 1 つの (そして唯一の) 末尾の符号を解析します。$NORMALIZE は、複数の末尾符号を解析します。
括弧。$NUMBER は、引用符付き文字列での符号なしの数を囲む括弧を、負の数を示すものとして解析します。$NORMALIZE は、非数値文字として括弧を処理します。
複数の 10 進文字を含む、数値文字列。$NORMALIZE は 2 番目の 10 進文字を検出するまで、文字ごとに検証を行います。例えばアメリカ形式は、"123.4.56" を数 123.4 として検証します。$NUMBER は、1 つ以上の 10 進文字を含む任意の文字列を無効な数として受け入れません。

他の非数値文字を含む数値文字列。$NORMALIZE は、アルファベット文字を検出するまで、文字ごとに検証を行います。これは、"123A456" を数 123 として検証します。$NUMBER は文字列全体を検証し、"123A456" を無効な数として受け入れません。
NULL 文字列。$NORMALIZE は、NULL 文字列をゼロ (0) として解析します。$NUMBER は、NULL 文字列を受け入れません。

$NUMBER 関数は、オプションで min/max の範囲チェックを行います。範囲チェックは、$ISVALIDNUM 関数を使用して行うこともできます。

$NORMALIZE、$NUMBER、および $ISVALIDNUM はすべて、指定された小数桁数に 10 進数を丸めます。$NORMALIZE は、小数桁数の丸め、および 10 進数の丸めまたは切り捨てを行って、整数を返します。例えば、$NORMALIZE は 488.65 を 488.7 または 489 に丸めるかまたは、488 に切り捨てることができます。$NUMBER は、10 進数または整数を丸めることができます。例えば、$NUMBER は 488.65 を 488.7、489、490、または 500 に丸めることができます。