Справочник языка
Календарная арифметика и разбор
Со временем выполняют два рода действий: сдвигают его на интервал и измеряют расстояние между двумя значениями, а кроме того, читают временные данные из текста и проверяют их перед преобразованием. Сдвиг и подсчёт границ выполняют DATEADD, DATEDIFF и DATEPART; они принимают только типизированные значения. Разбор строк и их проверку берут на себя DATEVALUE, TIMEVALUE, DATETIMEVALUE и ISDATE.
DATEADD
DATEADD возвращает дату или время после прибавления указанного числа интервалов. Функция нужна для вычисления срока или времени после заданного сдвига; вызывать её можно в выражении консольной или графической программы, оператор SCREEN или CANVAS не требуется.
Синтаксис
DATEADD(<интервал>, <количество>, <дата DATE>)DATEADD(<интервал>, <количество>, <время TIME>)DATEADD(<интервал>, <количество>, <дата и время DATETIME>)Аргументы
Строка интервала регистронезависима: yyyy — год, q — квартал, m — месяц, d — день, h — час, n — минута, s — секунда. Пробелы вокруг обозначения не удаляются. Количество должно иметь тип INTEGER; отрицательное количество вычитает интервалы. Последний аргумент должен иметь ровно указанный временной тип; STRING не принимается.
Результат
Тип результата совпадает с типом последнего аргумента.
Правила и ограничения
DATE допускает yyyy, q, m, d; TIME — h, n, s; DATETIME — все семь. Для месяца и года день ограничивается последним днём итогового месяца. TIME циклически переходит через полночь, DATETIME изменяет и календарную дату. Количество 0 сохраняет значение.
Диагностика
Компилятор отклоняет неверное количество аргументов и несовместимый тип аргумента. MB3007 возникает при неверном интервале, несовместимом временном виде или выходе календарной даты за годы 1–9999.
Пример
DIM d AS DATE = "2024-01-31"
DIM t AS TIME = "23:59:59"
PRINT DATEADD("m", 1, d)
PRINT DATEADD("s", 1, t)Ожидаемый вывод:
2024-02-29
00:00:00См. также
DATEDIFF
Функция DATEDIFF возвращает число пересечённых границ указанного интервала между двумя значениями, то есть подсчитывает переходы между календарными или временными периодами. Вызов допустим в выражении консольной и графической программы; оператор SCREEN или CANVAS не нужен.
Синтаксис
DATEDIFF(<интервал>, <начало DATE>, <конец DATE>)DATEDIFF(<интервал>, <начало TIME>, <конец TIME>)DATEDIFF(<интервал>, <начало DATETIME>, <конец DATETIME>)Аргументы
Строка интервала регистронезависима: yyyy — год, q — квартал, m — месяц, d — день, h — час, n — минута, s — секунда. Пробелы вокруг обозначения не удаляются. Начало и конец должны иметь один и тот же тип DATE, TIME или DATETIME; передача STRING и смешение видов запрещены.
Результат
Результат LONG: индекс периода конца минус индекс периода начала.
Правила и ограничения
DATE допускает yyyy, q, m, d; TIME — h, n, s; DATETIME — все семь. Это число границ, а не число полных прошедших интервалов. При обратном порядке результат отрицателен. TIME сравнивается внутри одних суток без предположения о следующем дне.
Диагностика
Компилятор отклоняет неверное количество аргументов и несовместимый тип аргумента. MB3007 возникает при неизвестном интервале или несовместимости интервала с видом значений.
Пример
DIM a AS DATETIME = "2024-12-31 23:59:59"
DIM b AS DATETIME = "2025-01-01 00:00:00"
PRINT DATEDIFF("yyyy", a, b)
PRINT DATEDIFF("h", a, b)
PRINT DATEDIFF("s", b, a)Ожидаемый вывод:
1
1
-1См. также
DATEPART
Вызов DATEPART возвращает выбранную календарную или временную часть значения: нужный компонент задаётся строковым обозначением. Функция работает в выражениях консольных и графических программ, оператор SCREEN или CANVAS не требуется.
Синтаксис
DATEPART(<часть>, <дата DATE>)DATEPART(<часть>, <время TIME>)DATEPART(<часть>, <дата и время DATETIME>)Аргументы
Часть должна быть STRING: yyyy — год, q — квартал, m — месяц, d — день месяца, y — день года, w — день недели, h — час, n — минута, s — секунда. Значение имеет ровно тип DATE, TIME или DATETIME.
Результат
Результат INTEGER: год 1–9999, квартал 1–4, месяц 1–12, день месяца 1–31, день года 1–366, день недели 1–7, час 0–23, минута и секунда 0–59.
Правила и ограничения
Обозначения регистронезависимы, пробелы не удаляются. DATE допускает календарные части, TIME — временные, DATETIME — обе группы. Понедельник имеет номер 1.
Диагностика
Компилятор отклоняет неверное количество аргументов и несовместимый тип аргумента. MB3007 возникает при неизвестной части или части, отсутствующей у указанного временного вида.
Пример
DIM d AS DATE = "2024-02-29"
PRINT DATEPART("y", d)
PRINT DATEPART("w", d)Ожидаемый вывод:
60
4См. также
DATEVALUE
DATEVALUE возвращает календарную дату, прочитанную из строки. Функция нужна для явного извлечения нужной части текстовой записи; вызывается она в выражениях консольных и графических программ, оператор SCREEN или CANVAS не требуется.
Синтаксис
DATEVALUE(<текст>)DATEVALUE(<значение>)Аргументы
Передайте STRING в точной форме yyyy-MM-dd или yyyy-MM-dd HH:mm:ss. Допускается дробная часть после секунд: точка и от одной до семи цифр, например yyyy-MM-dd HH:mm:ss.125. Вторая форма принимает также значение DATETIME: это типизированный путь получить DATE без текста и без неявного преобразования. Результат — календарная дата, поэтому время суток и его доли в результат не входят.
Результат
Функция возвращает значение типа DATE.
Правила и ограничения
Полная запись даты-времени допустима, лишняя часть отбрасывается. Это единственный способ получить DATE из текста с временем суток: неявное присваивание такого текста переменной DATE отклоняется диагностикой. Пустая строка, пробелы на краях, невозможная дата и другая форма записи недопустимы.
Диагностика
Компилятор отклоняет неверное количество аргументов и несовместимый тип аргумента. MB3007 возникает при недопустимой строке, номере или календарной дате.
Пример
PRINT DATEVALUE("2024-02-29 12:34:56")Ожидаемый вывод:
2024-02-29См. также
TIMEVALUE
Функция TIMEVALUE возвращает время суток, прочитанное из строки, и служит для явного извлечения нужной части текстовой записи. Вызов допустим в выражении консольной и графической программы — оператор SCREEN или CANVAS не нужен.
Синтаксис
TIMEVALUE(<текст>)TIMEVALUE(<значение>)Аргументы
Передайте STRING в точной форме HH:mm:ss или yyyy-MM-dd HH:mm:ss. Допускается дробная часть после секунд: точка и от одной до семи цифр, например 14:05:06.125. Вторая форма принимает также значение DATETIME: это типизированный путь получить TIME без текста и без неявного преобразования. Результат сохраняет доли секунды, а календарная дата в результат не входит.
Результат
Функция возвращает значение типа TIME.
Правила и ограничения
Полная запись даты-времени допустима, лишняя часть отбрасывается. Это единственный способ получить TIME из текста с календарной датой: неявное присваивание такого текста переменной TIME отклоняется диагностикой. Пустая строка, пробелы на краях, невозможная дата и другая форма записи недопустимы.
Диагностика
Компилятор отклоняет неверное количество аргументов и несовместимый тип аргумента. MB3007 возникает при недопустимой строке, номере или календарной дате.
Пример
PRINT TIMEVALUE("2024-02-29 12:34:56")Ожидаемый вывод:
12:34:56См. также
DATETIMEVALUE
DATETIMEVALUE возвращает дату и время, прочитанные из строки в канонической записи или в формате обмена. Функция нужна для явного разбора текста, пришедшего из файла, сети или другого источника: каноническая запись с пробелом и запись с разделителем T читаются одной функцией, а неявное преобразование остаётся строгим. Вызывается она в выражениях консольных и графических программ; оператор SCREEN или CANVAS не требуется.
Синтаксис
DATETIMEVALUE(<текст>)Аргументы
Передайте STRING. Принимается запись yyyy-MM-dd HH:mm:ss и запись yyyy-MM-ddTHH:mm:ss. В обеих формах допускается дробная часть секунд: точка и от одной до семи цифр. Смещение вида +03:00 и суффикс Z не принимаются.
Результат
Функция возвращает значение типа DATETIME без часового пояса. Доли секунды сохраняются.
Правила и ограничения
Разделитель T принадлежит формату обмена, а не канонической записи Axiom. Поэтому результат печатается с пробелом, а неявное присваивание строки с T переменной DATETIME отклоняется: такой текст нужно разобрать этой функцией. Смещение и Z не отбрасываются молча, потому что DATETIME не хранит часовой пояс и потеря смещения изменила бы смысл момента; для однозначного момента нужен отдельный тип. Пустая строка, невозможная дата и другая форма записи недопустимы.
Диагностика
Компилятор отклоняет неверное количество аргументов и несовместимый тип аргумента. MB3007 возникает при недопустимой строке, смещении, суффиксе Z или невозможной календарной дате.
Пример
PRINT DATETIMEVALUE("2024-02-29T12:34:56.125")
PRINT DATETIMEVALUE("2024-02-29 12:34:56")Ожидаемый вывод:
2024-02-29 12:34:56.125
2024-02-29 12:34:56См. также
ISDATE
ISDATE возвращает признак допустимости канонической строки даты, времени или даты-времени. Функция позволяет проверить текст перед его преобразованием во временной тип. Вызывается она в выражениях консольных и графических программ; оператор SCREEN или CANVAS не требуется.
Синтаксис
ISDATE(<текст>)Аргументы
Передайте STRING; проверяется вся строка.
Результат
Результат BOOLEAN: TRUE для допустимой формы yyyy-MM-dd, HH:mm:ss или yyyy-MM-dd HH:mm:ss; иначе FALSE. После секунд допускается дробная часть: точка и от одной до семи цифр, например 12:34:56.125. Точка без цифр и нецифровой символ после точки дают FALSE.
Правила и ограничения
Пустая строка, невозможная дата и пробелы вокруг записи дают FALSE. TRUE для строки времени не означает, что эту строку примет DATEVALUE. Запись с дробной частью принимают TIMEVALUE и переменные TIME или DATETIME; DATEVALUE по-прежнему извлекает только календарную дату.
Диагностика
Компилятор отклоняет неверное количество аргументов и несовместимый тип аргумента. Некорректное содержимое не вызывает ошибки выполнения.
Пример
PRINT ISDATE("2024-02-29")
PRINT ISDATE("23:59:59")
PRINT ISDATE("2023-02-29")
PRINT ISDATE("")Ожидаемый вывод:
TRUE
TRUE
FALSE
FALSE