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

Rotina TCHAR.H	_UNICODE e _MBCS não definidos	_MBCS definido	_UNICODE definido
_tcsftime	strftime	strftime	wcsftime

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:

Código	Cadeia de caracteres de substituição
%a	Nome abreviado do dia da semana na localidade
%A	Nome completo do dia da semana na localidade
%b	Nome abreviado do mês na localidade
%B	Nome completo do mês na localidade
%c	Representação de data e hora apropriada para a localidade
%C	O ano dividido por 100 e truncado para um inteiro, como um número decimal (00-99)
%d	Dia do mês como um número decimal (01-31)
%D	Equivalente a %m/%d/%y
%e	Dia do mês como um número decimal (1 a 31), onde dígitos únicos são precedidos por um espaço
%F	Equivalente a %Y-%m-%d
%g	Os últimos 2 dígitos do ano baseado na semana ISO 8601 como um número decimais (00 a 99)
%G	O ano baseado em semana ISO 8601 como um número decimal
%h	Nome do mês abreviado (equivalente a %b)
%H	Hora em formato de 24 horas (00–23)
%I	Hora em formato de 12 horas (01–12)
%j	Dia do ano como número decimal (001–366)
%m	Mês como número decimal (01–12)
%M	Minuto como número decimal (00–59)
%n	Caractere de nova linha (\n)
%p	Indicador A.M./P.M. da localidade para relógio de 12 horas
%r	Hora do relógio de 12 horas da localidade
%R	Equivalente a %H:%M
%S	Segundo como um número decimal (00-59)
%t	Um caractere de guia horizontal (\t)
%T	Equivalente a %H:%M:%S, o formato de tempo ISO 8601
%u	Dia da semana ISO 8601 como um número decimal (1 a 7; Segunda-feira é 1)
%U	Número da semana do ano como um número decimais (00-53), onde o primeiro domingo é o primeiro dia da semana 1
%V	Número da semana ISO 8601 como um número decimal (00-53)
%w	Dia da semana como um número decimal (0–6; domingo é 0)
%W	Número da semana do ano como um número decimais (00-53), onde a primeira segunda-feira é o primeiro dia da semana 1
%x	Representação de data para a localidade
%X	Representação de hora para a localidade
%y	Ano sem século, como o número decimal (00-99)
%Y	Ano com século, como o número decimal
%z	O deslocamento de UTC no formato ISO 8601; nenhum caractere se o fuso horário for desconhecido
%Z	O nome do fuso horário ou abreviação de fuso horário da localidade, dependendo das configurações do Registro; Nenhum caractere se o fuso horário é desconhecido
%%	Símbolo de porcentagem

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.

Código de formatação	Significado
%#a, %#A, %#b, %#B, %#g%#p%#t%#u%#G%#X%#h%#Z%#n%#w%#z,%#%	# sinalizador é ignorado.
%#c	Representação longa de data e hora, apropriada para a localidade. Por exemplo: "Terça-feira, 14 de março de 1995, 12:41:29".
%#x	Representação longa de data, apropriada para a localidade. Por exemplo: "Terça-feira, 14 de março de 1995".
%#d, %#D, %#e, %#F, %#H%#I%#j%#m%#M%#r%#R%#S%#T%#U%#V%#W%#y%#Y	Remova os zeros à esquerda (se houver).

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.

Observação

Ao usar uma das funções strftime com um ponteiro tm retornado gmtime, os valores impressos por meio dos especificadores %Z e %z não serão precisos. Isso ocorre porque o struct tm conforme especificado pelo C Standard não contém as informações de nome de fuso horário nem diferença de hora. Em vez disso, as informações de fuso horário são preenchidas pelas variáveis globais _timezone e _dstbias.

Requisitos

Rotina	Cabeçalho necessário
strftime	<time.h>
wcsftime	<time.h> ou <wchar.h>
_strftime_l	<time.h>
_wcsftime_l	<time.h> ou <wchar.h>

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