1. Обзор

SQLite понимает 7 скалярных функций даты и времени следующим образом:

1. date(time-value, modifier, modifier, ...)
2. time(time-value, modifier, modifier, ...)
3. datetime(time-value, modifier, modifier, ...)
4. julianday(time-value, modifier, modifier, ...)
5. unixepoch(time-value, modifier, modifier, ...)
6. strftime(format, time-value, modifier, modifier, ...)
7. timediff(time-value, time-value)

Первые шесть функций даты и времени берут дополнительное значение времени в качестве аргумента, сопровождаемого нолем или большим количеством модификаторов. strftime() также берет строку формата в качестве своего первого аргумента. timediff() берет точно два аргумента, которые являются оба временными значениями.

Значения даты и времени могут быть сохранены как:

• текст в подмножестве формата ISO-8601
• числа, представляющие Julian day
• числа, представляющие число секунд после (или прежде) 1970-01-01 0:00:00 UTC (метка времени Unix).

Все временные значения функций времени и даты доступны как строки ISO-8601 или как дневные числа Julian. Они также доступны как unix timestamp с дополнительными аргументами ('auto' и 'unixepoch' описаны ниже). Начиная с timediff() функция не принимает дополнительного аргумента, это может использовать только ISO 8601 и дневные временные значения Julian.

date() возвращает дату как текст в этом формате: YYYY-MM-DD.

time() возвращает время как текст в этом формате: HH:MM:SS.

datetime() возвращает дату и время как текст в этом формате: YYYY-MM-DD HH:MM:SS.

julianday() вернет Julian day, фракционное число дней с полудня в Гринвиче 24 ноября, 4714 до н.э. ( Proleptic Gregorian calendar).

unixepoch() возвращает метку времени Unix, число секунд с 1970-01-01 0:00:00 UTC. unixepoch() обычно возвращает целое число секунд, но с дополнительным модификатором subsec это возвратит число с плавающей точкой, которое является фракционным числом секунд.

strftime() возвращает дату, отформатированную согласно строке формата, определенной как первый аргумент. Строка формата поддерживает наиболее распространенные замены, найденные в функции strftime() стандартной библиотеки C и еще две новых замены %f и %J. Следующее это полный список действительных замен strftime():

%d		день месяца: 00-31
%e		день месяца без начального 0: 0-31
%f		доли секунд: SS.SSS
%F		дата в ISO 8601: YYYY-MM-DD
%H		часы: 00-24
%I		часы в формате 12: 01-12
%j		день года: 001-366
%J		Julian day number (fractional)
%k		часы без ведущего 0: 0-24
%l		%I без нуля в начале: 1-12
%m		месяцы: 01-12
%M		минуты: 00-59
%p		"AM" или "PM" в зависимости от часа
%P		"am" или "pm" в зависимости от часа
%R		время по ISO 8601: HH:MM
%s		секунды с 1970-01-01
%S		секунды: 00-59
%T		время по ISO 8601: HH:MM:SS
%u		день недели 1-7, пн.=1
%w		день недели 0-6, вс.=0
%W		неделя в году: 00-53
%Y		год: 0000-9999
%%		%

Другие функции даты и времени могут быть выражены с точки зрения strftime():

Function		Эквивалентная (или ближайшая) strftime()
date(...)		strftime('%F', ...)
time(...)		strftime('%T', ...)
datetime(...)		strftime('%F %T', ...)
julianday(...)		strftime('%J', ...) (вернет число)
unixepoch(...)		strftime('%s', ...) (вернет число)

Функции date(), time() и datetime() вернут текст, таким образом, их эквиваленты strftime() точны. Однако, julianday() и unixepoch() возвращают числовые значения. Их эквиваленты strftime() возвращают последовательность, которая является текстовым представлением соответствующего числа.

Главные причины для обеспечения функций кроме strftime(): для удобства и для эффективности. julianday() и unixepoch() возвращают действительные и целочисленные значения соответственно и не несут расходы преобразования формата или неточность, следующую из использования формата '%J' или '%s' с strftime().

1.1. Timediff()

