strftime

Función de fecha y hora

strftime(format, timestring, modifier, modifier, ...) 

La función strftime toma como primer argumento una cadena de formato, seguido de una cadena de tiempo. A su vez esta cadena está seguida por cero o más modificadores.

Las funciones de fecha y hora usan un subconjunto de los formatos de fecha y hora ISO-8601. La función strftime() devuelve la fecha formateada de acuerdo con la cadena de formato especifiada como primer argumento. La cadena de formato soporta las sustituciones más comunes encontradas en la función strftime() de la librería C estándar más dos nuevas sustituciones, %f y %J. A continuación una lista completa de las sustituciones válidas para strftime():

%d día del mes: 00

%f segundos con fracciones: SS.SSS

%H hora: 00-24

%j día del año: 001-366

%J número de día Juliano

%m mes: 01-12

%M minuto: 00-59

%s segundos desde 1970-01-01

%S segundos: 00-59

%w día de la semana 0-6 con Domingo==0

%W semana del año: 00-53

%Y año: 0000-9999

%% %

Nótese que todas las otras funciones de fecha y hora pueden ser expresadas en términos de strftime():

El único motivo para proporcionar funciones distintas de strftime() es por conveniencia y por eficiencia.

Cadenas de tiempo

Una cadena de tiempo puede tener cualquiera de los siguientes formatos:

1. YYYY-MM-DD
2. YYYY-MM-DD HH:MM
3. YYYY-MM-DD HH:MM:SS
4. YYYY-MM-DD HH:MM:SS.SSS
5. YYYY-MM-DDTHH:MM
6. YYYY-MM-DDTHH:MM:SS
7. YYYY-MM-DDTHH:MM:SS.SSS
8. HH:MM
9. HH:MM:SS
10. HH:MM:SS.SSS
11. now
12. DDDDDDDDDD

En los formatos 5 a 7, la "T" es un carácter literal separador entre la fecha y la hora, tal como se requiere por ISO-8601. Los formatos 8 a 10 que especifican sólo una hora asumen una fecha de 2000-01-01. En el formato 11, la cadena 'now', se convierte a la fecha y hora actual como se obtiene desde el método xCurrentTime del objeto sqlite3_vfs en uso. Se usa el tiempo coordinado universal (UTC). El formato 12 es el número del día Juliano expresado como un valor en coma flotante.

Modificadores

La cadena de tiempo puede estar seguida por cero o más modificadores que alteran la fecha y/o la hora. Cada modificador es una transformación que se aplica al valor de tiempo a su izquierda. Los modificadores se aplican de izquierda a derecha; el orden es importante. Los modificadores disponibles son los siguientes:

1. NNN days
2. NNN hours
3. NNN minutes
4. NNN.NNNN seconds
5. NNN months
6. NNN years
7. start of month
8. start of year
9. start of day
10. weekday N
11. unixepoch
12. localtime
13. utc

Los seis primeros modificadores (1 al 6) simplemente añaden la cantidad de tiempo especificado a la fecha y hora especifiada por la cadena de tiempo y modificadores precedentes. Tener en cuenta que "±NNN meses" funciona convirtiendo la fecha originar al formato YYYY-MM-DD, añadiendo ±NNN al valor de MM, y entonces normalizando el resultado. Así, por ejemplo, la fecha 2001-03-31 modificada por '+1 month' inicialmente produce 2001-04-31, pero Abril sólo tiene 30 días así que la fecha se normaliza a 2001-05-01. Un efecto similar ocurre cuando la fecha originarl es 29 de Febero de un año bisiesto y el modificador es ±N years donde N no es un múltiplo de cuatro.

Los modificadores "start of" (7 a 9) desplazan la fecha hacia atrás al principio del mes, año o día actual.

El modificador "weekday" avanza la fecha hacia adelante a la siguiente fecha donde el día de la semana es N. El Domingo es 0, Lunes es 1 y sucesivamente.

