Função FindNLSStringEx (winnls.h)

Localiza uma cadeia de caracteres Unicode (caracteres largos) ou seu equivalente em outra cadeia de caracteres Unicode para uma localidade especificada pelo nome.

Sintaxe

int FindNLSStringEx(
  [in, optional]  LPCWSTR          lpLocaleName,
  [in]            DWORD            dwFindNLSStringFlags,
  [in]            LPCWSTR          lpStringSource,
  [in]            int              cchSource,
  [in]            LPCWSTR          lpStringValue,
  [in]            int              cchValue,
  [out, optional] LPINT            pcchFound,
  [in, optional]  LPNLSVERSIONINFO lpVersionInformation,
  [in, optional]  LPVOID           lpReserved,
  [in, optional]  LPARAM           sortHandle
);

Parâmetros

[in, optional] lpLocaleName

Ponteiro para um nome de localidade ou um dos seguintes valores predefinidos.

• LOCALE_NAME_INVARIANT
• LOCALE_NAME_SYSTEM_DEFAULT
• LOCALE_NAME_USER_DEFAULT

[in] dwFindNLSStringFlags

Sinalizadores especificando detalhes da operação de localização. Esses sinalizadores são mutuamente exclusivos, com FIND_FROMSTART sendo o padrão. O aplicativo pode especificar apenas um dos sinalizadores de localização com qualquer um dos sinalizadores de filtragem definidos na próxima tabela. Se o aplicativo não especificar um sinalizador, a função usará a comparação padrão para a localidade especificada. Conforme discutido em Tratamento de Classificação em Seus Aplicativos, não há modo de comparação binária.

O aplicativo pode usar os sinalizadores de filtragem definidos abaixo em combinação com um sinalizador de localização.

[in] lpStringSource

Ponteiro para a cadeia de caracteres de origem, na qual a função pesquisa a cadeia de caracteres especificada por lpStringValue.

[in] cchSource

Tamanho, em caracteres excluindo o caractere nulo de terminação, da cadeia de caracteres indicada por lpStringSource. O aplicativo não pode especificar 0 ou nenhum número negativo diferente de -1 para esse parâmetro. O aplicativo especifica -1 se a cadeia de caracteres de origem for terminada em nulo e a função deverá calcular o tamanho automaticamente.

[in] lpStringValue

Ponteiro para a cadeia de caracteres de pesquisa, para a qual a função pesquisa na cadeia de caracteres de origem.

[in] cchValue

Tamanho, em caracteres excluindo o caractere nulo de terminação, da cadeia de caracteres indicada por lpStringValue. O aplicativo não pode especificar 0 ou nenhum número negativo diferente de -1 para esse parâmetro. O aplicativo especifica -1 se a cadeia de caracteres de pesquisa for terminada em nulo e a função deverá calcular o tamanho automaticamente.

[out, optional] pcchFound

Ponteiro para um buffer que contém o comprimento da cadeia de caracteres que a função encontra. A cadeia de caracteres pode ser maior ou menor do que a cadeia de caracteres de pesquisa. Se a função não encontrar a cadeia de caracteres de pesquisa, esse parâmetro não será modificado.

A função pode recuperar NULL nesse parâmetro. Nesse caso, a função não indica se o comprimento da cadeia de caracteres encontrada difere do comprimento da cadeia de caracteres de origem.

Observe que o valor de pcchFound geralmente é idêntico ao valor fornecido em cchValue, mas pode ser diferente nos seguintes casos:

• O valor fornecido em cchValue é negativo.
• As cadeias de caracteres são equivalentes, mas têm comprimentos diferentes. Por exemplo, "A" mais "Combining Ring" (U+0041 U+030A) é equivalente ao "Anel A" (U+00c5).

[in, optional] lpVersionInformation

Reservados; deve ser NULL.

[in, optional] lpReserved

Reservados; deve ser NULL.

[in, optional] sortHandle

Reservados; deve ser 0.

Valor retornado

Retorna um índice baseado em 0 na cadeia de caracteres de origem indicada por lpStringSource se tiver êxito . Em combinação com o valor em pcchFound, esse índice fornece o local exato de toda a cadeia de caracteres encontrada na cadeia de caracteres de origem. Um valor retornado de 0 é um índice sem erros na cadeia de caracteres de origem e a cadeia de caracteres correspondente está na cadeia de caracteres de origem no deslocamento 0.

A função retornará -1 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 não eram válidos.
• ERROR_INVALID_PARAMETER. Qualquer um dos valores de parâmetro era inválido.
• ERROR_SUCCESS. A ação foi concluída com êxito, mas não rendeu resultados.

Comentários

Essa função fornece uma variedade de opções de pesquisa, incluindo direção de pesquisa, filtragem de equivalência de caracteres e filtragem específica da localidade. Observe que a equivalência depende da localidade e dos sinalizadores especificados na chamada para a função. Os sinalizadores de filtragem podem alterar os resultados da pesquisa. Por exemplo, as possíveis correspondências aumentam quando a função ignora marcas de maiúsculas e minúsculas ou diacríticas ao executar a pesquisa.

Por padrão, essa função mapeia o "i" minúsculo para o maiúsculo "I", mesmo quando o parâmetro Locale especifica turco (Turquia) ou Azerbaijão (Azerbaijão). Para substituir esse comportamento para turco ou Azerbaijão, o aplicativo deve especificar NORM_LINGUISTIC_CASING. Se esse sinalizador for especificado para a localidade correta, "ı" (minúsculas sem ponto I) é a forma minúscula de "I" (maiúsculas e minúsculas sem ponto I) e "i" (minúsculas pontilhadas I) é a forma minúscula de "ı" (maiúscula pontilhada I).

Para muitos scripts (notadamente scripts latinos), NORM_IGNORENONSPACE coincide com LINGUISTIC_IGNOREDIACRITIC e NORM_IGNORECASE coincide com LINGUISTIC_IGNORECASE, com as seguintes exceções:

• NORM_IGNORENONSPACE ignora qualquer distinção secundária, seja uma diacrítica ou não. Scripts para idiomas coreano, japonês, chinês, índice e outros usam essa distinção para fins diferentes de diacríticos. LINGUISTIC_IGNOREDIACRITIC ignora apenas os diacríticos reais, em vez de simplesmente ignorar o segundo peso de classificação.
• NORM_IGNORECASE ignora qualquer distinção terciária, seja ou não um caso linguístico. Por exemplo, em scripts árabes e índices, esse sinalizador distingue formas alternativas de um caractere. No entanto, as diferenças não correspondem ao caso linguístico. LINGUISTIC_IGNORECASE ignora apenas maiúsculas e minúsculas linguísticas reais, em vez de ignorar o terceiro peso de classificação.

Essa função é uma das poucas funções NLS que chama SetLastError mesmo quando é bem-sucedida. Ele faz essa chamada para limpar o último erro em um thread quando ele não corresponde à cadeia de caracteres de pesquisa. Isso limpa o valor retornado por GetLastError.

A partir do 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.

Requisitos

Confira também

CompareStringEx

FindNLSString

Manipulando a classificação em seus aplicativos

LCMapStringEx

Suporte à linguagem nacional

Funções de suporte à linguagem nacional

Considerações sobre segurança: recursos internacionais