Função CompareStringEx (stringapiset.h)

Artigo
08/26/2023

Compara duas cadeias de caracteres Unicode (caractere largo), para uma localidade especificada por nome.

Cuidado Usar CompareStringEx incorretamente pode comprometer a segurança do aplicativo. Cadeias de caracteres que não são comparadas corretamente podem produzir entrada inválida. Testar cadeias de caracteres para garantir que elas sejam válidas antes de usá-las e fornecer manipuladores de erros. Para obter mais informações, consulte Considerações de segurança: recursos internacionais.

Nota O aplicativo deve chamar essa função em preferência para CompareString se projetado para ser executado somente no Windows Vista e posterior.

Sintaxe

int CompareStringEx(
  [in, optional] LPCWSTR                          lpLocaleName,
  [in]           DWORD                            dwCmpFlags,
  [in]           _In_NLS_string_(cchCount1)LPCWCH lpString1,
  [in]           int                              cchCount1,
  [in]           _In_NLS_string_(cchCount2)LPCWCH lpString2,
  [in]           int                              cchCount2,
  [in, optional] LPNLSVERSIONINFO                 lpVersionInformation,
  [in, optional] LPVOID                           lpReserved,
  [in, optional] LPARAM                           lParam
);

Parâmetros

[in, optional] lpLocaleName

Ponteiro para um nome de localidade ou um dos valores predefinidos a seguir.

[in] dwCmpFlags

Sinalizadores que indicam como a função compara as duas cadeias de caracteres. Por padrão, esses sinalizadores não são definidos. Esse parâmetro pode especificar uma combinação de qualquer um dos valores a seguir ou pode ser definido como 0 para obter o comportamento padrão.

Sinalizador	Significado
LINGUISTIC_IGNORECASE	Ignorar maiúsculas e minúsculas, conforme linguisticamente apropriado.
LINGUISTIC_IGNOREDIACRITIC	Ignore caracteres sem espaçamento, conforme linguisticamente apropriado. Nota Esse sinalizador nem sempre produz resultados previsíveis quando usado com caracteres decompostos, ou seja, caracteres em que um caractere base e um ou mais caracteres não espaçados têm valores de ponto de código distintos.
NORM_IGNORECASE	Ignorar maiúsculas e minúsculas. Para muitos scripts (especialmente scripts latinos), NORM_IGNORECASE coincide com LINGUISTIC_IGNORECASE. Nota NORM_IGNORECASE ignora qualquer distinção terciária, seja realmente caso linguístico ou não. Por exemplo, em scripts árabes e índices, isso distingue formas alternativas de um caractere, mas as diferenças não correspondem a maiúsculas e minúsculas linguísticas. LINGUISTIC_IGNORECASE faz com que a função ignore apenas maiúsculas e minúsculas linguísticas reais, em vez de ignorar o terceiro peso de classificação. Nota Com esse sinalizador definido, a função ignora a distinção entre as formas largas e estreitas dos caracteres de compatibilidade do CJK.
NORM_IGNOREKANATYPE	Não diferencie entre caracteres hiragana e katakana. Os caracteres hiragana e katakana correspondentes são comparados como iguais.
NORM_IGNORENONSPACE	Ignorar caracteres sem espaçamento. Para muitos scripts (especialmente scripts latinos), NORM_IGNORENONSPACE coincide com LINGUISTIC_IGNOREDIACRITIC. Nota NORM_IGNORENONSPACE ignora qualquer distinção secundária, seja ela diacrítica ou não. Scripts para idiomas coreano, japonês, chinês e índice, entre outros, usam essa distinção para fins diferentes de diacríticos. LINGUISTIC_IGNOREDIACRITIC faz com que a função ignore apenas os diacríticos reais, em vez de ignorar o segundo peso de classificação. Nota NORM_IGNORENONSPACE só tem um efeito para localidades nas quais caracteres acentuados são classificados em uma segunda passagem de main caracteres. Normalmente, todos os caracteres na cadeia de caracteres são comparados primeiro sem considerar os acentos e, se as cadeias de caracteres forem iguais, uma segunda passagem sobre as cadeias de caracteres é executada para comparar acentos. Esse sinalizador faz com que a segunda passagem não seja executada. Para localidades que classificam caracteres acentuados na primeira passagem, esse sinalizador não tem efeito.
NORM_IGNORESYMBOLS	Ignorar símbolos e pontuação.
NORM_IGNOREWIDTH	Ignore a diferença entre caracteres de meia largura e largura total, por exemplo, C a t == cat. A forma de largura total é uma distinção de formatação usada em scripts em chinês e japonês.
NORM_LINGUISTIC_CASING	Use as regras linguísticas padrão para uso de maiúsculas e minúsculas, em vez de regras do sistema de arquivos. Observe que a maioria dos cenários para CompareStringEx usa esse sinalizador. Esse sinalizador não precisa ser usado quando seu aplicativo chama CompareStringOrdinal.
SORT_DIGITSASNUMBERS	Windows 7: Trate dígitos como números durante a classificação, por exemplo, classifique "2" antes de "10".
SORT_STRINGSORT	Trate a pontuação da mesma forma que os símbolos.

