Função GetDateFormatEx (datetimeapi.h)
Formata uma data como uma cadeia de caracteres de data para uma localidade especificada pelo nome. A função formata uma data especificada ou a data do sistema local.
Sintaxe
int GetDateFormatEx(
[in, optional] LPCWSTR lpLocaleName,
[in] DWORD dwFlags,
[in, optional] const SYSTEMTIME *lpDate,
[in, optional] LPCWSTR lpFormat,
[out, optional] LPWSTR lpDateStr,
[in] int cchDate,
[in, optional] LPCWSTR lpCalendar
);
Parâmetros
[in, optional] lpLocaleName
Ponteiro para um nome de localidade ou um dos seguintes valores predefinidos.
[in] dwFlags
Sinalizadores especificando várias opções de função que podem ser definidas se lpFormat estiver definido como NULL. O aplicativo pode especificar uma combinação dos seguintes valores e LOCALE_USE_CP_ACP ou LOCALE_NOUSEROVERRIDE.
Se o aplicativo não especificar DATE_YEARMONTH, DATE_MONTHDAY, DATE_SHORTDATE ou DATE_LONGDATE e lpFormat for definido como NULL, DATE_SHORTDATE será o padrão.
[in, optional] lpDate
Ponteiro para uma estrutura SYSTEMTIME que contém as informações de data a serem formatadas. O aplicativo poderá definir esse parâmetro como NULL se a função for usar a data atual do sistema local.
[in, optional] lpFormat
Ponteiro para uma cadeia de caracteres de imagem de formato usada para formar a data. Os valores possíveis para a cadeia de caracteres de imagem de formato são definidos em Day, Month, Year e Era Format Pictures.
Por exemplo, para obter a cadeia de caracteres de data "Wed, Aug 31 94", o aplicativo usa a cadeia de caracteres de imagem "ddd',' MMM dd yy".
A função usa a localidade especificada apenas para informações não especificadas na cadeia de caracteres de imagem de formato, por exemplo, os nomes de dia e mês para a localidade. O aplicativo pode definir esse parâmetro como NULL para formatar a cadeia de caracteres de acordo com o formato de data para a localidade especificada.
[out, optional] lpDateStr
Ponteiro para um buffer no qual essa função recupera a cadeia de caracteres de data formatada.
[in] cchDate
Tamanho, em caracteres, do buffer lpDateStr . O aplicativo pode definir esse parâmetro como 0 para retornar o tamanho do buffer necessário para manter a cadeia de caracteres de data formatada. Nesse caso, o buffer indicado por lpDateStr não é usado.
[in, optional] lpCalendar
Reservados; deve definir como NULL.
Retornar valor
Retorna o número de caracteres gravados no buffer lpDateStr se tiver êxito. Se o parâmetro cchDate for definido como 0, a função retornará o número de caracteres necessários para manter a cadeia de caracteres de data formatada, incluindo o 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 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.
Comentários
O nome do dia, o nome do dia abreviado, o nome do mês e o nome do mês abreviado são localizados com base no identificador de localidade.
Os valores de data na estrutura indicada por lpDate devem ser válidos. A função verifica cada um dos valores de data: ano, mês, dia e dia da semana. Se o dia da semana estiver incorreto, a função usará o valor correto e não retornará nenhum erro. Se qualquer um dos outros valores de data estiver fora do intervalo correto, a função falhará e definirá o último erro como ERROR_INVALID_PARAMETER.
A função ignora os membros de tempo da estrutura SYSTEMTIME indicada pelo lpDate. Eles incluem wHour, wMinute, wSecond e wMilliseconds.
Se o parâmetro lpFormat contiver uma cadeia de caracteres de formato inválido, a função não retornará erros, mas apenas forma a melhor cadeia de caracteres de data possível. Por exemplo, as únicas imagens de ano válidas são L"yyyy" e L"yyy", em que "L" indica uma cadeia de caracteres Unicode (caracteres de 16 bits). Se L"y" for passado, a função pressupõe L"yy". Se L"yyy" for passado, a função pressupõe L"yyyy". Se mais de quatro imagens de data (L"dddd") ou quatro meses (L"MMMM") forem passadas, a função usará como padrão L"dddd" ou L"MMMM".
O aplicativo deve incluir qualquer texto que deve permanecer em sua forma exata na cadeia de caracteres de data dentro das aspas simples na imagem de formato de data. A aspa única também pode ser usada como um caractere de escape para permitir que a própria aspa seja exibida na cadeia de caracteres de data. No entanto, a sequência de escape deve ser colocada entre duas aspas simples. Por exemplo, para exibir a data como "Maio '93', a cadeia de caracteres de formato é: L"MMMM ''''yy'". As primeiras e últimas aspas simples são as aspas delimitando. A segunda e a terceira aspas simples são a sequência de escape para permitir que a aspa única seja exibida antes do século.
Quando a imagem de data contém uma forma numérica do dia (d ou dd) e o nome do mês completo (MMMM), a forma congênita do nome do mês é recuperada na cadeia de caracteres de data.
Para obter o formato de data curta e longa padrão sem executar nenhuma formatação real, o aplicativo deve usar GetLocaleInfoEx com a constante LOCALE_SSHORTDATE ou LOCALE_SLONGDATE . Para obter o formato de data de um calendário alternativo, o aplicativo usa GetLocaleInfoEx com a constante LOCALE_IOPTIONALCALENDAR . Para obter o formato de data de um calendário específico, o aplicativo usa GetCalendarInfoEx, passando o Identificador de Calendário apropriado. Ele pode chamar EnumCalendarInfoEx ou EnumDateFormatsEx para recuperar formatos de data para um calendário específico.
Essa função pode recuperar dados de localidades personalizadas. Não há garantia de que os dados sejam iguais de computador para computador ou entre execuções de um aplicativo. Se o aplicativo precisar persistir ou transmitir dados, consulte Usando dados de localidade persistente.
O formato DATE_LONGDATE inclui dois tipos de padrões de data: padrões que incluem o dia da semana e padrões que não incluem o dia da semana. Por exemplo, "Terça-feira, 18 de outubro de 2016" ou "18 de outubro de 2016". Se o aplicativo precisar garantir que as datas usem um desses tipos de padrões e não o outro tipo, seu aplicativo deverá executar as seguintes ações:
- Chame a função EnumDateFormatsExEx para obter todos os formatos de data para o formato DATE_LONGDATE.
- Procure o primeiro formato de data passado para a função de retorno de chamada que você especificou para EnumDateFormatsExEx que corresponda ao identificador de calendário solicitado e tenha uma cadeia de caracteres de formato de data que corresponda aos requisitos do seu aplicativo. Por exemplo, procure o formato de primeira data que inclui "dddd" se o aplicativo exigir que a data inclua o nome completo do dia da semana ou procure o formato de primeira data que não inclui "ddd" nem "dddd" se o aplicativo exigir que a data inclua nether o nome abreviado nem o nome completo do dia da semana.
- Chame a função GetDateFormatEx com o parâmetro lpFormat definido como a cadeia de caracteres de formato de data que você identificou como o formato apropriado na função de retorno de chamada.
Se a presença ou ausência do dia da semana no formato de data longa não for importante para seu aplicativo, seu aplicativo poderá chamar GetDateFormatEx diretamente sem primeiro enumerar todos os formatos de data longos chamando EnumDateFormatsExEx.
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.
Começando no Windows 8: GetDateFormatEx é declarado em Datetimeapi.h. Antes de Windows 8, ele foi declarado em Winnls.h.
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 | datetimeapi.h |
| Biblioteca | Kernel32.lib |
| DLL | Kernel32.dll |
Confira também
Imagens de formato dia, mês, ano e era