wcsxfrm | Programming Place Plus　Ｃ言語編　標準ライブラリのリファレンス

概要

ロケール特有の基準に沿った文字列比較を効率化するため、ワイド文字列を変換する

ヘッダ

wchar.h

形式

size_t wcsxfrm(wchar_t* restrict s1, const wchar_t* restrict s2, size_t n);

引数

s1

変換結果を受け取る配列を指すポインタ。n が 0 の場合に限って、ヌルポインタでも良い。

s2

変換元のワイド文字列。

n

s1 が指す配列へ格納する最大文字数。末尾のヌル文字を含める。

戻り値

変換した結果の文字数。末尾のヌル文字を含まない。

詳細

ワイド文字列の内容を、ロケール特有の基準による比較を効率よく行えるような形に変換する。つまり、wcscoll関数を使って比較を行うよりも、wcscmp関数を使って比較を行う方が効率が良くなる（であろう）形に変換する。比較したいワイド文字列が２つあるとして、その２つを wcscoll関数で比較したときの結果と、wcsxfrm関数で変換した後の２つを wcscmp関数で比較したときの結果とが一致するように変換される。
引数 n の値を超える文字数の文字を、引数 s1 へ書き込むことはない。引数 n の値は、終端のヌル文字を含む。
戻り値が、引数 n の値以上である場合、引数 s1 が指す配列の内容は不定である。
戻り値は、s1 が指す配列へ格納された文字数ではなく、変換結果の文字数である。そのため、引数 n に 0 を指定して「size = wcsxfrm(NULL, s, 0) + 1;」のようにすれば、変換結果を格納するために必要な配列の大きさを調べることができる（最後の +1 は、末尾のヌル文字の分である）。

注意

s1 と s2 が指すワイド文字列のうち、処理に関係がある部分が重なり合っていた場合は未定義の動作になる。

使用例

#include <stdio.h>
#include <stdlib.h>
#include <wchar.h>
#include <locale.h>

int main(void)
{
    const wchar_t src[] = L"xyz";

    // LC_COLLATE をネイティブロケールに変更
    if (setlocale(LC_COLLATE, "") == NULL) {
        fputs("ロケールの設定に失敗しました。\n", stderr);
        return EXIT_FAILURE;
    }

    wchar_t dest[16];

    // 以下は同じ結果を出力する
#if 1
    wcsxfrm(dest, src, sizeof(src) / sizeof(wchar_t));
    printf("%d\n", wcscmp(src, L"xy"));
    printf("%d\n", wcscmp(src, L"xyz"));
    printf("%d\n", wcscmp(src, L"xyzz"));
#else
    printf("%d\n", wcscoll(src, L"xy"));
    printf("%d\n", wcscoll(src, L"xyz"));
    printf("%d\n", wcscoll(src, L"xyzz"));
#endif
}

実行結果：

1
0
-1

関連

ワイド文字列版の wcsxfrm関数がある。
ロケールの影響を受けない文字列比較は strcmp関数で、ロケールを考慮した文字列比較は strcoll関数で行える。

解説章