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.

contagem
Número máximo de caracteres a ser colocado 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 de retorno for maior ou igual à contagem, o conteúdo de strDest será imprevisível. Em caso de 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 formulário collado armazenado em strDest. Não mais do que contar caracteres, incluindo o caractere nulo, são transformados e colocados na cadeia de caracteres resultante. A transformação é feita usando a configuração de categoria LC_COLLATE localidade. Para obter mais informações sobre LC_COLLATE, consulte setlocale. strxfrm usa a localidade atual para seu comportamento dependente de localidade; _strxfrm_l é idêntico, exceto que 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 de uma chamada para strcoll aplicado às duas cadeias de caracteres originais. Assim como acontece com strcoll e stricoll, o strxfrm lida automaticamente com 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 caractere largo. Para wcsxfrm, após a transformação de cadeia de caracteres, uma chamada para wcscmp com as duas cadeias de caracteres transformadas gera resultados idênticos aos de uma chamada para wcscoll aplicado às duas cadeias de caracteres originais. wcsxfrm estrxfrm se comportam de forma idêntica caso contrário. wcsxfrm usa a localidade atual para seu comportamento dependente de 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 ponteiro NULL (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 comoEINVAL e retornarão INT_MAX.

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

Mapeamentos da rotina de texto genérico

Rotina TCHAR.H & _UNICODE _MBCS não definido _MBCS definido _UNICODE definido
_tcsxfrm strxfrm strxfrm wcsxfrm
_tcsxfrm_l _strxfrm_l _strxfrm_l _wcsxfrm_l

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 determinadas localidades europeias, o caractere 'a' (valor 0x61) precede o caractere 'ä' (value 0xE4) no conjunto de caracteres, mas o caractere 'ões' precede o caractere 'a' lexicograficamente.

Em localidades para as quais o conjunto de caracteres e a ordem de caractere lexicográfica diferem, use strxfrm nas cadeias de caracteres originais e, em seguida, strcmp nas cadeias de caracteres resultantes para produzir uma comparação de cadeia de caracteres lexicográfica de acordo com a configuração de categoria de 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, você pode usar strcoll em vez de strcmp nas cadeias de caracteres originais.

strxfrm é basicamente um wrapper em torno de LCMapString com LCMAP_SORTKEY.

O valor da expressão a seguir é o tamanho da matriz necessária para manter a transformação strxfrm da cadeia de caracteres de origem:

1 + strxfrm( NULL, string, 0 )

Somente na localidade "C", strxfrm é equivalente ao seguinte:

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

Requisitos

Rotina Cabeçalho necessário
strxfrm <string.h>
wcsxfrm <string.h> ou <wchar.h>
_strxfrm_l <string.h>
_wcsxfrm_l <string.h> ou <wchar.h>

Para obter mais 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