NOME¶
strptime - converte uma representação de hora do tipo string para
uma estrutura de hora tm
SINOPSE¶
#include <time.h>
char *strptime(const char *s, const char
*formato, struct tm *tm);
DESCRIÇÃO¶
strptime() é a função complementar a
strftime() e converte a string de caracteres apontada por
s para
valores que são armazenadas na estrutura
tm apontada por
tm, usando o formato especificado pelo
formato. Aqui o
formato é uma string de caracteres que consiste de descritores
de campo e caracteres de texto, reminiscentes do
scanf(3). Cada
descritor de campo consiste de um caractere
% seguido por outros
caracteres que especificam a sustituição para o descritor de
campo. Todos os outros caracteres na string
formato devem ter um
caractere que combine na string de entrada. Exceções são
os espaços em branco na string de formato que podem casar com zero ou
mais espaços em branco na string de entrada.
A função
strptime() processa a string de entrada da direita
para a esquerda. Cada um dos três elementos de entrada possíveis
(espaço em branco, literal ou formato) são manipulados um
após o outro. Se a entrada não pode ser casada com a string de
formato, a função pára. O restante das strings de formato
e de entrada não são processadas.
Os seguintes descritores de campo são suportados:
- %%
- o caractere %
- %a ou %A
- dia da semana, usando os nomes dos dias da semana do 'locale'; pode ser
especificado o nome abreviado ou completo
- %b ou %B ou %h
- mês, usando o nome de mês do 'locale'; pode ser especificado
o nome abreviado ou completo
- %c
- data e hora como %x %X
- %C
- data e hora, na representação de data e hora em formato
longo do 'locale'
- %d or %e
- dia do mês (1-31; zeros à esquerda são permitidos mas
não requeridos)
- %D
- data como %m/%d/%y
- %H or %k
- hora (0-23; zeros à esquerda são permitidos mas não
requeridos)
- %I or %l
- hora (0-12; zeros à esquerda são permitidos mas não
requeridos)
- %j
- número do dia do ano (001-366)
- %m
- número do mês (1-12; zeros à esquerda são
permitidos mas não requeridos)
- %M
- minutos (0-59; zeros à esquerda são permitidos mas
não requeridos)
- %p
- equivalente do 'locale' ao AM ou PM
- %r
- hora como %I:%M:%S %p
- %R
- hora como %H:%M
- %S
- segundos (0-61; zeros à esquerda são permitidos mas
não requeridos. O segundo extra é permitido para anos
bissextos)
- %T
- hora como %H:%M:%S
- %w
- número do dia da semana (0-6) com o domindo sendo o primeiro dia da
semana
- %x
- data, usando o formato de data do 'locale'
- %X
- hora, usando o formato de hora do 'locale'
- %y
- ano dentro do século (0-99; zeros à esquerda são
permitidos mas não requeridos. Caso um século não
seja especificado, os valores na faixa de 69 a 99 se referem aos anos no
século XX (1969 a 1999 inclusive); valores na faixa de 00 a 68 se
referem aos anos no século XXI (2000 a 2068 inclusive).
- %Y
- ano, incluindo o século (por exemplo, 1988)
Maiúsculas e minúsculas são ignoradas ao encontrar itens
como nomes de meses ou dias da semana.
Alguns descritores de campo podem ser modificados pelos caracteres modificadores
E e O para indicar que um formato ou uma especificação
alternativa devem ser usados. Se o formato ou a especificação
alternativa não existem no 'locale' corrente, são usados os
descritores de campo não modificados.
O modificador E especifica que a string de entrada pode conter versões
alternativas da representação de data e hora que são
dependentes do 'locale':
- %Ec
- a representação alternativa de data e hora do 'locale'.
- %EC
- o nome do ano base (período) na representação
alternativa do 'locale'.
- %Ex
- a representação alternativa de data do 'locale'.
- %EX
- a representação alternativa de hora do 'locale'.
- %Ey
- a compensação do %EC (somente o ano) na
representação alternativa do 'locale'.
- %EY
- a representação alternativa completa do ano.
O modificador O especifica que a entrada numérica pode estar em um
formato alternativo dependente do 'locale':
- %Od or %Oe
- o dia do mês usando os símbolos numéricos
alternativos do 'locale'; zeros à esquerda são permitidos
mas não requeridos.
- %OH
- a hora (relógio de 24 horas) usnado os símbolos
numéricos alternativos do 'locale'.
- %OI
- a hora (relógio de 12 horas) usando os símbolos
numéricos alternativos do 'locale'.
- %Om
- o mês usando os símbolos numéricos alternativos do
'locale'.
- %OM
- os minutos usando os símbolos numéricos alternativos do
'locale'.
- %OS
- os segundos usando os símbolos numéricos alternativos do
'locale'.
- %OU
- o número da semana do ano (domingo como o primeiro dia da semana)
usando os símbolos numéricos alternativos do 'locale'.
- %Ow
- o número do dia da semana (domingo=0) usando os símbolos
numéricos alternativos do 'locale'.
- %OW
- o número da semana do ano (segunda-feira como o primeiro dia da
semana) usando os símbolos numéricos alternativos do
'locale'.
- %Oy
- o ano (compensação de %C) usando os símbolos
numéricos alternativos do 'locale'.
A estrutura de horas quebrada
tm é definida em
<time.h> como segue:
struct tm
{
int tm_sec; /* segundos */
int tm_min; /* minutos */
int tm_hour; /* horas */
int tm_mday; /* dia do mês */
int tm_mon; /* mês */
int tm_year; /* ano */
int tm_wday; /* dia da semana */
int tm_yday; /* dia do ano */
int tm_isdst; /* horário de verão */
};
VALOR DE RETORNO¶
O valor de retorno de uma função é um ponteiro para o
primeiro caractere não processado nesta chamada de
função. Caso a string de entrada contenha mais caracteres que o
requerido pela string de formato, o valor de retorno aponta logo depois do
último caractere de entrada consumido. No caso em que a string de
entrada inteira seja consumida, o valor de retorno aponta para o byte NUL no
final da string. Se
strptime() falha em encontrar toda a string de
formato, e portanto ocorre um erro, a função retorna
NULL.
VEJA TAMBÉM¶
strftime(3),
time(2),
setlocale(3),
scanf(3)
NOTAS¶
A princípio, esta função não inicializa
tm,
mas apenas armazena os valores especificados. Isto significa que
tm
deve ser inicializado antes da chamada. Detalhes diferem um pouco entre
diferentes sistemas Unix. A implementação da libc GNU não
toca naqueles campos que não são especificados explicitamente,
exceto por recomputar os campos
tm_wday e
tm_yday se qualquer um
dos elementos ano, mês ou dia mudaram.
Esta função é disponível somente em bibliotecas mais
recentes que a versão 4.6.5. As inclusões da libc4 e da libc5 do
Linux definem o protótipo incondicionalmente; a inclusão glibc2
fornece um protótipo somente quando _XOPEN_SOURCE ou _GNU_SOURCE
são definidos. Os caracteres modificadores de 'locale' E e O são
aceitos desde a libc 5.4.13. A especificação 'y' (ano no
século) é tomada para especificar um ano no século XX na
libc4 e na libc5. Será um ano na faixa de 1950 a 2049 pela glib2.0, e
um ano na faixa de 1969 a 2068 pela glibc2.1.
TRADUÇÃO PARA A LÍNGUA PORTUGUESA¶
RUBENS DE JESUS NOGUEIRA <darkseid99@usa.net> (tradução)
XXXXXX XX XXXXX XXXXXXXX <xxxxxxxxxx@xxx.xxx> (revisão)