名前 | 形式 | 機能説明 | 戻り値 | エラー | 使用法 | 属性 | 関連項目
#include <wchar.h>unsigned long int wcstoul(const wchar_t *nptr, wchar_t **endptr, int base);
wcstoul() 関数は、 nptr が示すワイド文字列の先頭部分を unsigned long int つまり符号なしロング整数表現に変換します。 まず、指定されたワイド文字列を 3 つの部分に分解します。 初めの部分は、 iswspace(3C) で規定される空白のワイド文字コードの並びで、空の場合もあります。 次が変換対象となる文字コードの並びで、 base の値で指定された基数で表される整数として解釈されます。 最後の部分は、解釈不能なワイド文字コードのシーケンスで、 これには入力文字列の終わりの NULL ワイド文字コードも含まれます。 分割後、変換対象となる文字コードの並びを符号なし整数に変換しようと試み、 その結果を返します。
base の値が 0 のとき、 変換対象となる文字コードの並びの値は 10 進、8 進、または 16 進の定数であると予想されます。 定数には + または - の符号が付くこともあります。 10 進定数は 0 以外の数で始まり、いくつかの 10 進数で構成されます。 8 進定数は接頭辞 0 で始まり、その後に 0 から 7 までの数字がいくつか続きます。 16 進定数は、接頭辞 0x または 0X で始まり、その後に 0 から 9 までの数字および a ( または A) から f ( または F) までの文字 ( 数値 10 から 15 に対応 ) がいくつか続きます。
base の値が 2 から 36 までの範囲のとき、変換対象となる文字コードの並びの形式は base が示す基数に基づいた整数を表す一連の数字または文字 であると予想されます。 先頭に + または - の符号が付加されることはありますが、 整数の接尾辞は含まれません。文字 a ( または A) から z ( または Z) は、それぞれ 10 から 35 までの値に対応します。 base の値以内の範囲にある文字だけが、数値に対応することができます。 base の値が 16 のとき、値を表す一連の数字や文字の前に、 0x または 0X のワイド文字コード表現を付加することができます。 符号が存在していれば、そのあとに付加します。
変換対象となる文字コードの並びとは、 入力ワイド文字列中の最初の空白以外のワイド文字コードで始まる、 予想された形式の、 最長のワイド文字コード群であると定義できます。 入力ワイド文字列が空の場合、または空白を表すワイド文字コード だけからなる場合、または最初の空白以外のワイド文字コードが符号でもなく 指定可能な数字や文字でもない場合、 変換対象となる文字コードの並びには ワイド文字コードが 1 つも含まれません。
変換対象となる文字コードの並びが 予想どおりの形式であり、 base の値が 0 の場合、最初の数字で始まる一連のワイド文字コードは、 整定数であると解釈されます。 変換対象となる文字コードの並びが 予想どおりの形式であり、 base の値が 2 から 36 までの範囲にある場合、その値を基数として 変換が行われます。文字に対しては、前述したような方法で 数値が割り当てられます。 変換対象となる文字コードの並びが負の符号 (–) で始まっている場合、変換の結果として得られた 値は負となります。 endptr が示すオブジェクトには、 最終のワイド文字列へのポインタが書き込まれます。 ただし endptr が NULL ポインタの場合を除きます。
ロケールが POSIX 以外の場合、 変換対象となる文字コードの並びの形式も使用できます。
変換対象となる文字コードの並びが空の場合、または 予想された形式ではない場合、変換処理は行われません。 またこのとき、 endptr が示すオブジェクトには、 nptr の値が書き込まれます。 ただし endptr が NULL ポインタの場合を除きます。
エラー発生時には 0 および ULONG_MAX が返されますが、 0 は正常終了の場合にも返される値です。 したがってエラー発生の有無を知りたいアプリケーションは、 errno を 0 に設定して wcstoul() を呼び出し、処理実行後に errno の値をチェックする必要があります。 値が 0 でなければ、エラーが起こったものと判断できます。
処理が正常に終了すると、 wcstoul() は、変換された値 ( もしあれば ) を返します。 errno の設定は変更しません。 変換が行われなかった場合、 0 が返されます。このとき、 errno はエラー発生を示す値に設定されることがあります。 正しい値が表現可能な値の範囲外であれば、 ULONG_MAX が返され、 errno は ERANGE の値に設定されます。
wcstoul() 関数は、以下の条件のとき異常終了します。
base の値はサポートされていない
返されるべき値は表現不能である
また wcstoul() は、以下の条件のとき異常終了する場合があります。
変換が実行できない
wcstod(3C) や wcstol(3C) とは異なり、 wcstoul() は常に負ではない数を返す必要があります。 そのため wcstoul() の戻り値を wcstoul() の範囲外数値として使用します。 wcstoul() は、範囲外数値が常に負の場合、正確性を失うだけでなく、さらに深刻な 問題を生じることがあります。
次の属性については attributes(5) のマニュアルページを参照してください。
属性タイプ | 属性値 |
MT レベル | MT-Safe |