wcstok() - ワイド文字ストリングのトークンへの分割

標準

標準/拡張機能 C/C++ 依存項目

ISO C 改訂
XPG4
XPG4.2
C99
Single UNIX Specification、バージョン 3

 両方  

形式

非 XPG4: 
#include <wchar.h>

wchar_t *wcstok(wchar_t * __restrict__wcs1, 
                const wchar_t * __restrict__wcs2, wchar_t ** __restrict__ptr);
XPG4: 
#define _XOPEN_SOURCE
#include <wchar.h>

wchar_t *wcstok(wchar_t *wcs1, const wchar_t *wcs2);
XPG4 および MSE: 
#define _XOPEN_SOURCE
#define _MSE_PROTOS
#include <wchar.h>

wchar_t *wcstok(wchar_t *wcs1, 
                const wchar_t *wcs2, wchar_t **ptr);

機能説明

wcstok() 関数に対する一連の呼び出しは wcs1 が指す ワイド・ストリングを一連のトークンに分割し、そのおのおのは wcs2 が指すワイド・ストリングから ワイド文字によって区切られます。3 番目の引数は、wcstok() 関数が同じストリングの走査を継続する のに必要な情報を保管する呼び出し元提供のワイド文字ポインターを 指します。

シーケンスの最初の呼び出し、wcs1 は ワイド文字ストリングを指しますが、同じワイド・ストリングの 以降の呼び出しでは、wcs1 は NULL ポインターに なります。wcs1 が NULL ポインターの場合には、ptr が指す値は同じワイド文字ストリングに対する直前の呼び出し によって設定された値に一致します。そうでない場合には、その値は無視されます。wcs2 が指す区切りワイド文字ストリングは、呼び出しによって異なることがあります。

シーケンスの最初の呼び出しは、wcs2 が指す現行の区切りワイド文字ストリングに含まれていない、最初のワイド文字として、wcs1 が指すワイド文字ストリングを検索します。そのようなワイド文字が見つからなかった場合には、wcs1 が指すワイド文字ストリングにトークンがなく、wcstok() は NULL ポインターを戻します。そのようなワイド文字が見つかった場合には、それは最初の トークンの初めです。

その後、wcstok() は、そこから現行の区切りワイド・ストリングに含まれているワイド文字を検索します。そのようなワイド文字が見つからなかった場合には、現行のトークン は wcs1 が指すワイド文字ストリングの終わりまで拡張し、それ以降にトークンを検索すると NULL ポインターが戻されます。そのようなワイド文字が見つかった場合には、それは現行のトークンを 終了する、NULL 文字によって上書きされます。

いずれの場合であっても、wcstok() 関数はポインター ptr に 十分な情報を保管するので、以降の呼び出しは NULL ポインターを 最初の引数の値とし、未変更のポインター値を 3 番目の引数として、前に戻されたトークン (あれば) の終了のすぐ後で検索を 開始します。

このワイド文字関数の動作は、現行ロケールの LC_CTYPE カテゴリーの影響を受けます。 カテゴリーを変更すると、未定義の結果が発生する可能性があります。

XPG4 の特殊な動作: プログラム・ソース・ファイル内の wchar ヘッダーをインクルードするステートメントより前に、XPG4 の動作を指定してフィーチャー・テスト・マクロを定義した場合、_MSE_PROTOS フィーチャー・テスト・マクロも定義しない限り、コンパイラーは、ユーザーのプログラムが wcstok() 関数の XPG4 版を使用するものと想定します。 XPG4 と他のフィーチャー・テスト・マクロのリストについては、表 1 を参照してください。

wcstok() 関数の XPG4 版のプロトタイプは、以下のとおりです。
wchar_t *wcstok(wchar_t *wcs1, const wchar_t *wcs2);

XPG4 の wcstok() 関数には、プログラムのストレージに、再始動情報のアドレスを指定するための 3 番目のパラメーターが脱落しています。代わりに、C/370™ がランタイム・ライブラリーのストレージ比較可能再始動情報を提供します。このライブラリーのストレージは、スレッド化アプリケーションに対して XPG4 wcstok() 関数をスレッド特有なものにする、スレッド単位に基づいて提供されることに注意してください。

戻り値

正常に実行された場合、wcstok() は、トークンの最初のワイド文字へのポインターを戻します。

トークンがない場合、wcstok() は NULL ポインターを戻します。

例

CELEBW22 
⁄* CELEBW22 *⁄
#include <wchar.h>
int main(void)
{

    static wchar_t str1[] = L"?a??b,,,#c";
    static wchar_t str2[] = L"¥t ¥t";
    wchar_t *t, *ptr1, *ptr2;

    t = wcstok(str1, L"?", &ptr1);     ⁄* t points to the token L"a"    *⁄
    t = wcstok(NULL, L",", &ptr1);     ⁄* t points to the token L"??b"  *⁄
    t = wcstok(str2, L" ¥t,", &ptr2);  ⁄* t is a null pointer           *⁄
    t = wcstok(NULL, L"#,", &ptr1);    ⁄* t points to the token L"c"    *⁄
    t = wcstok(NULL, L"?", &ptr1);     ⁄* t is a null pointer           *⁄

}

関連情報

親トピック: ライブラリー関数