timediff(A,B) возвращает последовательность, которая описывает количество времени, которое должно быть добавлено к B, чтобы достигнуть времени A. Формат результата timediff() разработан, чтобы быть человекочитаемым. Формат:

(+|-)YYYY-MM-DD HH:MM:SS.SSS

Эта последовательность разницы во времени также позволенный модификатор для других функций даты/времени. Следующий инвариант держится для временных значений A и B:

datetime(A) = datetime(B, timediff(A,B))

Продолжительность месяцев и лет варьируется. Февраль короче, чем март. Високосные годы более длительны, чем невисокосные годы. Вывод timediff() берет это все во внимание. timediff() предназначается, чтобы предоставить человечески-благоприятное описание отрезка времени. Если вы хотите знать число дней или секунд между двумя датами, A и B, то можно всегда сделать:

SELECT julianday(B) - julianday(A);
SELECT unixepoch(B) - unixepoch(A);

timediff(A,B) мог бы возвратить тот же самый результат даже для значений A и B, которые охватывают различное число дней, в зависимости от срока начала работы. Например, оба из следующих двух timediff() возвращают тот же самый результат ("+0000-01-00 00:00:00.000") даже при том, что первый промежуток составляет 28 дней, а второй 31 день:

SELECT timediff('2023-02-15','2023-03-15');
SELECT timediff('2023-03-15','2023-04-15');

Резюме: Если вы хотите человечески-благоприятный отрезок времени, используйте timediff(). Если нужна точная разница во времени (в днях или секундах), используйте различие между двумя julianday() или unixepoch().

2. Значения времени

Значение времени может быть в любом из следующих форматов, показанных ниже. Обчно это последовательность, хотя это может быть целое число или число с плавающей точкой в случае формата 12.

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

В форматах 5-7 "T" это буквенный символ, отделяющий дату и время, как требуется ISO-8601. Форматы 8-10, которые определяют только время, принимают дату от 2000-01-01. Формат 11, последовательность 'now', преобразовывается в текущую дату и время, как получено из метода xCurrentTime объекта sqlite3_vfs. Параметр 'now' всегда возвращает точно то же самое значение для многократных вызовов в том же самом sqlite3_step(). Universal Coordinated Time (UTC) используется. Формат 12 это Julian day number, выраженное как целочисленное значение или значение с плавающей точкой. Формат 12 мог бы также интерпретироваться как метка времени Unix, если он немедленно сопровождается 'auto' или 'unixepoch'.

Форматы 2-10 могут произвольно сопровождаться индикатором часового пояса формы "[+-]HH:MM" или "Z". Функции даты и времени используют UTC или "zulu" время внутренне, и таким образом, суффикс "Z" ничего не делает. Любой ненулевой суффикс "HH:MM" вычтен из обозначенной даты и времени, чтобы вычислить всемирное время. Например, все следующие временные значения эквивалентны:

2013-10-07 08:23:19.120
2013-10-07T08:23:19.120Z
2013-10-07 04:23:19.120-04:00
2456572.84952685

В форматах 4, 7 и 10, у значения долей секунды SS.SSS может быть одна или более цифр после десятичной точки. Точно три цифры показывают в примерах, потому что только первые три цифры значительны для результата, но у входной строки может быть меньше или больше чем три цифры, и функции даты/времени будут все еще работать правильно. Точно так же формат 12 показывают с 10 значительными цифрами, но функции даты/времени действительно примут столько цифр, сколько необходимо, чтобы представлять дневное число Julian.

Во всех функциях кроме timediff() значение времени (и все модификаторы) может быть опущено, в этом случае предполагается временное значение 'now'.

3. Модификаторы

Для всех функций даты/времени кроме timediff() аргумент временного значения может сопровождаться нолем или большим количеством модификаторов, которые изменяют дату и/или время. Каждый модификатор это преобразование, которое применяется к временному значению с ее левой стороны от него. Модификаторы применяются слева направо, порядок важен. Доступные модификаторы следующие:

