STRPTIME(3)

NOME
strptime - converte uma representação de hora do tipo seqüencia de caracter para uma estrutura de hora tm

SINÓPSE
define _XOPEN_SOURCE /* a glibc2 precisa disto */
#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 seqüencia 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 seqüencia 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 seqüencia formato devem ter um caractere que combine na seqüencia de entrada. Exceções são os espaços em branco na seqüencia de formato que podem casar com zero ou mais espaços em branco na seqüencia de entrada.

A função strptime() processa a seqüencia 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 seqüencia de formato, a função pára. O restante das seqüencias 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 da localização; pode ser especificado o nome abreviado ou completo

%b ou %B ou %h
    mês, usando o nome de mês da localização; 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 da localização

%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 na localização 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 da localização

%X  hora, usando o formato de hora da localização

%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 na localização atual, são usados os descritores de campo não modificados.

O modificador E especifica que a seqüencia de entrada pode conter versões alternativas da representação de data e hora que são dependentes da localização:

%Ec a representação alternativa de data e hora da localização.

%EC o nome do ano base (período) na representação alternativa da localização.

%Ex a representação alternativa de data da localização.

%EX a representação alternativa de hora da localização.

%Ey a compensação do %EC (somente o ano) na representação alternativa da localização.

%EY a representação alternativa completa do ano.

O modificador O especifica que a entrada numérica pode estar em um formato alternativo dependente da localização:

%Od or %Oe
    o dia do mês usando os símbolos numéricos alternativos da localização; zeros à esquerda são permitidos mas não requeridos.

%OH a hora (relógio de 24 horas) usnado os símbolos numéricos alternativos da localização.

%OI a hora (relógio de 12 horas) usando os símbolos numéricos alternativos da localização.

%Om o mês usando os símbolos numéricos alternativos da localização.

%OM os minutos usando os símbolos numéricos alternativos da localização.

%OS os segundos usando os símbolos numéricos alternativos da localização.

%OU o número da semana do ano (domingo como o primeiro dia da semana) usando os símbolos numéricos alternativos da localização.

%Ow o número do dia da semana (domingo=0) usando os símbolos numéricos alternativos da localização.

%OW o número da semana do ano (segunda-feira como o primeiro dia da semana) usando os símbolos numéricos alternativos da localização.

%Oy o ano (compensação de %C) usando os símbolos numéricos alternativos da localização.

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 */
    };

VALORES RETORNADOS
O valor de retorno de uma função é um ponteiro para o primeiro caractere não processado nesta chamada de função. Caso a seqüencia de entrada contenha mais caracteres que o requerido pela seqüencia de formato, o valor de retorno aponta logo depois do último caractere de entrada consumido. No caso em que a seqüencia de entrada inteira seja consumida, o valor de retorno aponta para o byte NULO no final da seqüencia. Se strptime() falha em encontrar toda a seqüencia de formato, e portanto ocorre um erro, a função retorna NULO.

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 da localização 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.

VEJA TAMBÉM
time(2), scanf(3), setlocale(3), strftime(3).

TRADUZIDO POR LDP-BR em 21/08/2000.

  Tradução:
Rubens de Jesus Nogueira <darkseid99@usa.net>

  Revisão.:
André Luiz Fassone <lonely_wolf@ig.com.br>