Работа с Датой и Временем
❖ Используемый формат Даты и Времени
Дата и Время всегда Вводятся и ВЫводятся в фиксированном формате:
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). Больше предназначено для удобства вычислений в Выражениях.
Функция нужна например для показа роста чего-либо в играх: фрукты растут, но не больше 24 часов. Потом рост "останавливается".
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", 180, "-")} - собственный разделитель (покажет условно: 170-59){dt_passedm_hm("31.12.2021 23:59:59", 180, " | ", " часов", " минут")} - собственный разделитель и суффиксы для Часов и Минут (покажет условно: 170 часов | 59 минут)
Если нужно показать секунды:{mod(floor(dt_passedm("31.12.2021 23:59:59", 180) * 3600), 60)}
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_left_tz()
dt_left_tz()
Функция - аналог dt_left(), но формирует оставшееся время, с учётом настроенного в боте часового пояса (_tz - Time Zone).
Функция берёт указанное вами время и отсчитывает сколько до него осталось по отношению ко времени в вашем Часовом Поясе (указанном в боте).
В общем случае, рекомендуется использовать данную функцию только если время указанное вами уже сохранено с учётом Часового Пояса - например функцией dt_now_tz() (чего мы делать - не рекомендуем). Если вы сохраняли Системное Время - например функцией dt_now() - используйте стандартные функции для работы с ним.
dt_passed_tz()
dt_passed_tz()
Функция - аналог dt_passed(), но формирует прошедшее время, с учётом настроенного в боте часового пояса (_tz - Time Zone).
Функция берёт указанное вами время и отсчитывает сколько времени прошло по отношению ко времени в вашем Часовом Поясе (указанном в боте).
В общем случае, рекомендуется использовать данную функцию только если время указанное вами уже сохранено с учётом Часового Пояса - например функцией dt_now_tz() (чего мы делать - не рекомендуем). Если вы сохраняли Системное Время - например функцией dt_now() - используйте стандартные функции для работы с ним.
dt_format()
dt_format(date, "$a $b $c $d $e")
Где:date - это макрос переменной содержащей время (в кавычках) или любая функция времени$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("%date_var%", "$d.$m ($Y)")} - 31.12 (2024)
❖ Дополнительная Информация
Дату и Время можно записывать в Переменные
О том что такое переменные и как с ними работать.
• • •
Функции и Переменные с Дата/Время можно использовать в Выражениях
О том как применять Выражения, читай в руководстве по Выражениям.
• • •
Функции и Переменные с Дата/Время можно использовать в Условиях
О том как применять Условия, читай в руководстве по Условиям.
• • •
Дату и Время можно использовать в Action-ах
Подробнее о том что такое Action-ы, чем они удобны и как ими пользоваться смотрите в отдельном Руководстве по Action-ам.