1. NNN days
2. NNN hours
3. NNN minutes
4. NNN seconds
5. NNN months
6. NNN years
7. ±HH:MM
8. ±HH:MM:SS
9. ±HH:MM:SS.SSS
10. ±YYYY-MM-DD
11. ±YYYY-MM-DD HH:MM
12. ±YYYY-MM-DD HH:MM:SS
13. ±YYYY-MM-DD HH:MM:SS.SSS
14. start of month
15. start of year
16. start of day
17. weekday N
18. unixepoch
19. julianday
20. auto
21. localtime
22. utc
23. subsec
24. subsecond

Первые тринадцать модификаторов (1-13) добавляют указанное количество времени к дате и времени, определенной аргументами ее левой стороны. Символ 's' в конце имен модификатора в 1-6 дополнительный. Значение NNN может быть любым числом с плавающей точкой с дополнительным префиксом '+' или '-'. Обратите внимание на то, что "±NNN months" работает, отдавая оригинальную дату в формате YYYY-MM-DD, добавляя ±NNN к значению месяца MM, затем нормализуя результат. Таким образом, например, дата 2001-03-31, измененная на '+1 month', первоначально 2001-04-31, но в апреле только 30 дней, таким образом, дата нормализована до 2001-05-01. Подобный эффект происходит, когда оригинальная дата имеет 29 февраля високосный год, и модификатор ±N years, где N не кратное четырем число.

Модификаторы изменения времени (7-13) перемещают временное значение на число лет, месяцев, дней, часов, минут и/или секунд. Начальный "+" или "-" требуется для форматов 10-13, но дополнительный для форматов 7, 8 и 9. Изменения применяется слева направо. Сначала год перемещается на YYYY, затем месяц на MM, затем день на DD и т.д. Нормализация и округление из-за отличающихся продолжительностей месяца и високосных годов применяются после каждого шага. Функция timediff(A,B) возвращает изменение времени в формате 13, который перемещает временное значение B в A.

Модификаторы "start of" (14-16) перемещает дату назад к началу месяца, года или дня.

"weekday" продвигает дату вперед, при необходимости, к следующей дате, где день недели N. Воскресенье 0, понедельник 1 и т.д. Если дата уже находится в желаемом дне, "weekday" оставляет дату без изменений.

"unixepoch" (18) работает только если это немедленно следует за временным значением в формате DDDDDDDDDD. Этот модификатор заставляет DDDDDDDDDD интерпретироваться не как дневное число Julian, как это обычно было бы, а как Unix Time, число секунд с 1970. Если "unixepoch" не следует за временным значением формы DDDDDDDDDD, которая выражает число секунд с 1970 или если другие модификаторы отделяют "unixepoch" от предшествующего DDDDDDDDDD, поведение не определено. Для версий SQLite до 3.16.0 (2017-01-02) "unixepoch" работает только для дат между 0000-01-01 00:00:00 и 5352-11-01 10:52:47 (unix times от -62167219200 до 106751991167).

"julianday" должен немедленно следовать за начальным значением времени в формате DDDDDDDDD. Любое другое использование модификатора 'julianday' это ошибка и заставляет функцию возвращать NULL. 'julianday' вынуждает число временного значения интерпретироваться как число юлианского дня. Поскольку это поведение по умолчанию, 'julianday' обычно не используется. Единственная разница в том, что добавление 'julianday' вызывает формат временного значения DDDDDDDDD и заставляет NULL быть возвращенным, если какой-либо другой формат используется.

"auto" должен немедленно следовать за начальным временным значением. Если временное значение числовое (формат DDDDDDDDDD), 'auto' заставляет воспринимать значение как номер дня julian или unix timestamp в зависимости от величины. Если значение от 0.0 до 5373484.499999, это день julian (соответствует датам между -4713-11-24 12:00:00 и 9999-12-31 23:59:59, включительно). Для числовых значений за пределами диапазона действительных юлианских дневных чисел, но в диапазоне от -210866760000 до 253402300799, 'auto' заставляет значение интерпретироваться как метка времени Unix. Другие числовые значения вне диапазона вызывают возвращение NULL. 'auto' ничего не делает для текстовых временных значений.

'auto' может использоваться, чтобы работать с датой/временем даже в случаях, где неизвестно, используются ли юлианское дневное число или форматы метки времени Unix. 'auto' автоматически выберет соответствующий формат. Однако, есть область двусмысленности. Метки времени Unix в течение первых 63 дней 1970 будут интерпретироваться как юлианские дневные числа. 'auto' очень полезен, когда набор данных, как гарантируют, не будет содержать любые даты в том регионе, но не должен применяться для запросов, которые могли бы использовать даты в начале 1970.

