名前 | 形式 | 機能説明 | 戻り値 | エラー | 使用法 | 属性 | 関連項目
#include <wchar.h>double wcstod(const wchar_t *restrict nptr, wchar_t **restrict endptr);
wcstod()、wcstof()、および wcstold() 関数は、nptr が指すワイド文字列の先頭部分を、それぞれ、double、float、および long double 型の表現に変換します。これらの関数はまず、指定されたワイド文字列を次の 3 つのシーケンスに分解します。
最初のシーケンス。空白などのワイド文字から構成されます。つまり、iswspace(3C) で識別されるワイド文字です。このシーケンスは空の場合もあります。
変換対象シーケンス。変換対象として認識されるワイド文字から構成されます。このシーケンスは、浮動小数点の定数として、あるいは、無限または非数を表す文字列として解釈されます。
最後のシーケンス。変換対象として認識されないワイド文字から構成されます。つまり、終了ヌルなどのワイド文字です。このワイド文字は 1 文字の場合も複数文字の場合もあります。
次に、これらの関数は、変換対象シーケンスを浮動小数点数に変換して、その結果を返します。
変換対象シーケンスの期待される形式は、プラスまたはマイナス記号 (任意) の後に、次のいずれか 1 つが続くものです。
10 進数のシーケンス (空でない)。この後には、基数点 (任意) が続き、さらには、指数部 (任意) が続くこともあります。
0x または 0X とそれに続く 16 進数のシーケンス (空でない)。この後には、基数点 (任意) が続き、さらには、指数部 (任意) が続くこともあります。
INF または INFINITY。あるいは、これと等価なワイド文字列 (大文字小文字の区別はない)。
NAN または NAN (n-wchar-sequenceopt)。あるいは、これと等価なワイド文字列 (NAN 部分の大文字小文字の区別はない)。ここで、w-wchar-sequence は次のとおりです。
n-wchar-sequence: digit nondigit n-wchar-sequence digit n-wchar-sequence nondigit
wcstod() のデフォルトのモードでは、10 進数、INF/INFINITY、および、NAN/NAN (n-char-sequence) の形式だけが認識されます。C99/SUSv3 モードでは、これに加えて、16 進数の文字列も認識されます。
wcstod() のデフォルトのモードでは、NAN (n-char-equence) 形式の n-char-sequence 部分には、「)」(右の丸括弧) または「\ 」(ヌル) を除く、すべての文字を含むことができます。C99/SUSv3 モードでは、n-char-sequence には、英大文字、英小文字、数字、および「_」(下線) だけを含むことができます。
wcstof() 関数と wcstold() 関数は、常に、C99/SUSv3 準拠モードで動作します。
変換対象シーケンスは、「指定されたワイド文字列内で最初の空白以外のワイド文字から始まる最初で最長の部分シーケンス」であると定義されます。つまり、これを「期待される形式」と呼びます。変換対象シーケンスが期待される形式でない場合、変換対象シーケンスにワイド文字は含まれません。
変換対象シーケンスが浮動小数点数の期待される形式である場合、変換対象シーケンスは次のように解釈されます。変換対象シーケンスが数字または基数点文字から始まる場合、このシーケンスは、C 言語の規則に従って、浮動小数点の定数であると解釈されます。ただし、C 言語の規則と異なる点として、ピリオドの代わりに基数点文字が使用されます。また、変換対象シーケンスが 10 進数の浮動小数点数であり、かつ、指数部または基数点文字のどちらも存在しない場合、あるいは、変換対象シーケンスが 16 進数の浮動小数点数であり、かつ、2 進数の指数部が存在しない場合、変換対象シーケンスの最後にある数字の後に、値が 0 で適切な型の指数部が続くと想定されます。変換対象シーケンスがマイナス記号から始まる場合、このシーケンスは負であると解釈されます。変換対象シーケンスが INF または INIFITITY である場合、このシーケンスは無限であると解釈されます。変換対象シーケンスが NAN または NAN (n-wchar-sequenceopt) である場合、このシーケンスは非数であると解釈されます。endptr が指すオブジェクトには、最後のシーケンスへのポインタが格納されます。ただし、endptr がヌルポインタである場合を除きます。
変換対象シーケンスが 10 進数または 16 進数の形式である場合、変換の結果の値は、一般的な浮動小数点丸め方向モードに従って正しく丸められます。変換の結果、場合によっては、浮動小数点の不正確な例外、アンダーフローの例外、またはオーバーフローの例外が発生することもあります。
基数点文字は、プログラムのロケール (カテゴリ LC_NUMERIC) で定義されます。POSIX ロケールなど、基数点文字が定義されていないロケールでは、基数点文字のデフォルトはピリオド (.) です。
変換対象となる文字コードの並びが空の場合、または期待された形式ではない場合、変換処理は行われません。またこのとき、endptr が示すオブジェクトには、nptr の値が書き込まれます。ただし endptr が NULL ポインタの場合を除きます。
wcstod() 関数は、正常終了した場合、errno の設定を変更しません。
wstod() 関数は、wcstod() と同等です。
watof(str) 関数は wstod(str, (wchar_t **)NULL) と同じです。
これらの関数は、正常終了した場合、変換した値を返します。変換しなかった場合は、0 を返します。
変換された値が表現可能な値の範囲を超えてしまった場合、(値の符号によって)、±HUGE_VAL、±HUGE_VALF、または、±HUGE_VALL が返されます。そして、浮動小数点オーバーフローの例外が発生して、errno は ERANGE に設定されます。
値を変換した結果としてアンダーフローの例外が発生した場合、正しく丸められた結果 (通常、通常以下、または 0) が返されます。そして、浮動小数点アンダーフローの例外が発生して、errno は ERANGE に設定されます。
wcstod() および wstod() 関数は、以下の状態のときエラーを返します。
返されるべき値が、オーバフローまたはアンダフローを起こしてしまう
wcstod() および wcstod() 関数は、以下の状態のときエラーを返します。
変換が実行できない
エラー発生時には 0 が返されますが、これは正常終了の場合にも返される値です。したがってエラー発生の有無を知りたいアプリケーションは、errno を 0 に設定して wcstod()、wcstof()、wcstold() または wstod() を呼び出し、処理実行後に errno の値を調べる必要があります。値が 0 以外であれば、エラーが起こったものと判断できます。
次の属性については attributes(5) のマニュアルページを参照してください。
属性タイプ | 属性値 |
MT レベル | MT-Safe |
インタフェースの安定性 | wcstod()、wcstof()、および wcstold() は標準 |