Работа с Датой и Временем

Конструктор Menu Builder позволяет вам работать в Датой и Временем, используя их в математических Выражениях. Можно добавлять и вычитать время, вычисляя уже прошедшее или оставшееся время "от" или "до" заданного события в будущем или отметки в прошлом. Для этого в конструкторе @MenuBuilderBot добавлен целый набор сущностей, позволяющих работать с Датами и Временем и возможность сохранять отметки времени в переменных. Работа со Временем, в основном, ориентирована на понятие "относительное время", то есть время между некоторыми событиями - что позволит вам отсчитывать время в часах "от" и "до" отметок. Но можно пользоваться и абсолютными значениями времени - выводя конкретные даты.

❖ Используемый формат Даты и Времени

Дата и Время всегда Вводятся и ВЫводятся в фиксированном формате:

DD.MM.YYYY HH:mm:ss

где:
● DD - день
● MM - месяц
● YYYY - год (4 цифры)
● HH - часы
● mm - минуты
● ss - секунды

Например:
● "01.01.2020 00:00:01" - новый 2020 год
● "17.05.2020 19:45:05" - вот более однозначный пример формата выводимого времени.

❖ Переменные Даты и Времени

Для хранения Даты/Времени добавлен специальный тип переменных:

«📕 Время».

Чисто технически, Время можно сохранять и в Текстовых Переменных, но полноценно работать с такими переменными у вас не получится. В Текстовой переменной Время можно только хранить, но не выполнять с ним каких-либо действий.

Синтаксис в сообщениях

В Сообщениях бота - Вывод Даты/Времени осуществляется как обычно - через Макрос той переменной, в которой оно сохранено.

Синтаксис в выражениях

В Выражениях Функций Времени, при использовании переменных хранящих Время - макросы этих переменных ДОЛЖНЫ браться "в кавычки", так как, по сути, они являются текстом.

Синтаксис параметра в функции

Пример записи переменной "date1" в выражениях ФУНКЦИЙ ВРЕМЕНИ: {dt_passed("%date1%")}.

Само выражение, естественно, в {фигурных скобках}.
Подробнее о выражениях - в руководстве по выражениям.

Синтаксис функции

При передаче значения одной функции в другую, даже если значение будет текстом, саму функцию в кавычки брать НЕ НУЖНО (смысл этого пункта вам станет ясен позднее) например:
{dt_passed(dt_now()...)}
В примере функция dt_now() передана в качестве параметра функции dt_passed() - кавычки не нужны. Вы поймёте этот пример, когда ниже причитаете про функции.

Ещё раз: в общем случае, при использовании «Переменных Времени» в Выражениях «Функций Времени» ВСЕГДА берите их макрос "в кавычки"! Иначе ничего не будет работать.

Примеры:
● Сообщение: "Вы нажали кнопку в %date1%".
(Покажет время сохранённое в переменной "date1")
● Выражение: {dt_add("%date1%", 1)}
(Покажет время сохранённое в переменной "date1" плюс 1 час)

❖ Базовые функции для работы с Датой и Временем

ВСЯ(!) реальная работа с датами происходит ТОЛЬКО через специальные Функции (Кроме случаев, когда Дату/Время нужно просто отобразить в сообщении). Базовых Функций всего 3:

dt_now() - Текущее Время

dt_now() Текущее время - функция получения "сейчас", то есть текущей Даты и Времени. Нужна, чтобы можно было от "сейчас" отсчитывать время, сравнивать его и т.д.

Возвращает значение типа "Дата/Время".

Функция имеет практический смысл в Выражениях в комбинации с другими функциями или значениями переменных.

Та же результат данной функции можно использовать, чтобы сохранить в переменную текущее время (например, время в момент нажатия кнопки). В дальнейшем такую запись можно использовать как "отсечку" для расчётов времени, прошедшего с этого момента.

Примеры:
{dt_now()}
Если использовано в Сообщении - выведет текущую дату и время (БЕЗ учёта часового пояса) в момент показа юзеру. Если использовано в Выражении кнопки или в Action-е - то текущая дата (на момент срабатывания) может быть записана в переменную.

Время, показанное при помощи функции {dt_now()}, может НЕ СООТВЕТСТВОВАТЬ  времени показанному при помощи Макросов %date% и %time%, потому как, в отличии от макросов времени, оно НЕ ЗАВИСИТ от установленного в боте часового пояса - это Системное Время.

Не используйте данную функцию для вывода текущего времени в сообщениях (если только ваш часовой пояс не соответствует +3 UTC).

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

dt_add() - Добавить Время

dt_add(date, hours) Добавить время - функция получения даты, отличающейся от "date" на "hours" часов. Другими словами, некая "date" плюс сколько-то "hours".

Возвращает значение типа "Дата/Время".