[in] lpString1

Ponteiro para a primeira cadeia de caracteres a ser comparada.

[in] cchCount1

Comprimento da cadeia de caracteres indicada por lpString1, excluindo o caractere nulo de terminação. O aplicativo poderá fornecer um valor negativo se a cadeia de caracteres for terminada em nulo. Nesse caso, a função determina o comprimento automaticamente.

[in] lpString2

Ponteiro para a segunda cadeia de caracteres a ser comparada.

[in] cchCount2

Comprimento da cadeia de caracteres indicada por lpString2, excluindo o caractere nulo de terminação. O aplicativo poderá fornecer um valor negativo se a cadeia de caracteres for terminada em nulo. Nesse caso, a função determina o comprimento automaticamente.

[in, optional] lpVersionInformation

Ponteiro para uma estrutura NLSVERSIONINFOEX que contém as informações de versão sobre a funcionalidade de NLS relevante; geralmente recuperado de GetNLSVersionEx.

Windows Vista, Windows 7: Reservados; deve definir como NULL.

[in, optional] lpReserved

Reservados; deve definir como NULL.

[in, optional] lParam

Reservados; deve ser definido como 0.

Retornar valor

Retornará um dos valores a seguir se tiver êxito. Para manter a convenção de runtime C da comparação de cadeias de caracteres, o valor 2 pode ser subtraído de um valor retornado diferente de zero. Em seguida, o significado de <0, ==0 e >0 é consistente com o runtime C.

CSTR_LESS_THAN. A cadeia de caracteres indicada por lpString1 é menor em valor lexical do que a cadeia de caracteres indicada por lpString2.
CSTR_EQUAL. A cadeia de caracteres indicada por lpString1 é equivalente em valor lexical à cadeia de caracteres indicada por lpString2. As duas cadeias de caracteres são equivalentes para fins de classificação, embora não necessariamente idênticas.
CSTR_GREATER_THAN. A cadeia de caracteres indicada por lpString1 é maior em valor lexical do que a cadeia de caracteres indicada por lpString2.

A função retornará 0 se não for bem-sucedida. Para obter informações de erro estendidas, o aplicativo pode chamar GetLastError, que pode retornar um dos seguintes códigos de erro:

ERROR_INVALID_FLAGS. Os valores fornecidos para sinalizadores eram inválidos.
ERROR_INVALID_PARAMETER. Qualquer um dos valores de parâmetro era inválido.

Comentários

CompareString e CompareStringEx são otimizados para serem executados na velocidade mais alta quando dwCmpFlags é definido como 0 ou NORM_IGNORECASE, cchCount1 e cchCount2 são definidos como -1, e a localidade não dá suporte a nenhuma compactação linguística, como quando a classificação tradicional em espanhol trata "ch" como um único caractere.

CompareString e CompareStringEx ignoram kashidas árabes durante a comparação. Portanto, se duas cadeias de caracteres forem idênticas, exceto pela presença de kashidas, a função retornará CSTR_EQUAL.

Quando o aplicativo usa os sinalizadores NORM_IGNORENONSPACE e NORM_IGNORECASE com a função de classificação, às vezes, os sinalizadores podem interferir nas comparações de cadeia de caracteres. Essa situação pode resultar em uma localidade que não dá suporte a caracteres não espaçados ou maiúsculas e minúsculas, mas usa níveis de peso equivalentes para lidar com outras operações importantes. Nesses casos, seu aplicativo deve usar os sinalizadores LINGUISTIC_IGNOREDIACRITIC e LINGUISTIC_IGNORECASE. Esses sinalizadores fornecem resultados linguisticamente apropriados para classificar pontos de código que usam marcas diacríticas e maiúsculas e minúsculas e não têm impacto sobre outros pontos de código.

A partir do Windows Vista: CompareString e CompareStringEx podem recuperar dados de localidades personalizadas. Não há garantia de que os dados sejam iguais de computador para computador ou entre execuções de um aplicativo. Se o aplicativo precisar persistir ou transmitir dados, consulte Usando dados de localidade persistente.

Começando no Windows 8: se o aplicativo passar marcas de idioma para essa função do namespace Windows.Globalization, ele deverá primeiro converter as marcas chamando ResolveLocaleName.

Começando em Windows 8: CompareStringEx é declarado em Stringapiset.h. Antes de Windows 8, ele foi declarado em Winnls.h.

Nota O comportamento da classificação pode mudar entre as versões do Windows. Por exemplo, pode haver novos pontos de código Unicode criados. Use GetNlsVersionEx para descobrir se a versão de classificação foi alterada.

Exemplos

Um exemplo mostrando o uso dessa função pode ser encontrado em NLS: Exemplo de APIs baseadas em nome.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows Vista [aplicativos da área de trabalho \| Aplicativos UWP]
Servidor mínimo com suporte	Windows Server 2008 [aplicativos da área de trabalho \| Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	stringapiset.h (inclua Windows.h)
Biblioteca	Kernel32.lib
DLL	Kernel32.dll