Справочник языка

Дата и время

Раздел «Дата и время» описывает типы DATE, TIME и DATETIME, чтение часов, календарные компоненты, арифметику, разбор строк и часовые пояса.

Значения и запись

DATE хранит календарную дату с годом от 1 до 9999. TIME хранит время суток без календарной даты. DATETIME хранит дату и время суток без собственного часового пояса.

Внутреннее значение TIME и DATETIME хранит доли секунды с точностью до одного тика (100 нс). При печати, соединении через & и записи в STRING используется краткая форма yyyy-MM-dd, HH:mm:ss и yyyy-MM-dd HH:mm:ss. Если дробная часть не равна нулю, к ней добавляется точка и от одной до семи цифр без конечных нулей: например 2024-02-29 12:34:56.125. Запись обратима: текст, полученный из значения, читается обратно в равное значение, поэтому сохранение даты-времени в текстовый файл не меняет её.

Значения с точностью до секунды всегда печатаются кратко и не получают точку. Два значения с разными долями секунды остаются разными при сравнении, сортировке и поиске, даже если их краткая часть совпадает.

Функции текущего времени имеют собственное разрешение. TIME, NOW, UTCTIME, UTCNOW и формы с часовым поясом возвращают значение с точностью до секунды: доли секунды системных часов отбрасываются при чтении. DATE и UTCDATE отбрасывают и время суток. TIMER остаётся дробным и предназначен для измерения прошедшего времени.

Четвёртый временной тип — UTCDATETIME — хранит момент времени: однозначную точку на шкале UTC. Он не является календарной записью и не хранит часовой пояс. Момент печатается с разделителем T и признаком Z, например 2024-02-29T12:34:56Z, и его нельзя спутать с календарной записью DATETIME. Перевод между видами выполняют явные функции TOINSTANT и FROMINSTANT, потому что для него нужен часовой пояс. Два разных момента, дающих одинаковую местную запись при переходе часов, остаются разными значениями.

Начальные значения неинициализированных переменных — 0001-01-01, 00:00:00, 0001-01-01 00:00:00 и 0001-01-01T00:00:00Z. Строковая запись остаётся STRING, пока не выполнено допустимое преобразование.

Преобразование и арифметика

Каноническая строка может преобразоваться во временной тип при присваивании. DATE при преобразовании в DATETIME дополняется полуночью; TIME — минимальной календарной датой.

Обратное сужение запрещено везде, где оно было бы неявным. Значение DATETIME нельзя присвоить переменной DATE или TIME, вернуть из функции с типом DATE или TIME, передать в такой параметр, положить в поле TYPE или элемент массива. Строка с полным текстом yyyy-MM-dd HH:mm:ss подчиняется тому же запрету, даже если она записана в скобках или хранится в переменной STRING. Ограничение действует одинаково для DIM, повторного присваивания, CONST, аргумента процедуры, RETURN и сравнения.

Отбросить ненужный компонент можно только явно. DATEVALUE возвращает дату из полного текста или из DATETIME, TIMEVALUE — время суток. Функции YEAR, MONTH, DAY, WEEKDAY, HOUR, MINUTE, SECOND, STARTOFMONTH, ENDOFMONTH, STARTOFYEAR и ENDOFYEAR принимают DATETIME напрямую, потому что чтение одной части и есть их назначение. Расширение DATE или TIME до DATETIME остаётся допустимым.

Собрать DATETIME из готовых частей можно функцией DATETIMESERIAL: она принимает DATE и TIME и переносит обе части целиком, включая доли секунды. Этот путь не требует промежуточного текста, поэтому сборка и разбор образуют обратимую пару: DATETIMESERIAL(DATEVALUE(moment), TIMEVALUE(moment)) возвращает исходное значение.

Диагностика различает два случая. Если полный текст виден компилятору, отказ приходит при проверке программы как MB2003. Если содержимое строки известно только во время выполнения, отказ приходит как MB3005 и перехватывается TRY/CATCH; переменная-цель сохраняет прежнее значение.

DATEADD, DATEDIFF и DATEPART принимают только типизированные временные аргументы, без строкового преобразования. Для строки сначала используют DATEVALUE или TIMEVALUE; для DATETIME можно объявить переменную с канонической строковой инициализацией. Часовой пояс задаётся отдельным строковым аргументом соответствующих функций.

Пример типизированной даты

DIM calendarDay AS DATE = "2024-01-31"
PRINT DATEADD("m", 1, calendarDay)

Ожидаемый вывод:

2024-02-29

Полное значение DATETIME не сужается неявно. Ниже показано, как получить дату и время осознанно:

DIM moment AS DATETIME = "2026-04-20 14:05:06"
PRINT DATEVALUE("2026-04-20 14:05:06")
PRINT TIMEVALUE("2026-04-20 14:05:06")
PRINT YEAR(moment)
PRINT HOUR(moment)

Ожидаемый вывод:

Темы раздела

Текущие дата и время — чтение часов и TIMER.
Календарные компоненты — сборка даты, имена месяцев, високосность и границы периодов.
Арифметика и разбор — смещение, подсчёт границ и проверка строк.
Часовые пояса — смещение в минутах и перевод между местным временем и UTC.

Значения при отладке

Отладчик сохраняет DATE, TIME, DATETIME и UTCDATETIME в снимках переменных, аргументов, полей и промежуточных вычислений. Обратный шаг восстанавливает значение с полной точностью, включая доли секунды. Чистые преобразования и вычисление интервала между заданными моментами допускают повторное выполнение; чтение текущих часов и файловых метаданных ограничивает историю.