Функция принимает (требует для работы) два параметра:
● date - та дата, от которой происходит отсчет времени.
Обычно к моменту использования она уже сохранена в какой-либо Переменной Времени (в этом случае используйте макрос той переменной в кавычках), однако это может быть и Текущее Время из функции «dt_now()»).
● hours - это количество часов, на которое нужно изменить дату - часы задаются дробным числом (например, 0.5 часов - это 30 минут и т.д.). Данный параметр может быть не только жестко задан при помощи конкретного числа, но может быть представлен и значением Числовой Переменной - в этом случае используйте макрос этой перемеренной (без кавычек).

Часы могут быть отрицательными (если дату надо уменьшить), в этом случае вычисление времени осуществляется в обратном направлении относительный даты в переменной.

Фактически, это функция добавления времени в часах к некой Дате. Результат покажет новую Дату.

Функция нужна для отображения в сообщении или сохранения в переменной, некоторой точки в будущем (например - окончание "похода в лес" в играх) - вычисленной в данной функции.

Примеры:
{dt_add("%date1%", 1)}
Вычислит дату на 1 час позже чем та, что сохранена в переменной "date1".

Обратите внимание на то, что макрос Переменной Времени "%date1%" - в кавычках, это важно (дата - это текстовая информация)!

Вычислит дату на 1.5 часа позже чем dt_now() "сейчас" (на момент срабатывания выражения).

Например: "Вы ушли, возвращайтесь обратно в {dt_add(dt_now(), 1.5)}". То есть через полтора часа.

Вычислит дату на "var1" часов позже чем та, что сохранена в переменной "date1".

Обратите внимание на то, что макрос Переменной Времени "%date1%" - в кавычках, а макрос Числовой Переменной %var1% - без кавычек!

Добавление стандартных отрезков времени

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

Добавит 1 час.

Для часов, однако можно использовать и следующее выражение {dt_add(dt_now(), 1)}.

добавит 1 день

добавит 1 неделю

добавит 1 месяц (имеется ввиду календарный месяц - вне зависимости от количества дней в месяце)

добавит 1 год

Естественно вместо функции dt_now() можно использовать любую дату или макрос переменной времени содержащую дату.

dt_diff() - Разница Времени

dt_diff(date1, date2) Разница времени - функция получения разницы в часах (дробных) между двумя датами. Вычисляет "date1" минус "date2". Если "date2" будет больше (то есть позже по времени) чем "date1" - результат будет отрицательным числом.

Возвращает дробное число Часов.

Функция нужна для получения информации о том, сколько времени в (дробных) часах прошло между двумя событиями "date1" и "date2".

Примеры:
{dt_diff(dt_now(), "%date1%")}
Допустим ранее вы сохранили Дату/Время в переменной "date1". Данный пример вычислит (разницу), сколько часов прошло со времени сохраненного в переменной "date1" (то есть от какого-то события в прошлом) до теперешнего момента из функции «dt_now()».

Обратите внимание на то, что макрос Переменной Времени "%date1%" - в кавычках, это важно!

Дополнительные НЕобязательные параметры:

Тип результата: "s", "m", "h", "d" (секунда, минута, час, день). По умолчанию - час.
Округление: "n", "u", "d" (не округлять, округлять вверх, округлять вниз). По умолчанию - не округлять.
{dt_diff("%date%", dt_now(), "s")} - результат в секундах.
{dt_diff("%date%", dt_now(), "d")} - результат в днях (дробных).
{dt_diff("%dater%", dt_now(), "d", "u")} - результат в днях (целых, округленных вверх).

● Пример сообщения:
"С вашего ухода прошло {dt_diff(dt_now(), "%date1%")} часов."

● Или поинтереснее:
"За прошедшие {dt_diff(dt_now(), "%date1%")} часа вы заработали {dt_diff(dt_now(), "%date1%") * 10} монет."
При условии что юзер получает 10 монет в час.

❖ Сравнение Даты и Времени

Функции Времени, а так же Переменные содержащие данные о Дате и Времени могут служить Условием для выполнения тех или иных действий в Кнопках и Action-ах. Для этого Время можно сравнивать в Условиях этих кнопок и Action-ов.

Даты и Время сравниваются обычными операторами сравнения:
● >, >= (Больше, Больше или равно)
● <, <= (Меньше, Меньше или равно)
и другими.

Технически можно сравнивать даты на "равно/не равно" (==, !=), но практического смысла в этом - нет: маловероятно что даты совпадут с точностью до миллисекунд.

Пример 1:
Некую Дату нужно сравнить с Настоящим (со временем "сейчас").
{dt_left("%date1%") == 0}
Время оствшееся до даты равно 0 (нулю). Дата уже прошла.

Функция dt_left() вернёт оставшееся до %date1% время в часах (смотри ниже).

