名前 | 形式 | 機能説明 | 戻り値 | エラー | 属性 | 関連項目 | 注意事項
#include <wchar.h>long int wcstol(const wchar_t *nptr, wchar_t **endptr, int base);
#include <widec.h>long int wstol(const wchar_t *nptr, wchar_t **endptr, int base);
wcstol() と wstol() の両関数は、nptr が示すワイド文字列の先頭部分を 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) までの文字がいくつか続きます。
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 ポインタの場合を除きます。
watol() 関数は wstol(str, (wchar_t **)NULL, 10) と同機能です。
watoll() 関数は longlong 型の watol() です。
watoi() 関数は (int)watol( ) と同機能です。
処理が正常に終了すると、wcstol() および wstol() は、変換された値 (もしあれば) を返します。変換が行われなかった場合、0 が返されます。このとき、errno はエラー状態を示す値に設定されることがあります。正しい値が表現可能な値の範囲外であれば、{LONG_MAX} または {LONG_MIN} のどれか (値の符号による) が返され、errno は ERANGE の値に設定されます。
wcstol() および wstol() 関数は、以下の条件のとき異常終了します。
base の値はサポートされていない
返されるべき値は表現不能である
また wcstol() および wstol() 関数は、以下の状態のときエラーを返します。
変換が実行できない
次の属性については attributes(5) のマニュアルページを参照してください。
属性タイプ | 属性値 |
---|---|
MT レベル | MT-Safe |
エラー発生時には 0、{LONG_MIN}、および {LONG_MAX} が返されますが、これらは正常終了の場合にも返される値です。したがってエラー発生の有無を知りたいアプリケーションは、errno を 0 に設定して wcstol() または wstol() を呼び出し、処理実行後に errno の値を調べる必要があります。値が 0 以外であれば、エラーが起こったものと判断できます。
代入時に必要であれば、または明示的に指定されていれば、longlong 型から long 型への切り捨てが発生することがあります。