Função FindStringOrdinal (libloaderapi.h)
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.
[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 |