Função lstrcmpiA (winbase.h)

Artigo
11/20/2024

Compara duas cadeias de caracteres. A comparação não diferencia maiúsculas de minúsculas.

Para executar uma comparação que diferencia maiúsculas de minúsculas, use a função lstrcmp.

Sintaxe

int lstrcmpiA(
  [in] LPCSTR lpString1,
  [in] LPCSTR lpString2
);

Parâmetros

[in] lpString1

Tipo: LPCTSTR

A primeira cadeia de caracteres terminada em nulo a ser comparada.

[in] lpString2

Tipo: LPCTSTR

A segunda cadeia de caracteres terminada em nulo a ser comparada.

Valor de retorno

Tipo: int

Se a cadeia de caracteres apontada por lpString1 for menor que a cadeia de caracteres apontada por lpString2, o valor retornado será negativo. Se a cadeia de caracteres apontada por lpString1 for maior que a cadeia de caracteres apontada por lpString2, o valor retornado será positivo. Se as cadeias de caracteres forem iguais, o valor retornado será zero.

Observações

A função lstrcmpi compara duas cadeias de caracteres verificando os primeiros caracteres entre si, os segundos caracteres uns contra os outros e assim por diante até encontrar uma desigualdade ou atingir as extremidades das cadeias de caracteres.

Observe que os parâmetros lpString1 e lpString2 devem ser encerrados em nulo, caso contrário, a comparação de cadeia de caracteres pode ser incorreta.

A função chama CompareStringEx, usando a localidade do thread atual e subtrai 2 do resultado, para manter as convenções de tempo de execução C para comparar cadeias de caracteres.

Para algumas localidades, a função lstrcmpi pode ser insuficiente. Se isso ocorrer, use CompareStringEx para garantir a comparação adequada. Por exemplo, no Japão, chame com os valores NORM_IGNORECASE, NORM_IGNOREKANATYPEe NORM_IGNOREWIDTH para obter a comparação de cadeia de caracteres não exata mais apropriada. Os valores NORM_IGNOREKANATYPE e NORM_IGNOREWIDTH são ignorados em localidades não asiáticas, para que você possa definir esses valores para todas as localidades e ter a garantia de ter uma classificação culturalmente correta "insensível", independentemente da localidade. Observe que especificar esses valores reduz o desempenho, portanto, use-os somente quando necessário.

Com uma versão DBCS (conjunto de caracteres de dois bytes) do sistema, essa função pode comparar duas cadeias de caracteres DBCS.

A função lstrcmpi usa uma classificação de palavra, em vez de uma classificação de cadeia de caracteres. Uma classificação de palavra trata hifens e apóstrofos de forma diferente do que trata outros símbolos que não são alfanuméricos, a fim de garantir que palavras como "coop" e "co-op" permaneçam juntas dentro de uma lista classificada. Para obter uma discussão detalhada sobre classificações de palavras e classificações de cadeia de caracteres, consulte manipulação de classificação em seus aplicativos.

Comentários de segurança

Consulte considerações de segurança: recursos internacionais para considerações de segurança sobre a escolha de funções de comparação.

Nota

O cabeçalho winbase.h define lstrcmpi como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows 2000 Professional [somente aplicativos da área de trabalho]
servidor com suporte mínimo	Windows 2000 Server [somente aplicativos da área de trabalho]
da Plataforma de Destino	Windows
cabeçalho	winbase.h (inclua Windows.h)
biblioteca	Kernel32.lib
de DLL	Kernel32.dll