名前 | 形式 | 機能説明 | 属性 | 関連項目 | 注意事項
#include <wchar.h>wchar_t *wcscat(wchar_t *ws1, const wchar_t *ws2);
#include <widec.h>wchar_t *wscat(wchar_t *ws1, const wchar_t *ws2);
#include <wchar.h>const wchar_t *wcschr(const wchar_t *ws, wchar_t wc);
#include <cwchar>wchar_t *std::wcschr(wchar_t *ws, wchar_t wc);
これらの関数は、wchar_t 型の NULL 文字で終了するワイド文字列を扱います。追加またはコピー処理を行うとき、受け取り側の文字列でオーバフロー状態が発生しても これらの関数はそれをチェックしません。以下の説明では ws 、ws1 、および ws2 は、wchar_t 型の NULL 文字で終了するワイド文字列を指しています。
wcscat() と wscat() の両関数は、ws2 が指すワイド文字列 ( 終端の NULL ワイド文字コードも含む ) をコピーして、ws1 が指すワイド文字列の終わりに追加します。ws1 の終端の NULL ワイド文字コードは、ws2 の先頭のワイド文字コードにより置き換えられます。重なりあうオブジェクト間でコピーが行われた場合、その結果は未定義です。両関数ともに s1 を返します。エラー発生を示す戻り値は定義されていません。
wcsncat() と wsncat() の両関数は、ws2 が指す配列中の n 個以下の数のワイド文字コードを、ws1 が指すワイド文字列の終わりに追加します。なお NULL のワイド文字コードとそれに続くワイド文字コードは、追加の対象とはなりません。ws1 の終端の NULL ワイド文字コードは、ws2 の先頭のワイド文字コードにより置き換えられます。追加されるワイド文字コードの終わりには、必ず NULL ワイド文字コードが付加されます。両関数ともに s1 を返します。エラー発生を示す戻り値は定義されていません。
wcscmp() と wscmp() の両関数は、ws1 と ws2 が示す 2 つのワイド文字列を比較します。両ワイド文字列中のコードを順番に比較して、両ワイド文字列が一致しない場合は、最初に一致しない両ワイド文字列の違いに応じて、 0 以外の値を返します。ws1 の指すワイド文字列中のコードが ws2 の指すワイド文字列中のコードより 大きい場合は 0 より大きい値を返し、逆に小さい場合は 0 より小さい値を返します。両ワイド文字列が一致する場合には 0 を返します。
wcsncmp() と wsncmp() の両関数は、ws1 が指す配列中の n 個以下の数のワイド文字コードと、ws2 が指す配列の内容とを比較します。ws1 の配列の中で、 NULL ワイド文字コード以降のワイド文字コードは 比較の対象とはなりません。両ワイド文字列中のコードを順番に比較して、両ワイド文字列が一致しない場合は、最初に一致しない両ワイド文字列の違いに応じて、 0 以外の値を返します。ws1 の指すワイド文字列中のコードが ws2 の指すワイド文字列中のコードより 大きい場合は 0 より大きい値を返し、逆に小さい場合は 0 より小さい値を返します。両ワイド文字列が一致する場合には 0 を返します。
wcscpy() と wscpy() の両関数は、ws2 が指すワイド文字列 ( 終端の NULL ワイド文字コードも含む ) を、ws1 が指す配列にコピーします。重なりあうオブジェクト間でコピーが行われた場合、その結果は未定義です。両関数ともに ws1 を返します。エラー発生を示す戻り値は定義されていません。
wcsncpy() と wsncpy() の両関数は、ws2 が指す配列中の n 個以下の数のワイド文字コードを、ws1 が指す配列に複写します。なお NULL のワイド文字コードに続くワイド文字コードは、複写の対象とはなりません。重なりあうオブジェクト間で複写が行われた場合、その結果は未定義です。ws2 が指す配列が、n 個未満のワイド文字コードからなるワイド文字列の場合、ws1 が指す出力先の配列には、合計コード数が n 個に達するまで NULL ワイド文字コードが書き込まれます。両関数ともに ws1 を返します。エラー発生を示す戻り値は定義されていません。
wcslen() と wslen() の両関数は、ws が指すワイド文字列中のワイド文字コードの個数を計算します。終端の NULL ワイド文字コードは、数には含まれません。両関数ともに ws を返します。エラー発生を示す戻り値は定義されていません。
wcschr() と wschr() の両関数は、ws が指すワイド文字列内にワイド文字コード wc が含まれていれば、最初の出現位置を報告します。wc の値は、wchar_t 型として表示可能な文字である必要があり、また現ロケール中の正しい文字に対応した ワイド文字コードである必要があります。終端の NULL ワイド文字コードは、ワイド文字列の一部と見なされます。処理が正常に終了すると、ワイド文字コードが見つかればその最初の出現位置を示すポインタを返し、見つからなければ NULL ポインタを返します。
wcsrchr() と wsrchr() の両関数は、ws が指すワイド文字列内にワイド文字コード wc が含まれていれば、最後の出現位置を報告します。wc の値は、wchar_t 型として表示可能な文字である必要があり、また現ロケール中の正しい文字に対応した ワイド文字コードである必要があります。終端の NULL ワイド文字コードは、ワイド文字列の一部と見なされます。処理が正常に終了すると、ワイド文字コードが見つかればその最後の出現位置を示すポインタを返し、見つからなければ NULL ポインタを返します。
windex() と wrindex() の両関数の動作は、それぞれ wschr() と wsrchr() の動作と同じです。
wcspbrk() と wspbrk() の両関数は、ws1 が指すワイド文字列内に、ws2 が指すワイド文字列中のいずれかのワイド文字コード が含まれていれば、その最初の出現位置を報告します。処理が正常に終了すると、ws2 中のいずれかのワイド文字コードが見つかれば その最初の出現位置を示すポインタを返し、 1 つも見つからなければ NULL ポインタを返します。
wcswcs() 関数は、ws1 が指すワイド文字列内に、ws2 が指すワイド文字列 ( 終端の NULL ワイド文字コードを除く ) が含まれていれば、その最初の出現位置を報告します。処理が正常に終了すると、ws2 中のワイド文字列が見つかれば その最初の出現位置を示すポインタを返し、見つからなければ NULL ポインタを返します。ws2 が長さ 0 のワイド文字列を指している場合、関数は ws1 を返します。
wcsspn() と wsspn() の両関数は、ws1 が指すワイド文字列を先頭から検査し、ws2 が示すワイド文字列中のワイド文字コード だけで構成される部分の最大長を計算します。両関数ともに最初の部分文字列 ws1 の長さを返します。エラー発生を示す戻り値は定義されていません。
wcscspn() と wscspn() の両関数は、ws1 が指すワイド文字列を先頭から検査し、ws2 が示すワイド文字列中のワイド文字コード 以外のコードだけで構成される最初の部分の最大長を計算します。両関数ともに ws1 の初期部分文字列の長さを返します。エラー発生を示す戻り値は定義されていません。
wcstok() と wstok() を連続して呼び出すと、ws1 が指すワイド文字列はいくつかのトークンに分割されます。トークンは、ws2 が指すワイド文字列から得られるワイド文字コードによって区切られます。
第 3 引数は、呼び出し元から提供される wchar_t ポインタを返します。wchar_t ポインタには、wcstok() 関数が同じワイド文字列を続けて走査するために、必要な情報が格納されています。この引数は wcstok() の XPG4 と SUS のバージョンでは利用できません。また、wstok() 関数でも利用できません ( standards(5) 参照)。
最初の呼び出しでは ws1 を第 1 引数に指定し、それ以後の呼び出しでは NULL ポインタを第 1 引数に指定します。トークンの区切り文字として指定する文字列、つまり ws2 が指すワイド文字列は、呼び出しごとに異なっていてもかまいません。
1 回目の呼び出しでは、ws1 が示すワイド文字列を先頭から検査して、ws2 が指す区切り文字列に含まれていないワイド文字コードを 探します。そのようなワイド文字コードが最初に見つかった位置が、第 1 トークンの始まりとなります。そのようなワイド文字コードが 1 つも見つからなければ、ws1 が指すワイド文字列にはトークンは存在しないことになり、wcstok() および wstok() は NULL ポインタを返します。
第 1 トークンの始まりが定義されたら、wcstok() と wstok() の両関数は、その地点からさらに検査して、区切り文字列中に 含まれているワイド文字コードを探します。ws1 の終わりまで検索してもそのようなワイド文字コードが 見つからなければ、文字列全体の終わりがトークンの終わりとなり、以降の呼び出しに対しては、 NULL ポインタが返されます。ワイド文字コードが見つかれば、その地点が第 1 トークンの終端となり、そのコードは NULL ワイド文字に置き換えられます。このとき wcstok() と wstok() の両関数は、その次のワイド文字コードへのポインタを保存します。次のトークン検索は、そのポインタの位置から開始されます。
このようにして、第 1 引数に NULL ポインタを指定して wcstok() または wstok() を連続して呼び出すと、保存されたポインタの位置から 上記のようなトークンの検索が実行されます。 処理が正常に終了すると、両関数は生成したトークンの 先頭のワイド文字コードを指すポインタを返します。正常に終了しなかった場合、 NULL ポインタが返されます。
次の属性については attributes(5) のマニュアルページを参照してください。
属性タイプ | 属性値 |
---|---|
MT レベル | MT-Safe |
CSI | 対応済み |
インタフェースの安定性 | 「注意事項」を参照。 |
wcscat()、wcsncat()、wcscmp()、wcsncmp()、wcscpy()、wcsncpy()、wcslen()、wcschr()、wcsrchr()、wcspbrk()、wcswcs()、wcsspn()、wcscspn()、および wcstok() 関数は「標準」です。wscat()、wsncat()、wscmp()、wscpy()、wsncpy()、wslen()、wschr()、wsrchr()、wspbrk()、wsspn()、wstok()、windex()、および wrindex() 関数は「安定」です。