"monetary": Monetary formatting and Rounding doubles in C
 Happy Hacking!

monetary: 浮動小数点数を金額フォーマットで文字列に変換するユーティリティ

この C 言語ユーティリティは、double 型の浮動小数点数を金額フォーマットで文字列に変換するか、あるいは数値を表す文字列を同様に変換します。小数点 '.' を出力する桁位置を指定することが可能で、整数部の 3 桁毎に挿入する区切り文字はカンマ文字 ',' に固定しています。
金額フォーマットで変換された結果の文字列を、通常の数値を表す文字列に戻すことと浮動小数点数 (double 型) に変換することもできます。

round_double: 浮動小数点数値を丸めるユーティリティ

このユーティリティは、浮動小数点数値を丸める (四捨五入、切り上げ、切り捨てる) 操作を行います。

これらの API を使用するためのヘッダは monetary.h で、API の実装は monetary.c です。API の説明は、この文書で後述しています。

テスト・プログラム monetary-test.c と make ファイル Makefile を記述しました。テストは、

        $ make clean; make; make test

        << monetary() tests... >>
         ----+----+----+----+----+
        [-1,234,567,890,124   ] (-1234567890123.675049)
        [ 1,234,567,890,124   ] (1234567890123.675049)
        [  -0    ] (-0.005000)
        [   0    ] (0.005000)
        [890     ] (-1234567890.005000)
        [890     ] (1234567890.005000)
        [-1,234,567,890,123.7 ] (-1234567890123.675049)
        [ 1,234,567,890,123.7 ] (1234567890123.675049)
        [  -0.0  ] (-0.005000)
        [   0.0  ] (0.005000)
        [890.01  ] (-1234567890.005000)
        [890.01  ] (1234567890.005000)
        [-1,234,567,890,123.68] (-1234567890123.675049)
        [ 1,234,567,890,123.68] (1234567890123.675049)
        [  -0.01 ] (-0.005000)
        [   0.01 ] (0.005000)
        [890.0050] (-1234567890.005000)
        [890.0050] (1234567890.005000)
         ----+----+----+----+----+
        [       1,234,567,890 ] (1234567890.005000)
        [        1,234,567,890] (1234567890.005000)
        [(null)] (NaN) (errno = 33 "Numerical argument out of domain")
        [(null)] (-Inf) (errno = 33 "Numerical argument out of domain")
        [(null)] (Inf) (errno = 33 "Numerical argument out of domain")

        << strmonetary() tests... >>
          ----+----+----+----+----+
        [-1,234,567,890,123   ] <-1234567890123.675049>
        [ 1,234,567,890,123   ] <1234567890123.675049>
        [  -0    ] <-0.005000>
        [   0    ] <0.005000>
        [890     ] <-1234567890.005000>
        [890     ] <1234567890.005000>
        [-1,234,567,890,123.6 ] <-1234567890123.675049>
        [ 1,234,567,890,123.6 ] <1234567890123.675049>
        [  -0.0  ] <-0.005000>
        [   0.0  ] <0.005000>
        [890.00  ] <-1234567890.005000>
        [890.00  ] <1234567890.005000>
        [-1,234,567,890,123.67] <-1234567890123.675049>
        [ 1,234,567,890,123.67] <1234567890123.675049>
        [  -0.00 ] <-0.005000>
        [   0.00 ] <0.005000>
        [890.0050] <-1234567890.005000>
        [890.0050] <1234567890.005000>
         ----+----+----+----+----+
        [       1,234,567,890 ] <1234567890.005000>
        [        1,234,567,890] <1234567890.005000>
        [             123.000 ] <123.>
        [            -456.000 ] <-456>
        [        123          ] <123.>
        [       -456          ] <-456>
        [,890.005] <1234567890.005000>
        [  123.456 ] <123.456abc> (errno = 0 "No error")
        [(null)] <xyz> (errno = 22 "Invalid argument")
        [(null)] <> (errno = 22 "Invalid argument")
        [(null)] <(null)> (errno = 22 "Invalid argument")

API の説明