Пример 2:
У вас две Даты "не сейчас".
{dt_diff(%date1%, %date2%) <=0}
Ипользуйте >=, в зависимости от того какая дата должна быть больше.

Функция dt_diff() вернёт разницу между %date1% и %date2% в часах (смотри выше).

Как НЕ НАДО сравнивавть Даты:
{"%date1%" < dt_now()}
В данном примере происходит сравнение Строк и результат может быть непредстказуемым, несмотря на то, что выражение может казаться верным и даже верно работать в ряде случаев.

❖ Типы результатов Выражений

При записи в переменные результатов работы функций Даты/Времени (когда они сохраняются в переменную через кнопки типа «Бонус», «Обмен», или через «Action-ы»), важно понимать и учитывать то, какого ТИПА результат возвращает та или иная функция Времени. От этого будет зависеть способ записи данных и соответственно то что останется записанным в переменной в конечном итоге.

Результаты бывают двух Типов:
● Тип - Дата/Время. Если выражение возвращает "Дату" - то дата будет ПРИСВОЕНА переменной. Всегда присвоена: то есть старая дата будет затёрта новой.
● Тип - Число: Если выражение возвращает "Число" - то значение будет ДОБАВЛЕНО (или вычтено, если отрицательное) к Дате в переменной. Работа по принципу функции «dt_add()». 

Какой тип результата возвращает та или иная функция, смотрите выше - в описании самих функций.

❖ Дополнительные Функции

Дополнительные функции предоставляют возможности, которые в принципе можно "собрать" и из «Базовых Функций» - осуществив все вычисления самостоятельно. Однако использование «Дополнительных Функций» для "типовых сценариев", позволяет сократить визуальную сложность Выражений и упростить вам работу.

Набор дополнительных функций, вероятнее всего, будет расширятся по мере выявления новых "типовых", активно используемых сценариев (другими словами - по вашим просьбам).

dt_left()

функция, которая возвращает, сколько В ЧАСАХ осталось до указанной даты (date). Если относительно текущего момента дата уже прошла - функция вернет 0 (ноль).

Функция вернет дробное, десятичное количество часов (1.2, 5.7, 34.4). Больше предназначено для удобства вычислений в Выражениях.

Дополнительные НЕобязательные параметры:

Тип результата: "s", "m", "h", "d" (секунда, минута, час, день). По умолчанию - час.
Округление: "n", "u", "d" (не округлять, округлять вверх, округлять вниз). По умолчанию - не округлять.
{dt_left("%datevar%", "s")} - результат в секундах.
{dt_left("%datevar%", "d")} - результат в днях (дробных).
{dt_left("%datevar%", "d", "u")} - результат в днях (целых, округленных вверх).

Если нужно показать сколько осталось Дней, Часов и Минут до события:
{floor(dt_left("%date%", "d"))} дней
{floor(mod(dt_left("%date%", "h"), 24))} часов
{floor(mod(dt_left("%date%", "m"), 60))} минут
Где %date% это некая переменная содержащая данные о некой дате в будущем.
(покажет условно: 365 дней 23 часов 59 минут)

dt_left_hm()

функция, которая возвращает строку в HH:MM, сколько осталось В ЧАСАХ и МИНУТАХ до указанной даты (date). Если относительно текущего момента дата уже прошла - функция вернет 00:00.

Функция вернет привычное и удобное для понимания человеком количество часов и минут (1:12, 7:42, 36:24). Предназначено для упрощения понимания юзером и удобства вывода значений в Сообщениях.

Дополнительные НЕобязательные параметры:

Форматирование полученных результатов:
{dt_left_hm("31.12.2021 23:59:59", "-")} - собственный разделитель (покажет условно: 170-59)
{dt_left_hm("31.12.2021 23:59:59", " | ", " часов", " минут")} - собственный разделитель и суффиксы для Часов и Минут (покажет условно: 170 часов | 59 минут)

dt_passed()

функция, которая возвращает, сколько прошло В ЧАСАХ с указанной даты (date). Если относительно текущего момента дата ещё не подошла - функция вернет 0 (ноль).

Функция вернет дробное, десятичное количество часов (1.2, 5.7, 34.4). Больше предназначено для удобства вычислений в Выражениях.

Дополнительные НЕобязательные параметры:

Тип результата: "s", "m", "h", "d" (секунда, минута, час, день). По умолчанию - час.
Округление: "n", "u", "d" (не округлять, округлять вверх, округлять вниз). По умолчанию - не округлять.
{dt_passed("%datevar%", "s")} - результат в секундах.
{dt_passed("%datevar%", "d")} - результат в днях (дробных).
{dt_passed("%datevar%", "d", "u")} - результат в днях (целых, округленных вверх).

dt_passed_hm()