El modificador "unixepoch" (11) sólo funciona si sigue inmediatamente a una cadena de tiempo en el formato DDDDDDDDDD. Este modificador hace que DDDDDDDDDD se interprete no como un número de día Juliano, como se haría normalmente, sino como un tiempo Unix - el número de segundos desde 1970. Si el modificador "unixepoch" no sigue a una cadena de tiempo en formato DDDDDDDDDD qie exprese el número de segundos desde 1970 o si otros modificadores separan el modificador "unixepoch" del DDDDDDDDDD anterior, entonces el comportamiento queda indefinido. Debido a las limitaciones impuestas por las implementaciones que usan enteros de 64 bits, el modificador "unixepoch" sólo funciona con fechas entre 0000-01-01 00:00:00 y 5352-11-01 10:52:47 (tiempo unix de -62167219200 a 10675199167).

El modificador "localtime" (12) asume que la cadena de tiempo a su izquierda estña en Tiempo Coordinado Universal (UTC) y ajusta la cadena de tiempo de modo que muestre la hora local. Si "localtime" sigue a un tiempo que no es UTC, entonces el comportamiento es indefinido. El "utc" es lo contrario a "localtime". "utc" asume que la cadena a su izquierda está en la zona de tiempo local y ajusta esa cadena para que esté en UTC. Si la cadena anterior no está en tiempo local, el resultado de "utc" es indefinido.

Ejemplos

Calcular la fecha actual.

    SELECT date('now');

Calcular el último día del mes actual.

    SELECT date('now','start of month','+1 month','-1 day');

Calcular la fecha y hora dada una fechay hora unix 1092941466.

    SELECT datetime(1092941466, 'unixepoch');

Calcular la fecha y hora dada una fecha y hora unix 1092941466, y compensar para la zona de tiempo local.

    SELECT datetime(1092941466, 'unixepoch', 'localtime');

Calcular la fecha y hora unix actual.

    SELECT strftime('%s','now');

Calcular el número de días desde la firma de la declaración de independencia de USA.

    SELECT julianday('now') - julianday('1776-07-04');

Calcular el número de segundos desde un momento particular de 2004:

    SELECT strftime('%s','now') - strftime('%s','2004-01-01 02:34:56');

Calcular la fecha del primer Martes de Octuble del año actual.

    SELECT date('now','start of year','+9 months','weekday 2');

Calcular la hora desde la época unix en segundos (como strftime('%s','now') excepto que se incluye la parte fraccionaria):

    SELECT (julianday('now') - 2440587.5)*86400.0;

Advertencias y errores

El cálculo del tiempo local depende en gran medida del capricho de los políticos y por lo tanto es difícil conseguir el correcto para todas las localizaciones. En esta implementación, se usa la función localtime_r() de la librería C estándar para ayudar en los cálculos de la hora local. La función C localtime_r() normalmente sólo funciona con años entre 1970 y 2037. Para fechas fuera de este rango, SQLite intenta mapear el año a uno equivalente dentro de ese rango, hace los cálculos, y vuelve a mapearlo al original.

Estas funciones trabajan con fechas entre 0000-01-01 00:00:00 y 9999-12-31 23:59:59 (números de días julianos entre 1721059.5 y 5373484.5). Para fechas fuera de ese rango, los resultados de estas funciones son indefinidos.

Las platafornas de Window que no sean Vista sólo soportan uno de los conjuntos de reglas DST. Vista sólo soporte dos. Por lo tanto, en esas plataformas, los cálculos históricos de DST serán incorrectos. Por ejemplo, in los Estados Unidos, en 2007 las reglas DST cambiaron. Las plataformas Window no Vista aplcian las nuevas reglas DST 2007 a todos los años anteriores también. Vista es algo mejor al obtener datos correctos hasta 1986 hacia atrás, cuando las reglas también fueron cambiadas.

Todos los cálculos internos asumen el sistema de calendario Gregoriano. También se asume qie todos los días tienen exactamente 86400 segundos de duración.