Função GetNumberFormatEx (winnls.h)

  • Artigo

Formata uma cadeia de caracteres numérica como uma cadeia de caracteres numérica personalizada para uma localidade especificada pelo nome.

Nota O aplicativo deve chamar essa função em preferência para GetNumberFormat se projetado para ser executado somente no Windows Vista e posterior.

 
Nota Essa função pode formatar dados que são alterados entre versões, por exemplo, devido a uma localidade personalizada. Se o aplicativo precisar persistir ou transmitir dados, consulte Usando dados de localidade persistente.
 

Sintaxe

int GetNumberFormatEx(
  [in, optional]  LPCWSTR          lpLocaleName,
  [in]            DWORD            dwFlags,
  [in]            LPCWSTR          lpValue,
  [in, optional]  const NUMBERFMTW *lpFormat,
  [out, optional] LPWSTR           lpNumberStr,
  [in]            int              cchNumber
);

Parâmetros

[in, optional] lpLocaleName

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

[in] dwFlags

Sinalizadores que controlam a operação da função. O aplicativo deve definir esse parâmetro como 0 se lpFormat não estiver definido como NULL. Nesse caso, a função formata a cadeia de caracteres usando substituições de usuário para o formato de número padrão para a localidade. Se lpFormat estiver definido como NULL, o aplicativo poderá especificar LOCALE_NOUSEROVERRIDE formatar a cadeia de caracteres usando o formato de número padrão do sistema para a localidade especificada.

Cuidado O uso de LOCALE_NOUSEROVERRIDE é altamente desencorajado, pois desabilita as preferências do usuário.
 

[in] lpValue

Ponteiro para uma cadeia de caracteres terminada em nulo que contém a cadeia de caracteres de número a ser formatada. Essa cadeia de caracteres só pode conter os caracteres a seguir. Todos os outros caracteres são inválidos. A função retornará um erro se a cadeia de caracteres indicada por lpValue se desviar dessas regras.

  • Caracteres "0" a "9".
  • Um ponto decimal (ponto) se o número for um valor de ponto flutuante.
  • Um sinal de subtração na posição do primeiro caractere se o número for um valor negativo.

[in, optional] lpFormat

Ponteiro para uma estrutura NUMBERFMT que contém informações de formatação numérica, com todos os membros definidos como valores apropriados. Se o aplicativo não definir esse parâmetro como NULL, a função usará a localidade somente para formatar informações não especificadas na estrutura, por exemplo, o valor da cadeia de caracteres de localidade para o sinal negativo.

[out, optional] lpNumberStr

Ponteiro para um buffer no qual essa função recupera a cadeia de caracteres de número formatada. Como alternativa, esse parâmetro conterá NULL se cchNumber estiver definido como 0. Nesse caso, a função retorna o tamanho necessário para o buffer de cadeia de caracteres numérica.

[in] cchNumber

Tamanho, em caracteres, para o buffer de cadeia de caracteres de número indicado por lpNumberStr. Como alternativa, o aplicativo pode definir esse parâmetro como 0. Nesse caso, a função retorna o tamanho necessário para o buffer de cadeia de caracteres numérica e não usa o parâmetro lpNumberStr .

Retornar valor

Retorna o número de caracteres recuperados no buffer indicado por lpNumberStr se tiver êxito. Se o parâmetro cchNumber for definido como 0, a função retornará o número de caracteres necessários para manter a cadeia de caracteres numérica formatada, incluindo um caractere nulo de terminação.

A 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 foi definido incorretamente como NULL.
  • 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_OUTOFMEMORY. Não havia armazenamento suficiente disponível para concluir essa operação.

Comentários

Começando no 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

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

Confira também

GetNumberFormat

NUMBERFMT

Suporte à linguagem nacional

Funções de suporte à linguagem nacional