strftime, wcsftime, _strftime_l, _wcsftime_l

Formate uma cadeia de caracteres de hora.

Sintaxe

size_t strftime(
   char *strDest,
   size_t maxsize,
   const char *format,
   const struct tm *timeptr
);
size_t _strftime_l(
   char *strDest,
   size_t maxsize,
   const char *format,
   const struct tm *timeptr,
   _locale_t locale
);
size_t wcsftime(
   wchar_t *strDest,
   size_t maxsize,
   const wchar_t *format,
   const struct tm *timeptr
);
size_t _wcsftime_l(
   wchar_t *strDest,
   size_t maxsize,
   const wchar_t *format,
   const struct tm *timeptr,
   _locale_t locale
);

Parâmetros

strDest
Cadeia de caracteres de saída.

maxsize
Tamanho do strDest buffer, medido em caracteres (char ou wchar_t).

format
Cadeia de caracteres de controle de formato.

timeptr
estrutura de dados tm.

locale
A localidade a ser usada.

Valor retornado

strftime retorna o número de caracteres colocados em strDest e wcsftime retorna o número correspondente de caracteres largos.

Se o número total de caracteres, incluindo a terminação nula, é mais de maxsize, ambos strftime e wcsftime retornam 0 e os conteúdos de strDest serão indeterminados.

O número de caracteres em strDest é igual ao número de caracteres literais em format, mais quaisquer caracteres que possam ser adicionados por format meio de códigos de formatação. O nulo de terminação de uma cadeia de caracteres não é contado no valor retornado.

Comentários

As strftime funções e wcsftime formatam o valor de tm tempo de timeptr acordo com o argumento fornecido format e armazenam o resultado no buffer strDest. No máximo, caracteres maxsize são colocados na cadeia de caracteres. Para obter uma descrição dos campos na estrutura timeptr, consulte asctime. wcsftime é o equivalente de caractere largo de strftime; seu argumento de cadeia de caracteres aponta para uma cadeia de caracteres largos. Caso contrário, essas funções se comportam de forma idêntica.

Essa função valida seus parâmetros. Se strDest, format, ou timeptr for um ponteiro nulo, ou se a estrutura de dados endereçada tm for timeptr inválida (por exemplo, se contiver valores fora do intervalo para a hora ou data), ou se a format cadeia de caracteres contiver um código de formatação inválido, o manipulador de parâmetro inválido será invocado, conforme descrito em Validação de parâmetro. Se a execução puder continuar, a função retornará 0 e definirá errno como EINVAL.

Por padrão, o estado global dessa função tem como escopo o aplicativo. Para alterar esse comportamento, confira Estado global no CRT.

Mapeamentos de rotina de texto genérico

O format argumento consiste de um ou mais códigos, como em printf, os códigos de formatação são precedidos por um sinal de porcentagem (%). Os caracteres que não começam com % são copiados inalterados para strDest. A categoria LC_TIME da localidade atual afeta a formatação de saída de strftime. (Para obter mais informações sobre LC_TIME, consulte setlocale.) As strftime funções e wcsftime usam a localidade definida no momento. As versões _strftime_l e _wcsftime_l dessas funções são idênticas, exceto que usam a localidade como parâmetro e a usam em vez da localidade definida atualmente. Para obter mais informações, consulte Localidade.

As funções strftime dão suporte a esses códigos de formatação:

Como na função printf, o # sinalizador pode ser prefixo em qualquer código de formatação. Nesse caso, o significado do código de formatação é alterado da seguinte maneira.

A semana ISO 8601 e o ano baseado em semana produzidos por %V, %g, e %G, usa uma semana que começa na segunda-feira. A semana 1 é a semana que contém o quarto dia de janeiro, que é a primeira semana que inclui pelo menos quatro dias do ano. Se a primeira segunda-feira do ano for a 2ª, a 3ª ou a 4ª, os dias anteriores fazem parte da última semana do ano anterior. Para esses dias, %V é substituído por 53 e %g e %G são substituídos pelos dígitos do ano anterior.

Requisitos

As funções _strftime_l e _wcsftime_l são específicas da Microsoft. Para obter informações sobre compatibilidade, consulte Compatibilidade.

Exemplo

Confira o exemplo de time.

Confira também

Localidade
Gerenciamento de tempo
Manipulação de cadeia de caracteres
localeconv
setlocale, _wsetlocale
Funções strcoll
strxfrm, wcsxfrm, _strxfrm_l, _wcsxfrm_l