4.3.2 val_to_string関数

val_to_string関数は、項目参照の値または数値リテラルを数値型とみなし、指定された書式で文字列を返却します。

val_to_string関数の書式を以下の図に示します。

図4.8 val_to_string関数の書式

数値変換書式

数値変換書式は、以下の文字列とセパレータ文字を使用して、任意の順番で指定できます。

表4.5 数値変換書式に指定可能な文字列
カテゴリ	書式要素	意味
数値	9	指定した桁に値がある場合だけ、その値を出力します。
数値	0	指定した桁に値があればその値、なければ0を出力します。
文字	B	書式要素に0を指定した場合に、0の代わりに半角空白を出力します。
文字	S	先頭に符合を出力します。

表4.6 セパレータ文字に指定可能な文字
名称	文字
ピリオド	.
カンマ	,

注意

指定された値の整数部が変換書式の桁数を超えている場合、変換書式の桁数分の“#”を出力します。
指定された値の小数部が変換書式の桁数を超えている場合、変換書式の桁数で切り捨てられます。
変換書式の桁数で切り捨てられた結果、小数部に不要な“0”が存在する場合、正規化して処理されます。(結果が“0.0100”の場合、正規化されて“0.01”になります)
整数値が0で小数部が存在する場合、整数部の値はないとものとして処理されます。 (“0.12”の場合は“.12”として、“0”の場合は"0"として処理します。)
変換書式に“9”が指定され、小数部の値がない場合、小数点指定は無視されます。
カンマ(,)は小数点の右側には指定できません。
セパレータ文字を連続して指定することはできません。(例:999,,99)
セパレータ文字は、数値カテゴリの後に続けて指定してください。
整数部は、省略できません。
“S”およびB”は、変換書式の最前方に指定します。“S”とB”の両方を同時に指定することもできます。
セパレータ文字を、先頭または末尾に指定できません。(例:.99999.)
セパレータ文字だけを指定することはできません。(例:,,,)
“S”、“B”または“.”は、複数指定できません。

参照

項目参照については、“3.1.9 項目参照”を参照してください。
数値リテラルについては、“3.1.6 リテラル”を参照してください。

復帰値

変換が正常に動作した場合は、文字列型を返します。

項目参照の値が文字列型、または数値型でない場合、構文エラーとなります。空の場合は空を返します。
項目参照の値が数値型の範囲を超える場合、オーバーフローが発生し、連結条件式、グループ式、またはソート式の延長で使用されているときは、エラーとなります。リターン式、または集計式の延長で使用されているときは、以下の文字列を出力します。
結果の値が0となる場合、符号はつきません。ただし、書式要素に“S”が設定された場合、“+”が出力されます。

"ERR(=val_to_string(数値, 変換書式))"

例1

$nmが、“1234.56”の場合

val_to_string( $nm, "9,999.99")

文字列として“1,234.56”を出力します(指定された桁にカンマ、小数点を付加します)。

例2

$nmが、“1234.56”の場合

val_to_string( $nm, "SB9,990.999")

文字列として“+_1,234.56”を出力します。(_は半角空白を示します)

例3

$nmが、“1234.56”の場合

val_to_string( $nm, "S9999.9")

文字列として“+1234.5”を出力します。( 常に符合が付加されます。指定された桁で切り捨てます。 )

例4

$nmが、“1234.56”の場合

val_to_string( $nm, "00000.000")

文字列として“01234.560”を出力します(指定された桁に値がない場合は0パディングします)。

例5

$nmが、“12345.6”の場合

val_to_string( $nm, "S9,999.9")

文字列として“####.#”を出力します(指定桁以上の値が指定された場合、指定桁数の“#”を出力します。この場合、符号もカンマも出力しません)。

例6

$nmが、“1234”の場合

val_to_string( $nm, "9999.99")

文字列として“1234”を出力します(小数点は付加しません）。

例7

$nmが、“1234”の場合

val_to_string( $nm, "0000.00")

文字列として“1234.00”を出力します(指定された桁に値がない場合は0パディングします）。

例8

$nmが、“0.1234”の場合

val_to_string( $nm, "9.99999")

文字列として“.1234”を出力します。

ポイント

“0.1234”と出力したい場合は、変換書式に“0.99999”と指定します。
$nmが“0”の場合は、文字列として“0”を出力します。

例9

$nmが、-1234.56の場合

val_to_string( $nm, "B00000.000")

文字列として“-_1234.56_”を出力します(_は半角空白を示します）。

例10

$nmが、-0.002の場合

val_to_string( $nm, "S0.09")

文字列として“+0.0”を出力します(結果の値が0となるため、符合はプラス(+)に統一されます）。

例11

$nmが、-0.002の場合

val_to_string( $nm, "0.09")

文字列として“0.0”を出力します。