Função CompareString (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, porque duas cadeias de caracteres distintas em sua representação binária podem ser linguisticamente equivalentes. O aplicativo deve testar as cadeias de caracteres quanto à validade 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 de 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 CompareString(
  [in] LCID    Locale,
  [in] DWORD   dwCmpFlags,
  [in] LPCTSTR lpString1,
  [in] int     cchCount1,
  [in] LPCTSTR 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 valores predefinidos a seguir.

[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.

Retornar valor

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 "I" maiúsculo, 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).

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

Requisitos

Requisito	Valor
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