wcstring(3C)

構文

#include <wchar.h>

wchar_t *wcscat(wchar_t *ws1, const wchar_t *ws2);

wchar_t *wcsncat(wchar_t *ws1, const wchar_t *ws2, size_t n);

int wcscmp(const wchar_t *ws1, const wchar_t *ws2);

int wcsncmp(const wchar_t *ws1, const wchar_t *ws2, size_t n);

wchar_t *wcscpy(wchar_t *ws1, const wchar_t *ws2);

wchar_t *wcsncpy(wchar_t *ws1, const wchar_t *ws2, size_t n);

size_t wcslen(const wchar_t *ws);

wchar_t *wcschr(const wchar_t *ws, wchar_t wc);

wchar_t *wcsrchr(const wchar_t *ws, wchar_t wc);

wchar_t *wcspbrk(const wchar_t *ws1, const wchar_t *ws2);

size_t wcsspn(const wchar_t *ws1, const wchar_t *ws2);

size_t wcscspn(const wchar_t *ws1, const wchar_t *ws2);

wchar_t *wcswcs(const wchar_t *ws1, const wchar_t *ws2);

wchar_t *wcstok(wchar_t *ws1, const wchar_t *ws2);

int wcscoll(const wchar_t *ws1, const wchar_t *ws2);

int wcwidth(wint_t wc);

int wcswidth(const wchar_t *ws, size_t n);

size_t wcsxfrm(wchar_t *ws1, const wchar_t *ws2, size_t n);

説明

引き数 ws1, ws2, および ws は、ワイドキャラクタ文字列 (null 値で終わる、 wchar_t 型の配列) を指します。

wcscat() は、ワイドキャラクタ文字列 ws2 のコピーをワイドキャラクタ文字列 ws1 の後ろに追加します。 wcsncat() は、最大で n 文字追加します。 ws2 が、 n 文字より短い場合は、追加する文字数は n より少なくなります。 どちらも、結果として得られる null で終了する文字列へのポインター ws1 の値) を戻り値とします。

wcscmp() は、引き数を辞書順で比較し、 ws1 が ws2 に対して小さいか、等しいか、大きいかに応じて、それぞれ ０ に対して小さい、等しい、または大きい整数を戻り値とします。 ワイドキャラクタの比較は、そのワイドキャラクタ コードの数値の比較で行っています。 ws1 や ws2 が null ポインターの場合、空の文字列へのポインターであるかのように扱います。 wcsncmp() は、最大でも n 文字しか比較しないことを除いては同じです n が ０ に等しいかそれよりも小さい場合、等しいと判断します)。

wcscpy() は、ワイドキャラクタ文字列 ws2 を、 ws1 にコピーします。null 値をコピーすると終了します。 wcsncpy() は、 ws2 から最大で n 文字 コピーします。コピーする文字数がちょうど n となるように、必要だけ ws1 の後ろに null 値を追加します。 ws2 の長さが n に等しいかそれ以上の場合、 結果は null で終了する文字列ではありません。 どちらの関数も、 ws1 を戻り値とします。 任意の構造体をコピーするために wcsncpy() を使うべきではありません。 その構造体が、 sizeof(wchar_t) バイトの連続する null を含んでいた場合、構造体全体をコピーしないことがあります。 任意のバイナリデータをコピーする場合は、 memcpy() 関数 memory(3C) を参照) を使ってください。

wcslen() は、 ws の中のワイドキャラクタの数を戻り値とします。終端 null ワイドキャラクタは含みません。

wcschr() (wcsrchr()) は、ワイドキャラクタ文字列 ws 中の最初 (最後) のワイドキャラクタ wc へのポインターを戻り値とします。 wc が、文字列中にない場合は、null ポインターを戻り値とします。 ワイドキャラクタ文字列の終端 null ワイドキャラクタは、文字列の一部であるとします。

wcsstr() は、 ws1 によって指示されたワイドキャラクタ文字列の中で、 ws2 によって指示されたワイドキャラクタ文字列内のワイドキャラクタ シーケンス (終端 null ワイドキャラクタを除く) の最初の出現箇所を探します。正常終了すると、 wcsstr() は検出されたワイドキャラクタ文字列へのポインターを返し、ワイドキャラクタ文字列が見つからなかった場合には null ポインターを返します。 ws2 がゼロ長のワイドキャラクタ文字列を指示する場合、この関数は ws1 を返します。

wcspbrk() は、ワイドキャラクタ文字列 ws2 中のワイドキャラクタのどれかが、はじめてワイドキャラクタ文字列 ws1 中に現れる場所へのポインターを返します。 ワイドキャラクタ文字列 ws2 中のワイドキャラクタが ws1 中にない場合は、null ポインターを戻り値とします。

wcsspn() (wcscspn()) は、 ws1 の先頭にある、 ws2 中の (以外の) ワイドキャラクタだけからなる最長セグメントの文字数を戻り値とします。

wcswcs() は、ワイドキャラクタ文字列 ws2 がワイドキャラクタ文字列 ws1 中に最初に現れる場所へのポインターを戻り値とします。 ws2 が ws1 中に現れない場合は null ポインターを戻り値とします。 ws2 が、大きさゼロのワイドキャラクタ文字列を指す場合、 wcswcs() は、 ws1 を戻り値とします。

