#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);
これらの関数は、 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 | 対応済み |