OpenVMS マニュアル

wcsxfrm

ワイド文字列を変更して，変更後の文字列を wcscmp関数に渡したときに，変更なしの文字列を wcscoll関数に渡したときと同じ結果が得られるようにします。

形式

#include <wchar.h>

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

引数

ws1, ws2

ワイド文字列へのポインタ。

maxchar

s1 に格納できるワイド文字の数の最大値。終端の null ワイド文字を含みます。

説明

wcsxfrm関数は，ws2 がポイントする文字列を変換し，その結果の文字列を ws1 がポイントする配列に格納します。 ws1 がポイントする配列に格納されるワイド文字の数は，終端の null ワイド文字を含めて，maxchar 個以下です。

maxchar の値が，( 終端の null を含めて ) 変換後の文字列を格納するのに必要なサイズよりも小さかった場合， ws1 がポイントする配列の内容は不定となります。この場合，関数は変換後の文字列のサイズを返します。

maxchar が 0 の場合， ws1 は NULL ポインタであってよく，関数は変換を行う前に， ws1 配列の必要なサイズを返します。

ワイド文字列比較関数の wcscollと wcscmpは，同じ 2 つのワイド文字列を与えられたときに，異なる結果を生成することがあります。これは， wcscmpが文字列中の文字のコード・ポイント値の直接の比較を行うのに対し， wcscollが比較の実行にロケール情報を使用するためです。ロケールによっては， wcscollの比較はマルチパスの操作になることがあり， wcscmpよりも遅くなります。

wcsxfrm関数は， wcscmp関数に 2 つの変換後の文字列を渡したときに，元の 2 つの文字列を wcscoll関数に渡したときと同じ結果が得られるような形でワイド文字列を変換します。 wcsxfrm関数は， wcscollを使って同じワイド文字列に対する多数の比較を行う必要があるアプリケーションで便利です。この場合には，( ロケールによっては ) wcsxfrm関数を使って文字列を変換した後に， wcscmp関数を使って比較を行う方が効率的である場合があります。

戻り値

x	結果として得られる， ws1 がポイントする文字列の長さ。終端の null 文字は含みません。
( size_t ) -1	エラーが発生したことを示します。関数は errno を EINVAL に設定します。 ws2 がポイントする文字列は，照合シーケンスの領域の外にある文字を含みます。

例

#include <wchar.h> #include <stdio.h> #include <stdlib.h> #include <locale.h> /* This program verifies that two transformed strings, */ /* when passed through wcsxfrm and then compared, provide */ /* the same result as if passed through wcscoll without */ /* any transformation. */ #define BUFF_SIZE 20 main() { wchar_t w_string1[BUFF_SIZE]; wchar_t w_string2[BUFF_SIZE]; wchar_t w_string3[BUFF_SIZE]; wchar_t w_string4[BUFF_SIZE]; int errno; int coll_result; int wcscmp_result; size_t wcsxfrm_result1; size_t wcsxfrm_result2; /* setlocale to French locale */ if (setlocale(LC_ALL, "fr_FR.ISO8859-1") == NULL) { perror("setlocale"); exit(EXIT_FAILURE); } /* Convert each of the strings into wide-character format. */ if (mbstowcs(w_string1, "<a`>bcd", BUFF_SIZE) == (size_t)-1) { perror("mbstowcs"); exit(EXIT_FAILURE); } if (mbstowcs(w_string2, "abcz", BUFF_SIZE) == (size_t)-1) { perror("mbstowcs"); exit(EXIT_FAILURE); } /* Collate string 1 and string 2 and store the result. */ errno = 0; coll_result = wcscoll(w_string1, w_string2); if (errno) { perror("wcscoll"); exit(EXIT_FAILURE); } else { /* Transform the strings (using wcsxfrm) into */ /* w_string3 and w_string4. */ wcsxfrm_result1 = wcsxfrm(w_string3, w_string1, BUFF_SIZE); if (wcsxfrm_result1 == ((size_t) - 1)) perror("wcsxfrm"); else if (wcsxfrm_result1 > BUFF_SIZE) { perror("\n** String is too long **\n"); exit(EXIT_FAILURE); } else { wcsxfrm_result2 = wcsxfrm(w_string4, w_string2, BUFF_SIZE); if (wcsxfrm_result2 == ((size_t) - 1)) { perror("wcsxfrm"); exit(EXIT_FAILURE); } else if (wcsxfrm_result2 > BUFF_SIZE) { perror("\n** String is too long **\n"); exit(EXIT_FAILURE); } /* Compare the two transformed strings and verify that */ /* the result is the same as the result from wcscoll on */ /* the original strings. */ else { wcscmp_result = wcscmp(w_string3, w_string4); if (wcscmp_result == 0 && (coll_result == 0)) { printf("\nReturn value from wcscoll() and return value" " from wcscmp() are both zero."); printf("\nThe program was successful\n\n"); } else if ((wcscmp_result < 0) && (coll_result < 0)) { printf("\nReturn value from wcscoll() and return value" " from wcscmp() are less than zero."); printf("\nThe program was successful\n\n"); } else if ((wcscmp_result > 0) && (coll_result > 0)) { printf("\nReturn value from wcscoll() and return value" " from wcscmp() are greater than zero."); printf("\nThe program was successful\n\n"); } else { printf("** Error **\n"); printf("\nReturn values are not of the same type"); } } } } }

この例のプログラムを実行すると，次の結果が生成されます。

Return value from wcscoll() and return value 
       from wcscmp() are less than zero. 
The program was successful