1. 浮動小数点数を金額フォーマットで文字列変換する: monetary()
   

   char *monetary(double amounts
                      size_t max_len
                    , size_t faractional_digits
                    , size_t additions
                    , char  *str
                    , size_t sz
                    )
   

   amounts に変換する浮動小数点数を double 型で渡します。
   max_len には変換後の文字列の最大文字列長を指定します。
   faractional_digits には変換後の小数点数の桁数を指定します。
   additions には変換後の小数点の文字列末尾からの桁位置 (0 以上) を指定します。
   str には変換後の文字列が出力されます。
   sz には str のメモリサイズをバイト単位で指定します。

   正常終了の場合、変換後の文字列を設定されたメモリ領域のアドレスとして str を返します。不正な引数を渡された場合、NULL を返し errno にエラー詳細を出力します。

   • EINVAL : 桁位置指定が矛盾しているような、不正な引数を渡された場合
   • ENOMEM : 金額フォーマットを行うための動的メモリを獲得できない場合 (メモリ不足)
   • EDOM : amounts に非数 ("NaN") あるいは無限大数 ("-Inf", "Inf") といった定義域外の浮動小数点数を渡された場合
   
   
2. 数値を表す文字列を金額フォーマットで変換する: strmonetary()
   

   char *strmonetary(char *src
                    , size_t src_sz
                    , size_t max_len
                    , size_t faractional_digits
                    , size_t additions
                    , char  *str
                    , size_t sz
                    )
   

   src に変換する数値文字列を渡します。
   src_sz に src が指す文字列の文字列長を渡します。
   max_len には変換後の文字列の最大文字列長を指定します。
   faractional_digits には変換後の小数点数の桁数を指定します。
   additions には変換後の小数点の文字列末尾からの桁位置 (0 以上) を指定します。
   str には変換後の文字列が出力されます。
   sz には str のメモリサイズをバイト単位で指定します。

   str の先頭の空白文字は無視し、数字列の直後に存在する数字以外の文字がある場合は数値文字列の終端として扱います。いずれの場合も正常終了します。

   正常終了の場合、変換後の文字列を設定されたメモリ領域のアドレスとして str を返します。不正な引数を渡された場合、NULL を返し errno にエラー詳細を出力します。

   • EINVAL : 桁位置指定が矛盾していたり数字列でない文字列といった、不正な引数を渡された場合
   
   
3. 金額を表す文字列を数値を表す通常の文字列に変換する: monetary_to_numeral()
   

   char *monetary_to_numeral(char *mone
                           , char  *dst
                           , size_t sz
                           )
   

   mone に金額を表す文字列を渡します。
   dst には数値を表す通常の文字列の出力先バッファのアドレスを渡します。
   sz には dst のメモリサイズをバイト単位で指定します。

   mone の先頭と末尾の空白文字そして整数部の 3 桁毎の区切り文字 ',' は取り除いた上で、負符号 '-'、数字そして小数点 '.' を出力先に転送します。金額を表す文字列を構成する文字以外のものがあった場合は、異常終了します。

   正常終了の場合、dst に渡されたアドレスを返します。不正な引数を渡された場合、NULL を返し errno にエラー詳細を出力します。

   • EINVAL : 金額を表す文字列を構成しない文字を mone に渡された場合
   
   
4. 金額を表す文字列を浮動小数点数に変換する: monetary_to_double()
   

   double monetary_to_double(char *mone)
   

   mone に金額を表す文字列を渡します。
   

   浮動小数点数に変換した結果を戻り値にして返します。

   正常終了の場合、errno にゼロを出力します。変換に失敗した場合、ゼロ、HUGE_VAL、あるいは -HUGE_VAL を返し errno にエラー詳細を出力します。

   • EINVAL : 金額を表す文字列を構成しない文字を mone に渡された場合
   • ERANGE : mone が、浮動小数点数で扱える範囲を超えた数値を表している場合
   • ENOMEM : 変換処理のための動的メモリ獲得に失敗した場合 (メモリ不足)
   
   
5. 浮動小数点数値を丸める: round_double()
   

   double round_double(double value, int scale, Round_double_how_t how)
   

   value には丸められる浮動小数点数値を指定します。
   scale には丸めを行う桁位置を指定します。ゼロから 17 までを指定すると、小数点以下第 1 位から 18 位が丸める桁になります。-1 から -16 までを指定すると、整数部第 1 位から 16 位が丸める桁になります。
   how には丸めの操作を指定します。四捨五入を行うには Round_double_EVEN を、切り上げを行うには Round_double_UP を、切捨てを行うには Round_double_DOWN を指定します。

   不正な引数を渡された場合は無限大 INF を返し、errno に EINVAL を出力します。それ以外の場合は、丸めの結果を返します。