Função FoldStringW (stringapiset.h)

Mapeia uma cadeia de caracteres Unicode para outra, executando a transformação especificada. Para obter uma visão geral do uso das funções de cadeia de caracteres, consulte Cadeias de caracteres.

Sintaxe

int FoldStringW(
  [in]            DWORD                         dwMapFlags,
  [in]            _In_NLS_string_(cchSrc)LPCWCH lpSrcStr,
  [in]            int                           cchSrc,
  [out, optional] LPWSTR                        lpDestStr,
  [in]            int                           cchDest
);

Parâmetros

[in] dwMapFlags

Sinalizadores que especificam o tipo de transformação a ser usado durante o mapeamento de cadeia de caracteres. Esse parâmetro pode ser uma combinação dos seguintes valores.

[in] lpSrcStr

Ponteiro para uma cadeia de caracteres de origem que a função mapeia.

[in] cchSrc

Tamanho, em caracteres, da cadeia de caracteres de origem indicada por lpSrcStr, excluindo o caractere nulo de terminação. O aplicativo pode definir o parâmetro como qualquer valor negativo para especificar que a cadeia de caracteres de origem é terminada em nulo. Nesse caso, a função calcula o comprimento da cadeia de caracteres automaticamente e termina em nulo a cadeia de caracteres mapeada indicada por lpDestStr.

[out, optional] lpDestStr

Ponteiro para um buffer no qual essa função recupera a cadeia de caracteres mapeada.

[in] cchDest

Tamanho, em caracteres, da cadeia de caracteres de destino indicada por lpDestStr. Se o espaço para um caractere nulo de terminação estiver incluído em cchSrc, cchDest também deverá incluir espaço para um caractere nulo de terminação.

O aplicativo pode definir cchDest como 0. Nesse caso, a função não usa o parâmetro lpDestStr e retorna o tamanho do buffer necessário para a cadeia de caracteres mapeada. Se o sinalizador MAP_FOLDDIGITS for especificado, o valor retornado será o tamanho máximo necessário, mesmo que o número real de caracteres necessário seja menor que o tamanho máximo. Se o tamanho máximo não for passado, a função falhará com ERROR_INSUFFICIENT_BUFFER.

Retornar valor

Retorna o número de caracteres na cadeia de caracteres traduzida, incluindo um caractere nulo de terminação, se bem-sucedido. Se a função for bem-sucedida e o valor de cchDest for 0, o valor retornado será o tamanho do buffer necessário para manter a cadeia de caracteres traduzida, incluindo um caractere nulo de terminação.

Essa função retornará 0 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_INSUFFICIENT_BUFFER. Um tamanho de buffer fornecido não era grande o suficiente ou estava definido incorretamente como NULL.
• ERROR_INVALID_DATA. Os dados eram inválidos.
• 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_MOD_NOT_FOUND. O módulo não foi encontrado.
• ERROR_OUTOFMEMORY. Não havia armazenamento suficiente disponível para concluir esta operação.
• ERROR_PROC_NOT_FOUND. O procedimento necessário não foi encontrado.

Comentários

Os valores dos parâmetros lpSrcStr e lpDestStr não devem ser os mesmos. Se forem iguais, a função falhará com ERROR_INVALID_PARAMETER.

A zona de compatibilidade em Unicode consiste em caracteres no intervalo 0xF900 até 0xFFEF que são atribuídos a caracteres de outros padrões de codificação para caracteres, mas na verdade são variantes de caracteres que já estão em Unicode. A zona de compatibilidade é usada para dar suporte ao mapeamento de ida e volta para esses padrões. Os aplicativos podem usar o sinalizador MAP_FOLDCZONE para evitar dar suporte à duplicação de caracteres na zona de compatibilidade.

Começando com o Windows Vista: Essa função dá suporte à normalização Unicode. Todos os caracteres de compatibilidade Unicode são mapeados.

Começando com o Windows Vista: As transformações indicadas pelos sinalizadores MAP_FOLDCZONE, MAP_PRECOMPOSED e MAP_COMPOSITE usam as formas de normalização Unicode KC, C e D (por meio da função NormalizeString ) para fazer os mapeamentos.

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

Confira também

Suporte a idiomas nacionais

Funções de suporte à linguagem nacional

NormalizeString

Considerações sobre segurança: recursos internacionais

Classificação

Usando a normalização unicode para representar cadeias de caracteres