"localtime" (21) предполагает, что временное значение с левой стороны от него находится в Universal Coordinated Time (UTC) и регулирует значение так, чтобы это было в localtime. Если "localtime" следует за временем, которое не является UTC, то поведение не определено. Модификатор "UTC" это противоположность "localtime". "utc" предполагает, что временное значение с левой стороны от него находится в местном часовом поясе и регулирует его так, чтобы быть в UTC. Если время слева не в localtime, то результат "UTC" не определен.

"subsecond" (который может быть сокращен как "subsec") увеличивает разрешение вывода datetime(), time(), unixepoch() и формата строки "%s" в strftime(). "subsecond" не имеет никакого эффекта на другие функции даты/времени. Текущая реализация увеличивает резолюцию с секунд к миллисекундам, но это могло бы увеличиться до более высокой резолюции в будущих выпусках SQLite. Когда "subsec" используется с datetime() или time(), поле seconds в конце сопровождается десятичной точкой и одной или более цифрами, чтобы показать доли секунды. Когда "subsec" используется с unixepoch(), результат это значение с плавающей точкой, которое является числом секунд и долей секунды с 1970-01-01.

"subsecond" и "subsec" имеют специальную собственность, что они могут появиться как первый аргумент функциям даты/времени (или как первый аргумент после строки формата для strftime()). Когда это происходит, временное значение, которое обычно находится в первом аргументе, как понимают, "now". Например, короткий путь, чтобы получить текущее время в секундах с 1970 с точностью до миллисекунды:

SELECT unixepoch('subsec');

4. Примеры

Вычислите текущую дату.

SELECT date();

Вычислите последний день текущего месяца.

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

Вычислите дату и время, данные меткой времени Unix 1092941466.

SELECT datetime(1092941466, 'unixepoch');
SELECT datetime(1092941466, 'auto'); -- Does not work for early 1970!

Вычислите дату и время, данные меткой времени Unix 1092941466, и дайте компенсацию на свой местный часовой пояс.

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

Вычислите текущую метку времени Unix.

SELECT unixepoch();
SELECT strftime('%s');

Вычислите число дней начиная с подписания Декларации независимости США.

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

Вычислите число секунд с конкретного момента в 2004:

SELECT unixepoch() - unixepoch('2004-01-01 02:34:56');

Вычислите дату первого вторника в октябре текущего года.

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

Вычислите время с эпохи Unix в секундах с точностью до миллисекунд:

SELECT (julianday('now') - 2440587.5)*86400.0;
SELECT unixepoch('now','subsec');

Вычислите, какого возраста Авраам Линкольн был бы, если бы он был все еще жив сегодня:

SELECT timediff('now','1809-02-12');

5. Ошибки

Вычисление местного времени зависит в большой степени от прихоти политиков и таким образом трудно быть правильным для всех мест действия. В этом внедрении функция стандартной библиотеки C localtime_r() используется, чтобы помочь в вычислении местного времени. localtime_r() обычно работает только в течение лет между 1970 и 2037. Для дат вне этого диапазона SQLite пытается отобразить год в эквивалентный год в этом диапазоне, сделать вычисление, затем отобразить год назад.

Эти функции работают только на датах между 0000-01-01 00:00:00 и 9999-12-31 23:59:59 (номера дней julian от 1721059.5 до 5373484.5). Для дат вне этого диапазона результаты этих функций не определены.

Не-Vista Windows поддерживают только один набор правил DST. Vista поддерживает два. Поэтому на этих платформах, исторические вычисления DST будут неправильными. Например, в США в 2007 изменены правила DST. Платформы Windows не-Vista применяют новое 20:07 правила DST ко всем предыдущим годам также. Vista делает несколько лучшие результаты, когда правила были также изменены.

Все внутренние вычисления принимают систему Григорианского календаря. Они также предполагают, что каждый день точно 86400 секунд длиной, никакие дополнительные секунды не включены.