strxfrm, wcsxfrm, _strxfrm_l, _wcsxfrm_l

Transforme uma cadeia de caracteres com base nas informações específicas à localidade.

Sintaxe

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
);

Parâmetros

strDest
Cadeia de caracteres de destino.

strSource
Cadeia de caracteres de origem.

count
Número máximo de caracteres a serem colocados em strDest.

locale
A localidade a ser usada.

Valor retornado

Retorna o tamanho da cadeia de caracteres transformada, sem contar o caractere nulo de terminação. Se o valor retornado for maior ou igual a count, o conteúdo de strDest será imprevisível. Em um erro, cada função define errno e retorna INT_MAX. Para um caractere inválido, errno é definido como EILSEQ.

Comentários

A função strxfrm transforma a cadeia de caracteres apontada por strSource em um novo formato agrupado que é armazenado em strDest. Um número que não excede count caracteres, incluindo o caractere nulo, é transformado e colocado na cadeia de caracteres resultante. A transformação é feita usando a configuração de categoria LC_COLLATE da localidade. Para obter mais informações sobre LC_COLLATEo , consulte setlocale. strxfrm usa a localidade atual de seu comportamento dependente da localidade; _strxfrm_l é idêntico, exceto pelo fato de que ele usa a localidade passada, em vez da localidade atual. Para obter mais informações, consulte Localidade.

Após a transformação, uma chamada para strcmp com as duas cadeias de caracteres transformadas produz resultados idênticos aos resultados de uma chamada para strcoll aplicada às duas cadeias de caracteres originais. Assim como ocorre com strcoll e stricoll, strxfrm manipula automaticamente as cadeias de caracteres multibyte, conforme apropriado.

wcsxfrm é uma versão de caractere largo de strxfrm; os argumentos de cadeia de caracteres de wcsxfrm são ponteiros de caracteres largos. Para wcsxfrm, após a transformação da cadeia de caracteres, uma chamada para wcscmp com as duas cadeias de caracteres transformadas produz resultados idênticos aos resultados de uma chamada para wcscoll aplicada às duas cadeias de caracteres originais. Caso contrário, wcsxfrm e strxfrm se comportam de forma idêntica. wcsxfrm usa a localidade atual de seu comportamento dependente da localidade; _wcsxfrm_l usa a localidade passada, em vez da localidade atual.

Essas funções validam seus parâmetros. Se strSource for um ponteiro nulo ou strDest for um NULL ponteiro (a menos que count seja zero) ou se count for maior que INT_MAX, o manipulador de parâmetro inválido será invocado, conforme descrito em Validação de parâmetro. Se a execução tiver permissão para continuar, essas funções definirão errno como EINVAL e retornarão INT_MAX.

Por padrão, o estado global dessa função tem como escopo o aplicativo. Para alterar esse comportamento, confira Estado global no CRT.

Mapeamentos de rotina de texto genérico

Na localidade “C”, a ordem dos caracteres no conjunto de caracteres (conjunto de caracteres ASCII) é a mesma que a ordem lexicográfica dos caracteres. No entanto, em outras localidades, a ordem de caracteres no conjunto de caracteres pode ser diferente da ordem lexicográfica de caracteres. Por exemplo, em certas localidades europeias, o caractere 'a' (valor 0x61) precede o caractere 'ä' (valor 0xE4) no conjunto de caracteres, mas o caractere 'ä' precede o caractere 'a' lexicograficamente.

Em localidades nas quais o conjunto de caracteres e a ordem lexicográfica dos caracteres diferem, use strxfrm nas cadeias de caracteres originais e, em seguida, strcmp nas cadeias de caracteres resultantes para produzir uma comparação lexicográfica de cadeia de caracteres de acordo com a configuração de categoria LC_COLLATE da localidade atual. Portanto, para comparar duas cadeias de caracteres lexicograficamente na localidade acima, use strxfrm nas cadeias de caracteres originais e, em seguida, strcmp nas cadeias de caracteres resultantes. Como alternativa, é possível usar strcoll em vez de strcmp nas cadeias de caracteres originais.

strxfrm é basicamente um invólucro com LCMapString LCMAP_SORTKEY.

O valor da seguinte expressão é o tamanho da matriz necessário para conter a transformação strxfrm da cadeia de caracteres de origem:

1 + strxfrm( NULL, string, 0 )

Somente na localidade "C", strxfrm é equivalente às seguintes chamadas de função:

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

Requisitos

Para obter informações sobre compatibilidade, consulte Compatibilidade.

Confira também

Conversão de dados
localeconv
setlocale, _wsetlocale
Localidade
Manipulação de cadeia de caracteres
Funções strcoll
strcmp, wcscmp, _mbscmp
strncmp, wcsncmp, _mbsncmp, _mbsncmp_l