名前 | 形式 | 機能説明 | 戻り値 | エラー | 使用法 | 属性 | 関連項目
#include <wchar.h>unsigned long wcstoul(const wchar_t *restrict nptr, wchar_t **restrict endptr, int base);
wcstoul() と wcstoull() 関数は、nptr が示すワイド文字列の先頭部分を unsigned long と unsigned long long 表現に変換します。まず、指定されたワイド文字列を 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 ポインタの場合を除きます。
変換対象シーケンスが空であるか、期待される形式でない場合、変換は実行されません。endptr が指すオブジェクトには、nptr の値が格納されます。ただし、endptr がヌルポインタである場合を除きます。
wcstoul() 関数は、正常終了した場合、errno の設定を変更しません。
エラー時には、0、{ULONG_MAX}、および {ULLONG_MAX} が返され、成功時には、有効な値が返されるため、エラー状態をチェックしたいアプリケーションは、wcstoul() または wcstoull() を呼び出す前に、errno を 0 に設定しておく必要があります。これにより、後で errno をチェックできます。
処理が正常に終了すると、wcstoul() は、変換された値 ( もしあれば ) を返します。errno の設定は変更しません。変換が行われなかった場合、0 が返されます。このとき、errno はエラー発生を示す値に設定されることがあります。正しい値が表現可能な値の範囲外であれば、ULONG_MAX が返され、errno は ERANGE の値に設定されます。
wcstoul() とwcstoull() 関数は、以下の条件のとき異常終了します。
base の値はサポートされていない
返されるべき値は表現不能である
また wcstoul() とwcstoull() は、以下の条件のとき異常終了する場合があります。
変換が実行できない
wcstod(3C) や wcstol(3C) とは異なり、wcstoul() とwcstoull() は常に負ではない数を返す必要があります。 そのため wcstoul() の戻り値を wcstoul() または wcstoull() の範囲外数値として使用します。wcstoul() または wcstoull() は、範囲外数値が常に負の場合、正確性を失うだけでなく、さらに深刻な 問題を生じることがあります。
次の属性については attributes(5) のマニュアルページを参照してください。
属性タイプ | 属性値 |
MT レベル | MT-Safe |
インタフェースの安定性 | 標準 |