NOMBRE¶
strptime - convierte una cadena de caracteres que representa un tiempo a una
estructura tm
SINOPSIS¶
#define _XOPEN_SOURCE /* requerido por glibc2 */
#include <time.h>
char *strptime(const char *s, const char
*format, struct tm *tm);
DESCRIPCIÓN¶
La función
strptime() es la función inversa de
strftime() y convierte la cadena de caracteres a la que apunte
s
en valores que son almacenados en la estructura
tm a la que apunte
tm, utilizando el formato especificado por
format.
format
es una cadena de caracteres que consiste en descriptores de campos y
caracteres de texto, una reminiscencia de
scanf(3). Cada descriptor de
campo consiste en un carácter de porcentaje
% seguido por otro
carácter que especifica el reemplazo para el descriptor de campo. Todos
los otros caracteres de la cadena
format deben tener un carácter
concordante en la cadena de entrada, salvo los espacios en blanco que pueden
concordar con cero o más espacios en blanco de la cadena de entrada.
Entre dos descriptores de campo cualesquiera debe haber siempre un espacio en
blanco o bien otros caracteres alfanuméricos.
La función
strptime() procesa la cadena de entrada de izquierda a
derecha. Cada uno de los tres posibles elementos de entrada (espacio en
blanco, literal o formato) se tratan uno detrás de otro. Si no se puede
hacer coincidir la entrada con la cadena de formato, la función se
detiene. El resto de las cadenas de formato y de entrada no se procesa.
Los descriptores de campo de entrada se listan a continuación. En caso de
que la concordancia sea con cadenas de texto (como el nombre de un día
de la semana o de un mes), la comparación no tiene en cuenta las
mayúsculas. En caso de que la concordancia sea con números, se
permite poner ceros al principio aunque no es obligatorio.
- %%
- El carácter %.
- %a o %A
- El nombre del día de la semana según la localización
actual, en forma abreviada o completa.
- %b o %B o %h
- El nombre del mes según la localización actual, en forma
abreviada o completa.
- %c
- La representación de fecha y hora para la localización
actual.
- %C
- El número de siglo (0-99).
- %d o %e
- El día del mes (1-31).
- %D
- Equivalente a %m/%d/%y. (Este es el estilo americano para las fechas, muy
confuso para los no americanos, especialmente debido a que el formato
%d/%m/%y es el que se usa ampliamente en Europa. El formato del
estándar ISO 8601 es %Y-%m-%d.)
- %H
- La hora (0-23).
- %I
- La hora en formato de 12 horas (1-12).
- %j
- El número de día del año (1-366).
- %m
- El número de mes (1-12).
- %M
- El minuto (0-59).
- %n
- Cadena arbitraria de espacios en blanco.
- %p
- El equivalente de AM o PM en la localización. (Nota: puede no
existir.)
- %r
- La hora en formato de 12 horas (usando el equivalente de AM o PM en la
localización). En la localización POSIX equivale a %I:%M:%S
%p. Si el campo t_fmt_ampm está vacío en la
categoría LC_TIME de la localización actual el
comportamiento es indefinido.
- %R
- Equivalente a %H:%M.
- %S
- El segundo (0-60; 60 puede darse para segundos de salto (leap seconds);
anteriormente también se permitía 61).
- %t
- Cadena arbitraria de espacios en blanco.
- %T
- Equivalente a %H:%M:%S.
- %U
- El número de semana tomando el domingo como primer día de la
semana (0-53). El primer domingo de enero es el primer día de la
semana 1.
- %w
- El número de día de la semana (0-6) con domingo = 0.
- %W
- El número de semana tomando el lunes como primer día de la
semana (0-53). El primer lunes de enero es el primer día de la
semana 1.
- %x
- La fecha, usando el formato de fecha de la localización.
- %X
- La hora, usando el formato de hora de la localización.
- %y
- El año dentro del siglo (0-99). Cuando no se especifica el siglo,
los valores comprendidos en el rango 69-99 se refieren al siglo 20
(1969-1999) y los valores comprendidos en el rango 00-68 se refieren al
siglo 21 (2000-2068).
- %Y
- El año, incluyendo el siglo (por ejemplo, 1991).
Algunos descriptores de campo pueden ser modificados por los caracteres
modificadores E u O para indicar el uso de un formato o especificación
alternativo. Si el formato o especificación alternativo no existe en la
localización actual, se utiliza el descriptor de campo sin modificar.
El modificador E especifica que la cadena de entrada puede contener versiones
alternativas de la representación de fecha y hora dependientes de la
localización:
- %Ec
- La representación alternativa de fecha y hora de la
localización.
- %EC
- El nombre del año base (período) en la representación
alternativa de la localización.
- %Ex
- La representación alternativa de fecha de la
localización.
- %EX
- La representación alternativa de hora de la
localización.
- %Ey
- El desplazamiento desde %EC (sólo año) en la
representación alternativa de la localización.
- %EY
- La representación alternativa completa para el año.
El modificador O especifica que la entrada numérica puede estar en un
formato alternativo dependiente de la localización:
- %Od o %Oe
- El día del mes usando los símbolos numéricos
alternativos de la localización; los ceros del comienzo
están permitidos pero no son obligatorios.
- %OH
- La hora (foramto 24 horas) usando los símbolos numéricos
alternativos de la localización.
- %OI
- La hora (foramto 12 horas) usando los símbolos numéricos
alternativos de la localización.
- %Om
- El mes usando los símbolos numéricos alternativos de la
localización.
- %OM
- Los minutos usando los símbolos numéricos alternativos de la
localización.
- %OS
- Los segundos usando los símbolos numéricos alternativos de
la localización.
- %OU
- El número de semana del año (tomando el domingo como primer
día de la semana) usando los símbolos numéricos
alternativos de la localización.
- %Ow
- El número del día de la semana (domingo=0) usando los
símbolos numéricos alternativos de la
localización.
- %OW
- El número de semana del año (tomando el lunes como primer
día de la semana) usando los símbolos numéricos
alternativos de la localización.
- %Oy
- El año (desplazamiento desde %C) usando los símbolos
numéricos alternativos de la localización.
La estructura de tiempo descompuesto
tm se define en
<time.h> como sigue:
struct tm {
int tm_sec; /* segundos */
int tm_min; /* minutos */
int tm_hour; /* horas */
int tm_mday; /* día del mes */
int tm_mon; /* mes */
int tm_year; /* año */
int tm_wday; /* día de la semana */
int tm_yday; /* día del año */
int tm_isdst; /* ¿cambio horario? */
};
VALOR DEVUELTO¶
El valor devuelto por la función es un puntero al primer carácter
no procesado en esta llamada a la función. En el caso de que la cadena
de entrada contenga más caracteres de los que necesita la cadena de
formato, el valor devuelto apunta justo después del último
carácter de entrada consumido. En el caso de que se consuma toda la
cadena de entrada, el valor devuelto apunta al byte NUL al final de la cadena.
Si
strptime() no puede hacer coincidir toda la cadena de formato y, por
tanto, se ha producido un error, la función devuelve
NULL.
XPG4, SUSv2, POSIX 1003.1-2001.
EJEMPLO¶
El siguiente ejemplo demuestra el uso de
strptime() y
strftime().
#include <stdio.h>
#include <time.h>
int main() {
struct tm tm;
char buf[255];
strptime("2001-11-12 18:31:01", "%Y-%m-%d %H:%M:%S", &tm);
strftime(buf, sizeof(buf), "%d %b %Y %H:%M", &tm);
puts(buf);
return 0;
}
EXTENSIONES DE GNU¶
Por razones de simetría, glibc trata de dar soporte en
strptime a
los mismos caracteres de formato que para
strftime. (En la
mayoría de casos se analizan los campos correspondientes, pero no se
modifica ningún campo de la estructura
tm.) Esto conduce a
- %F
- Equivalente a %Y-%m-%d, el formato de fecha de ISO 8601.
- %g
- El año correspondiente al número de semana ISO, pero sin el
siglo (0-99).
- %G
- El año correspondiente al número de semana ISO. (Por
ejemplo, 1991.)
- %u
- El día de la semana como un número decimal (1-7, donde lunes
= 1).
- %V
- El número de semana ISO 8601:1988 como un número decimal
(1-53). Si la semana (comenzando en lunes) que contiene el 1 de enero
tiene cuatro o más días en el nuevo año, se considera
la semana 1. En otro caso, se toma como la última semana del
año anterior y la siguiente semana pasa a ser la semana 1.
- %z
- Una especificación estándar RFC-822/ISO 8601 de huso
horario.
- %Z
- El nombre del huso horario.
De manera similar, debido a las extensiones hechas por GNU a
strftime, se
acepta %k como sinónimo de %H, %l debería ser aceptado como
sinónimo de %I y %P se acepta como sinónimo de %p. Finalmente
- %s
- El número de segundos desde la época, es decir, desde la
media noche del 1 de enero de 1970 (1970-01-01 00:00:00 UTC). Los segundos
de salto (leap seconds) no se tienen en cuenta a menos que se encuentre
disponible el soporte para segundos de salto.
La implementación de libc de GNU no requiere que haya espacios en blanco
entre dos descriptores de campo.
OBSERVACIONES¶
En principio, esta función no inicializa la estructura
tm sino que
simplemente almacena los valores especificados. Esto quiere decir que la
estructura
tm debe ser inicializada antes de la llamada. Los detalles
pueden diferir ligeramente entre diferentes sistemas Unix. La
implementación de libc de GNU no modifica aquellos campos que no son
especificados explícitamente, salvo los campos
tm_wday y
tm_yday que son recalculados si cualquiera de los elementos año,
mes o día son alterados.
Esta función está disponible desde la versión 4.6.8 de
libc. Los ficheros de cabecera de libc4 y libc5 en Linux definen el prototipo
de manera incondicional; los ficheros de cabecera de glibc2 definen el
prototipo solamente cuando _XOPEN_SOURCE o _GNU_SOURCE están definidas.
En versiones de libc anteriores a la 5.4.13 los espacios en blanco (y las
especificaciones 'n' y 't') no eran manejados, no se aceptaban los
modificadores de localización 'E' y 'O', y la especificación 'C'
era un sinónimo de la especificación 'c'.
La especificación 'y' (año en el siglo) es considerada un
año en el siglo 20 por libc4 y libc5. En la versión 2.0 de glibc
se considera un año en el rango 1950-2049. Finalmente, en la
versión 2.1 de glibc la especificación 'y' se considera un
año en el rango 1969-2068.
VÉASE TAMBIÉN¶
time(2),
getdate(3),
scanf(3),
setlocale(3),
strftime(3)