функция, которая возвращает строку в HH:MM сколько прошло В ЧАСАХ И МИНУТАХ с указанной даты (date). Если относительно текущего момента дата ещё не подошла - функция вернет 00:00.

Функция вернет привычное и удобное для понимания человеком количество часов и минут (1:12, 7:42, 36:24). Предназначено для упрощения понимания юзером и удобства вывода значений в Сообщениях.

Дополнительные НЕобязательные параметры:

Форматирование полученных результатов:
{dt_passed_hm("31.12.2021 23:59:59", "-")} - собственный разделитель (покажет условно: 170-59)
{dt_passed_hm("31.12.2021 23:59:59", " | ", " часов", " минут")} - собственный разделитель и суффиксы для Часов и Минут (покажет условно: 170 часов | 59 минут)

dt_passedm()

функция, которая возвращает, сколько прошло В ЧАСАХ с указанной даты (date), но не больше (max) часов. Если относительно текущего момента дата ещё не подошла - функция вернет 0 (ноль). Если относительно (data) прошло больше (max) часов - функция вернет (max).

Функция вернет дробное, десятичное количество часов (1.2, 5.7, 34.4). Больше предназначено для удобства вычислений в Выражениях.

dt_passedm_hm()

функция, которая возвращает строку в HH:MM сколько прошло В ЧАСАХ И МИНУТАХ с указанной даты, но не больше (max) часов. Если относительно текущего момента дата ещё не подошла - функция вернет 00:00. Если относительно (data) прошло больше (max) часов - функция вернет (max) в формате HH:MM.

Функция вернет привычное и удобное для понимания человеком количество часов и минут (1:12, 7:42, 36:24). Предназначено для упрощения понимания юзером и удобства вывода значений в Сообщениях.

Дополнительные НЕобязательные параметры:

Форматирование полученных результатов:
{dt_passedm_hm("31.12.2021 23:59:59", "-")} - собственный разделитель (покажет условно: 170-59)
{dt_passedm_hm("31.12.2021 23:59:59", " | ", " часов", " минут")} - собственный разделитель и суффиксы для Часов и Минут (покажет условно: 170 часов | 59 минут)

dt_nextday()

dt_nextday(date)
Функция которая получив дату возвращает дату начала следующего ДНЯ.
Пример указания даты и времени:
dt_nextday("%date% %time%") - при помощи макросов даты и времени
dt_nextday(dt_now()) - при помощи функции "сейчас"
dt_nextday(dt_now_tz()) - при помощи функции "сейчас с учётом часового пояса бота"
Например: получив 01.01.2022 22:22:22 вернет 02.01.2022 00:00:00.

dt_nextmonth()

dt_nextmonth(date)
Функция которая получив дату возвращает дату начала следующего МЕСЯЦА.
Пример указания даты и времени:
dt_nextmonth("%date% %time%") - при помощи макросов даты и времени
dt_nextmonth(dt_now()) - при помощи функции "сейчас"
dt_nextmonth(dt_now_tz()) - при помощи функции "сейчас с учётом часового пояса бота"
Например: получив 22.01.2022 22:22:22 вернет 01.02.2022 00:00:00.

dt_now_tz()

dt_now_tz()
Функция - аналог dt_now(), но формирует время "сейчас", с учетом настроенного в боте часового пояса (_tz - Time Zone). 

Используйте данную функцию только для отображения времени и тому подобных вещей. Не рекомендуем использовать время локальных Часовых Поясов для хранения или учёта каких либо данных. С функциями типа: dt_left(), dt_passed() - данная функция может работать НЕПРАВИЛЬНО. 

dt_format()

dt_format(date, "$a $b $c $d $e")

Где: $a, $b, $c, $d, $e это любое из значений:
● $Y - год (4 цифры)
● $m - месяц
● $d - день
● $H - час
● $M - минута
● $S - секунда

Функция позволяет вам форматировать вывод даты любым необходимым вам образом. Внутри "кавычек" можно использовать любые текстовые символы (кроме самих "" кавычек разумеется).

Например:
{dt_format(dt_now(), "$Y.$m.$d - $H:$M:$S")} - 2024.12.31 - 00:59:59
{dt_format(dt_now(), "$d.$m ($Y)")} - 31.12 (2024)

❖ Дополнительная Информация

Дату и Время можно записывать в Переменные

О том что такое переменные и как с ними работать.

• • •

Функции и Переменные с Дата/Время можно использовать в Выражениях

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

• • •

Функции и Переменные с Дата/Время можно использовать в Условиях

О том как применять Условия, читай в руководстве по Условиям.

• • •

Дату и Время можно использовать в Action-ах

Подробнее о том что такое Action-ы, чем они удобны и как ими пользоваться смотрите в отдельном Руководстве по Action-ам.