Função CompareStringA (winnls.h)

Artigo
08/27/2023

Compara duas cadeias de caracteres, para uma localidade especificada pelo identificador.

Cuidado Usar CompareString incorretamente pode comprometer a segurança do aplicativo. Cadeias de caracteres que não são comparadas corretamente podem produzir entrada inválida. Por exemplo, a função pode gerar problemas de segurança quando usada para uma comparação não linguística, pois duas cadeias de caracteres distintas em sua representação binária podem ser linguisticamente equivalentes. O aplicativo deve testar cadeias de caracteres para validação antes de usá-las e deve fornecer manipuladores de erro. Para obter mais informações, consulte Considerações de segurança: recursos internacionais.

Nota Para compatibilidade com Unicode, seus aplicativos devem preferir CompareStringEx ou a versão Unicode do CompareString. Outro motivo para preferir CompareStringEx é que a Microsoft está migrando para o uso de nomes de localidade em vez de identificadores de localidade para novas localidades, por motivos de interoperabilidade. Qualquer aplicativo que será executado somente no Windows Vista e posterior deve usar CompareStringEx.

Sintaxe

int CompareStringA(
  [in] LCID   Locale,
  [in] DWORD  dwCmpFlags,
  [in] PCNZCH lpString1,
  [in] int    cchCount1,
  [in] PCNZCH lpString2,
  [in] int    cchCount2
);

Parâmetros

[in] Locale

Identificador de localidade da localidade usada para a comparação. Você pode usar a macro MAKELCID para criar um identificador de localidade ou usar um dos seguintes valores predefinidos.

[in] dwCmpFlags

Sinalizadores que indicam como a função compara as duas cadeias de caracteres. Para obter definições detalhadas, consulte o parâmetro dwCmpFlags de CompareStringEx.

[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. Esse valor representa bytes para a versão ANSI da função e caracteres largos para a versão Unicode. 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. Esse valor representa bytes para a versão ANSI da função e caracteres largos para a versão Unicode. 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.

Valor retornado

Retorna os valores descritos para CompareStringEx.

Comentários

Consulte Comentários para CompareStringEx.

Se o aplicativo estiver chamando a versão ANSI do CompareString, a função converterá parâmetros por meio da página de código padrão da localidade fornecida. Portanto, um aplicativo nunca pode usar CompareString para lidar com texto UTF-8.

Normalmente, para comparações que não diferenciam maiúsculas de minúsculas, CompareString mapeia o "i" minúsculo para o maiúsculo "I", mesmo quando a localidade é turca ou azerbaijão. A bandeira NORM_LINGUISTIC_CASING substitui esse comportamento para turco ou azerbaijão. Se esse sinalizador for especificado em conjunto com Turco ou Azerbaijão, LATIN SMALL LETTER DOTLESS I (U+0131) é a forma minúscula da LETRA MAIÚSCULA LATINA I (U+0049) e LATIN SMALL LETTER I (U+0069) é a forma minúscula da LETRA MAIÚSCULA LATINA I WITH DOT ABOVE (U+0130).

A partir do Windows 8: A versão ANSI da função é declarada em Winnls.h e a versão Unicode é declarada em Stringapiset.h. Antes do Windows 8, ambas as versões eram declaradas em Winnls.h.

Observação

O cabeçalho winnls.h define CompareString como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos


Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	winnls.h (inclua Windows.h)
Biblioteca	Kernel32.lib
DLL	Kernel32.dll