wcstok() は、ワイドキャラクタ文字列 ws1 が、ワイドキャラクタ文字列 ws2 の中の文字 １ つ、またはそれ以上によって区切られる ０ 個以上のトークンの列びとして処理します。 １ 回目に null でないポインター ws1 を指定して呼び出すと、最初のトークンの最初のワイドキャラクタへのポインターを返し、 ws1 中のこのトークンの直後に null ワイドキャラクタを書き込みます。 この関数はこの位置を記憶しているので、次に第 １ 引き数を null ポインター にして呼び出すとこの続きを調べます。 このようにしてトークンがなくなるまでワイドキャラクタ文字列 ws1 全体を走査できます。 区切りのワイドキャラクタの文字列 ws2 は、呼び出しのたびに異なっても構いません。 ws1 中にトークンがなくなると、null ポインターを返します。

３ 番目の引き数は、 _INCLUDE__STDC_A1_SOURCE 環境用に追加されています。 ３ 番目の引き数 ptr は、 wcstok() が同じワイドキャラクタ文字列の走査を続行するのに必要な情報を保存している、呼び出し側により提供された wchar_t ポインターを指示します。

wcscoll() は、引き数を比較し、 ws1 の指すワイドキャラクタ文字列が ws2 の指すワイドキャラクタ文字列に対して小さいか、等しいか、大きいかに応じて、それぞれ ０ に対して小さい、等しい、または大きい整数を戻り値とします。 比較は、プログラムのロケール (後述の「ロケール」を参照) に従って適切な方法で行われます。 ``C'' ロケールでは、 wcscoll() の動作は wcscmp() と同じです。

wcwidth() は、ワイドキャラクタ wc の幅を桁数で返します。 wc が、null ワイドキャラクタの場合、戻り値は ０ です。 wc がプリント不可能なワイドキャラクタの場合、戻り値は -1 です。

wcswidth() は、 ws が指すワイドキャラクタ文字列の先頭の n 文字 n 文字より前に null ワイドキャラクタがある場合は、 n 文字よりも少ない) の幅を桁数で返します。 ws が null ワイドキャラクタを指す場合、 wcswidth() の戻り値は ０ です。 ws にプリント不可能なワイドキャラクタが含まれる場合または ws が NULL ポインターの場合、 wcswidth() の戻り値は -1 です (どちらの場合も errno に EINVAL が設定されます)。

wcsxfrm() は、 ws2 が指すワイドキャラクタ文字列を変換して、 ws1 が指す配列に結果を格納します。 変換は、 wcscmp() を変換された ２ つのワイドキャタクタ文字列に用いる場合、 変換前の ２ つのワイドキャタクタ文字列に wcscoll() を適用し、その結果に応じて、正、0、負の値を返すようになっています。 末尾の NULL ワイドキャラクタを含め n 個までのワイドキャラクタ コードが、 ws1 で指定された結果用配列に格納されます。 n が ０ の場合、 ws1 には NULL ポインターが指定できます。領域が重なるオブジェクト間でコピーが行われた場合、動作は不定になります。 wcsxfrm() は、変換したワイドキャラクタの長さを (末尾の NULL ワイドキャラクタは含まないで) 返します。返された値が n またはそれよりも大きい場合、 ws1 が指す配列の値は不定です。エラーが発生した場合、 wcsxfrm() は (size_t) -1 を返し、 errno に EINVAL ws2 が指すワイドキャラクタ文字列に、照合順序の範囲外にあるワイドキャラクタ コードが含まれている場合)、または NOSYS (関数がサポートされていない場合) を設定します。

これらの関数と wchar_t 型はヘッダーファイル <wchar.h> に定義してあります。

多言語化対応

エラー

wcswidth() は以下の場合に失敗します。

wcsxfrm() は以下の場合失敗します。

例

以下のサンプルコードは、空白で区切られている、 文字列 s 中のトークンを見つけるものです (トークンの最大数は MAXTOK とします)。

アプリケーション使用法

_INCLUDE__STDC_A1_SOURCE プロトタイプを使用するには、 _INCLUDE__STDC_A1_SOURCE フラグをコンパイラオプションとして引き渡します。

警告

関数 wcscat(), wcsncat(), wcscpy(), wcsncpy(), wcstok(), wcsstr() および wcstok_r() は、 ws1 が指す配列の内容を変更します。 これらの関数は、配列のオーバーフローを確認しません。

宛先のワイドキャラクタ文字列が null ポインターの場合の動作は定義されていません。

ワイドキャラクタの移動方法はインプリメンテーションに依存しています。 コピーを行う場合に、コピー元のワイドキャラクタ文字列と宛先が重なっていると予想外の結果を生じることがあります。

カテゴリ LC_COLLATE と LC_CTYPE が指定する言語が、互いに異なった文字セットを使用する場合、 wcscoll() 関数の動作は定義されません。

wcstok_r() インタフェースは廃止され、現在では既存の DCE アプリケーションとの互換性を保つためにだけサポートされています。新しいマルチスレッドアプリケーションでは、 wcstok() を使用してください。

ws が指すワイドキャラクタで指定された n 文字のワイドキャラクタ用に必要なカラム数が INT_MAX を超えた場合、 wcswidth() は不正確な負の値を返します。

著者

wcstring 関数は OSF および HP で開発されました。

参照

wconv(3C), memory(3C), multibyte(3C), setlocale(3C), string(3C), thread_safety(5)

標準準拠

wcscat(): XPG4

wcschr(): XPG4

wcscmp(): XPG4

wcscoll(): XPG4

wcscpy(): XPG4

wcscspn(): XPG4

wcslen(): XPG4

wcsncat(): XPG4

wcsncmp(): XPG4

wcsncpy(): XPG4

wcspbrk(): XPG4

wcsrchr(): XPG4

wcsspn(): XPG4

wcstok(): XPG4

wcswcs(): XPG4

wcswidth(): XPG4

wcwidth(): XPG4

wcsxfrm(): XPG4