strxfrm、 wcsxfrm、 _strxfrm_l、 _wcsxfrm_l

ロケール固有の情報に基づいて文字列を変換します。

構文

size_t strxfrm(
   char *strDest,
   const char *strSource,
   size_t count
);
size_t wcsxfrm(
   wchar_t *strDest,
   const wchar_t *strSource,
   size_t count
);
size_t _strxfrm_l(
   char *strDest,
   const char *strSource,
   size_t count,
   _locale_t locale
);
size_t wcsxfrm_l(
   wchar_t *strDest,
   const wchar_t *strSource,
   size_t count,
   _locale_t locale
);

パラメーター

strDest
対象文字列。

strSource
ソース文字列。

count
strDestに配置する最大文字数。

locale
使用するロケール。

戻り値

変換された文字列の長さを返します。終端の null 文字は含まれません。 戻り値が count 以上である場合、strDest のコンテンツは予測できません。 エラーの場合、各関数は errno を設定し、INT_MAX を返します。 無効な文字の場合、errno は EILSEQ に設定されます。

解説

strxfrm 関数は、strSource によって指されている文字列を、strDest に格納されている新しい照合フォームに変換します。 null 文字を含めて count 以内の文字が変換され、結果の文字列に配置されます。 変換は、ロケールの LC_COLLATE カテゴリ設定を使用して行われます。 LC_COLLATE の詳細については、「setlocale」を参照してください。 strxfrm は、ロケールに依存する動作に現在のロケールを使用します。_strxfrm_l は、現在のロケールの代わりに渡されたロケールを使用することを除いて同じです。 詳細については、「 Locale」を参照してください。

変換後、2 つの変換された文字列を使用して strcmp を呼び出すと、元の 2 つの文字列に適用された strcoll の呼び出しの結果と同じ結果が生成されます。 strcoll と stricoll と同様に、strxfrm はマルチバイト文字の文字列を必要に応じて自動的に処理します。

wcsxfrm は strxfrm のワイド文字バージョンで、wcsxfrm の文字列引数はワイド文字ポインターです。 wcsxfrmの場合、文字列変換の後に、変換された 2 つの文字列でwcscmpを呼び出すと、元の 2 つの文字列に適用wcscoll呼び出しの結果と同じ結果が生成されます。 それ以外では、wcsxfrm と strxfrm の動作は同じです。 wcsxfrm は、ロケールに依存する動作に現在のロケールを使用します。_wcsxfrm_l は、現在のロケールの代わりに渡されたロケールを使用します。

これらの関数では、パラメーターの検証が行われます。 strSourceが null ポインターであるか、strDestがNULL ポインターである場合 (カウントが 0 でない場合)、またはcountがINT_MAXより大きい場合は、「パラメーターの検証」で説明されているように、無効なパラメーター ハンドラーが呼び出されます。 実行の継続が許可された場合、これらの関数は errno を EINVAL に設定し、INT_MAX を返します。

既定では、この関数のグローバル状態の適用対象は、アプリケーションになります。 この動作を変更するには、「CRT でのグローバル状態」を参照してください。

汎用テキスト ルーチンのマップ

"C" ロケールでは、文字セット (ASCII 文字セット) 内の文字の順序は、辞書式文字順序と同じです。 ただし、その他のロケールでは、文字セット内の文字の順序が辞書式文字順序と異なる場合があります。 たとえば、ヨーロッパのロケールによっては、文字 'a' (値 0x61) が文字 'ä' の前にあります。文字セット内の (値0xE4) が、文字 'ä' の前に文字 'a' が構文的に付けられます。

文字セットと辞書式文字順序が異なるロケールで、元の文字列で strxfrm を使用し、結果の文字列で strcmp を使用して、現在のロケールの LC_COLLATE カテゴリの設定に従って辞書式文字列比較を生成します。 このように、上記のロケールで 2 つの文字列を辞書式に比較するには、元の文字列で strxfrm を使用し、結果の文字列で strcmp を使用します。 または、元の文字列で strcmp ではなく strcoll を使用することもできます。

strxfrmは基本的に、LCMAP_SORTKEYを含むLCMapStringのラッパーです。

次の式の値は、ソース文字列の strxfrm 変換を保持するために必要な配列のサイズです。

1 + strxfrm( NULL, string, 0 )

"C" ロケールでのみ、 strxfrm は次の関数呼び出しと同じです。

strncpy( _string1, _string2, _count );
return( strlen( _string1 ) );

要件

互換性の詳細については、「 Compatibility」を参照してください。

関連項目

データ変換
localeconv
setlocale, _wsetlocale
ロケール
文字列操作
strcoll 関数
strcmp、 wcscmp、 _mbscmp
strncmp、 wcsncmp、 _mbsncmp、 _mbsncmp_l