Função FindStringOrdinal (libloaderapi.h)

  • Artigo

Localiza uma cadeia de caracteres Unicode (caracteres largos) em outra cadeia de caracteres Unicode para uma comparação não linguística.

Sintaxe

int FindStringOrdinal(
  [in] DWORD   dwFindStringOrdinalFlags,
  [in] LPCWSTR lpStringSource,
  [in] int     cchSource,
  [in] LPCWSTR lpStringValue,
  [in] int     cchValue,
  [in] BOOL    bIgnoreCase
);

Parâmetros

[in] dwFindStringOrdinalFlags

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.

Valor Significado
FIND_FROMSTART
 Pesquise a cadeia de caracteres, começando com o primeiro caractere da cadeia de caracteres.
FIND_FROMEND
 Pesquise a cadeia de caracteres na direção inversa, começando com o último caractere da cadeia de caracteres.
FIND_STARTSWITH
 Teste para descobrir se o valor especificado por lpStringValue é o primeiro valor na cadeia de caracteres de origem indicada por lpStringSource.
FIND_ENDSWITH
 Teste para descobrir se o valor especificado por lpStringValue é o último valor na cadeia de caracteres de origem indicada por lpStringSource.

[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 normalmente deve especificar um número positivo ou 0. O aplicativo poderá especificar -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 normalmente deve especificar um número positivo ou 0. O aplicativo poderá especificar -1 se a cadeia de caracteres for terminada em nulo e a função deverá calcular o tamanho automaticamente.

[in] bIgnoreCase

TRUE se a função for executar uma comparação que não diferencia maiúsculas de minúsculas e FALSE caso contrário. A comparação não é uma operação linguística e não é apropriada para todas as localidades e idiomas. Seu comportamento é semelhante ao do inglês.

Retornar valor

Retorna um índice baseado em 0 na cadeia de caracteres de origem indicada por lpStringSource se tiver êxito . Se a função for bem-sucedida, a cadeia de caracteres encontrada terá o mesmo tamanho que o valor de lpStringValue. Um valor retornado de 0 indica que a função encontrou uma correspondência no início da cadeia de caracteres de origem.

A função retornará -1 se não tiver êxito ou se não encontrar a cadeia de caracteres de pesquisa. 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

Como FindStringOrdinal fornece uma comparação binária, ele não retorna resultados linguisticamente apropriados. A comparação ordinal pode ser confundida com o comportamento de classificação em inglês. No entanto, ele não encontra correspondências quando os caracteres variam de acordo com quantidades linguisticamente insignificantes. Consulte Classificação para obter informações sobre como escolher uma função de classificação apropriada.

Ao contrário das funções NLS que retornam 0 para falha, essa função retornará -1 se falhar. Com êxito, ele retorna um índice baseado em 0. O uso desse índice ajuda a função a evitar erros off-by-one e estouros de buffer de um caractere.

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.

Começando com Windows 8: FindStringOrdinal é declarado em Libloaderapi.h. Antes de Windows 8, ele foi declarado em Winnls.h.

Requisitos

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

Confira também

FindNLSString

FindNLSStringEx

Manipulando a classificação em seus aplicativos

Suporte à linguagem nacional

Funções de suporte à linguagem nacional