Working with Date and Time
❖ Used Date and Time format
Date and Time are always Input and Output in a fixed format:
DD.MM.YYYY HH:mm:ss
where:
● DD - day
● MM - month
● YYYY - year (4 digits)
● HH - hours
● mm - minutes
● ss - seconds
For example:
● "01.01.2020 00:00:01" - new year 2020
● "17.05.2020 19:45:05" - this is a more unambiguous example of the format of the displayed time.
❖ Date and Time Variables
A special type of variables has been added to store the Date / Time:
«📕 Time».
Technically speaking, Time can be stored in Text Variables, but you will not be able to fully work with such variables. In the Text variable, Time can only be stored, but you will not be able to performed any actions with it.
Syntax in messages
In Bot Messages - Date / Time is displayed as usual - through the Macros of the variable where it was stored.
Expression Syntax
In Expressions of Time Functions, when using variables containing Time - macros of these variables MUST be taken "in quotes" since they are text in fact.
Parameter syntax in a function
Example of using variable "date1" expressions in a function of time: {dt_passed("%date1%")}.
The expression itself is obviously in {curly braces}.
For more information on expressions, see the guide on Expressions.
Function syntax
When passing the value of one function to another, even if the value is text, you DO NOT need to enclose the function in quotes (the meaning of this paragraph will become clear to you later) for example: {dt_passed(dt_now()...)}
In this example, the function is dt_now() passed as a function parameter of dt_passed() - quotes are not needed. You will understand this example when you read about functions below.
Once again: in general, when using Time Variables in Time Function Expressions, ALWAYS put their macros in quotation marks! Otherwise, nothing will work.
Examples:
● Message: "You pressed a button in %date1% ".
(Shows time stored in variable "date1")
● Expression: {dt_add("%date1%", 1)}
(Shows time stored in variable "date1" plus 1 hour)
❖ Basic functions for working with Date and Time
ALL ( ! ) real work with dates occurs ONLY through special Functions (Except when the Date / Time just needs to be displayed in the message). There are only 3 basic functions:
dt_now() - Current time
dt_now()Current Time - the function of getting "now", that is, the current Date and Time. It is needed to be able to count the time from "now", compare it, etc.
Returns a "Date / Time" as a value type.
Function has practical meaning in Expressions, in combination with other functions or variable values.
Also, the result of this function can be used to save the current time in a variable (for example, the time at the moment the button was pressed). In the future, such a record can be used as a "cutoff" for calculating the time elapsed from that moment.
Examples:{dt_now()}
If used in a Message, it will display the current date and time (WITHOUT taking into account bot's Time Zone) at the moment it is shown to the user. If it is used in the Expression of the button or in the Action, then the current date (at the moment of triggering) can be written to the variable.
The time shown using the function {dt_now()} may NOT MATCH the time shown using macros %date% and %time%, because, unlike the time of macros, it DOES NOT DEPEND on the time zone set in the bot - it's a System Time.
Do not use this function to display the current time in messages (unless your time zone is + 3UTC).
Read more about setting the time zone in the bot in the help section.
Learn more about the available macros.
dt_add() - Add Time
dt_add(date, hours)Add time is a function for getting a date that differs from "date" by amount of "hours" hours. In other words, some "date" plus some "hours".
Returns a "Date / Time" as a value type.
The function takes (requires for operation) two parameters:
● date - the date from which the time is counted.
Usually, by the time of use, it is already stored in some Time Variable (in this case, use the macro of that variable in quotes), but it can also be the Current Time from the "dt_now()" function).
● hours is the number of hours by which you want to change the date - hours are set with a fractional number (for example, 0.5 hours is 30 minutes, etc.). This parameter not only can be hard-coded using a specific number, but can also be represented by the value of a Numeric Variable - in this case, use the macro of this variable (without quotes).
Hours can be negative (if the date needs to be decreased), in this case the time is calculated in the opposite direction relative to the date in the variable.
In fact, this function is a way of adding time in hours to a certain Date. The result will show the new Date.
The function is needed to display in a message or save in a variable some point in the future (for example, the end of a "trip to the forest" in games) - calculated in this function.
Examples:{dt_add("%date1%", 1)}
Calculate the date one 1 hour later than the one stored in the variable "date1".
Please note that the Time Variable macro "%date1%" is in quotes, this is important (date is a text information)!
Calculate the date one 1.5 hour later than dt_now() "now" (at the time of the expression).
For example: "You went out, go back in {dt_add(dt_now(), 1.5)}". That is, in an hour and a half.
Will calculate the date "var1" hours later than the one stored in the variable "date1".
Note that the Time Variable macro "%date1%" is in quotation marks, and the Numeric Variable macro %var1% is without quotation marks!
Adding standard time periods
There are situations when you need to add a certain standard period of time to a date (today or any other), for example: hour, day, week, month or a year. For convenience, the following expressions have been introduced:
Add 1 hour.
For hours, however, the following expression can be used {dt_add(dt_now(), 1)}.
add 1 day
add 1 week
will add 1 month (this means a calendar month - regardless of the number of days in the month itself)
will add 1 year
Obviously, instead of a function, dt_now() you can use any date or macro of a time variable containing a date.
dt_diff() - Time Difference
dt_diff(date1, date2)Time difference is a function of getting the difference in hours (fractional) between two dates. Calculatesdate1minusdate2. If "date2" is greater (that is, later in time) than "date1" - the result will be a negative number.
Returns a "fractional number of Hours" as a value type.
The function is needed to get information about how much time in (fractional) hours elapsed between two events "date1" and "date2".
Examples:{dt_diff(dt_now(), "%date1%")}
Suppose you have previously stored the Date / Time in the "date1" variable . This example will calculate (the difference) how many hours have passed from the time stored in the variable "date1" (that is, from some event in the past) to the present moment from the function "dt_now()".
Note that the macros of Time Variable "%date1%" is in quotes, this is important!
Additional optional parameters:
Result type: "s", "m", "h", "d" (second, minute, hour, day). The default is hour.
Rounding: "n", "u", "d" (do not round, round up, round down). The default is no rounding.{dt_diff("%datevar%", dt_now(), "s")} - result in seconds.{dt_diff("%datevar%", dt_now(), "d")} - result in days (fractional).{dt_diff("%datevar%", dt_now(), "d", "u")} - result in days (whole, rounded up).
● Sample message:
"Since you left {dt_diff(dt_now(), "%date1%")} hours has passed."
● Or more interesting:
"For the last {dt_diff(dt_now(), "%date1%")} hours you have earned {dt_diff(dt_now(), "%date1%") * 10} coins."
In case that the user receives 10 coins per hour.
❖ Compare Date and Time
Time Functions, as well as Variables containing data about Date and Time, can serve as a Condition for performing certain actions in Buttons and Actions. To do this, Time can be compared in the Conditions of these buttons and Actions.
Dates and Times are compared with the usual comparison operators:
● >, >= (Greater than, Greater than or equal to)
● <, <= (Less than, Less than or equal to)
and others.
Technically, it is possible to compare dates by "equal / not equal" (==, !=), but there is no practical sense in this: it is unlikely that the dates will coincide with millisecond precision.
For example:{"%date1%" < dt_now()}
Is the time stored in the variable "date1" has already being reached (the time in the variable is less than now)?
In the condition it will sound like this: "IF {"%date1%" < dt_now()} THEN The condition is True. And as long as it is true, the button with such a condition will work as usual. As soon %date1% appears to be greater than dt_now(), condition will disable the use of the button.
❖ Expression Result Types
When writing the results of the Date / Time functions to variables (when they are saved to a variable through buttons such as "Bonus", "Exchange", or through "Actions"), it is important to understand and take into account the TYPE of the result that is returned by this or that Time Function. The method of writing data will depend on this and, accordingly, what will remain recorded in the variable at the end.
Results are of two Types:
● Type - Date / Time. If the expression returns "Date" - then the date will be SET to the variable. Always set: that is, the old date will be overwritten by the new one.
● Type - Number: If the expression returns "Number", then the value will be ADDED (or subtracted, if negative) to the Date in the variable. Work on the principle of the «dt_add()» function.
What type of result, this or that function returns, see above - in the description of the functions themselves.
❖ Additional Features
Additional functions provide opportunities that, basically, can be "assembled" from the "Basic Functions" - by doing all the calculations yourself. However, using "Advanced Functions" for "typical scenarios" can reduce the visual complexity of Expressions and make your work easier.
The set of additional functions is likely to expand as a new "typical", actively used scenarios, are identified (in other words, at your request).
dt_left()
dt_left(date)
a function that returns how many HOURS are left until the specified date (date). If the date has already passed relative to the current moment, the function will return 0 (zero).
The function will return a fractional, decimal number of hours (1.2, 5.7, 34.4). More intended for ease of calculation in Expressions.
Additional optional parameters:
Result type: "s", "m", "h", "d" (second, minute, hour, day). The default is hour.
Rounding: "n", "u", "d" (do not round, round up, round down). The default is no rounding.{dt_left("%datevar%", "s")} - result in seconds.{dt_left("%datevar%", "d")} - result in days (fractional).{dt_left("%datevar%", "d", "u")} - result in days (whole, rounded up).
If you need to show how many Days, Hours and Minutes are left before the event:{floor(dt_left("%date%", "d"))} days{floor(mod(dt_left("%date%", "h"), 24))} hours{floor(mod(dt_left("%date%", "m"), 60))} minutes
Where %date% is a variable containing data about a certain date in the future.
(will show conditionally: 365 days 23 hours 59 minutes)
dt_left_hm()
dt_left_hm(date)
a function that returns a string in HH: MM, how many hours and MINUTES are left until the specified date (date). If the date has already passed relative to the current moment, the function will return 00:00.
The function will return the usual and easy-to-understand number of hours and minutes (1:12, 7:42, 36:24). It is intended to simplify the understanding by the user and the convenience of displaying values in Messages.
Additional optional parameters:
Formatting of the received results:{dt_left_hm ("12.31.2021 23:59:59", "-")} - your own separator (will show something like: 170-59){dt_left_hm ("12.31.2021 23:59:59", " | ", " hours", " minutes")} - your own separator and suffixes for Hours and Mnutes (will show something like: 170 hours | 59 minutes)
dt_passed()
dt_passed(date)
a function that returns how many hours have passed since the specified date (date). If the date has not come yet relative to the current moment, the function will return 0 (zero).
The function will return a fractional, decimal number of hours (1.2, 5.7, 34.4). More intended for ease of calculation in Expressions.
Additional optional parameters:
Result type: "s", "m", "h", "d" (second, minute, hour, day). The default is hour.
Rounding: "n", "u", "d" (do not round, round up, round down). The default is no rounding.{dt_passed("%datevar%", "s")} - result in seconds.{dt_passed("%datevar%", "d")} - result in days (fractional).{dt_passed("%datevar%", "d", "u")} - result in days (whole, rounded up).
dt_passed_hm()
dt_passed_hm(date)
a function that returns a string in HH: MM how many hours and minutes have passed since the specified date (date). If the date has not come yet relative to the current moment, the function will return 00:00.
The function will return the usual and easy-to-understand number of hours and minutes (1:12, 7:42, 36:24). It is intended to simplify the understanding by the user and the convenience of displaying values in Messages.
Additional optional parameters:
Formatting of the received results:{dt_passed_hm ("12.31.2021 23:59:59", "-")} - your own separator (will show something like: 170-59){dt_passed_hm ("12.31.2021 23:59:59", " | ", " hours", " minutes")} - your own separator and suffixes for Hours and Mnutes (will show something like: 170 hours | 59 minutes)
dt_passedm()
dt_passedm(date, max)
a function that returns how many hours have elapsed since the specified date (date), but not more than (max) hours. If the date has not come yet relative to the current moment, the function will return 0 (zero). If relative to (date) more than (max) hours have passed, the function will return (max).
The function will return a fractional, decimal number of hours (1.2, 5.7, 34.4). More intended for ease of calculation in Expressions.
dt_passedm_hm()
dt_passedm_hm(date, max)
a function that returns a string in HH: MM how many hours have passed in HOURS AND MINUTES since the specified date, but not more than (max) hours. If the date has not come yet relative to the current moment, the function will return 00:00. If relative to (date) more than (max) hours have passed, the function will return (max) in the HH: MM format.
The function will return the usual and easy-to-understand number of hours and minutes (1:12, 7:42, 36:24). It is intended to simplify the understanding by the user and the convenience of displaying values in Messages.
Additional optional parameters:
Formatting of the received results:{dt_passedm_hm ("12.31.2021 23:59:59", "-")} - your own separator (will show something like: 170-59){dt_passedm_hm ("12.31.2021 23:59:59", " | ", " hours", " minutes")} - your own separator and suffixes for Hours and Mnutes (will show something like: 170 hours | 59 minutes)
dt_nextday()
dt_nextday(date)
A function that received a date returns the date of the beginning of the next DAY.
An example of specifying the date and time:dt_nextday("%date% %time%") - using macros of date and timedt_nextday(dt_now()) - using the "now" functiondt_nextday(dt_now_tz()) - using the function "now - taking into account the time zone of the bot"
Example: received 01.01.2022 22:22:22 will return 02.01.2022 00:00:00.
dt_nextmonth()
dt_nextday(date)
A function that received a date returns the date of the beginning of the next MONTH.
An example of specifying the date and time:dt_nextmonth("%date% %time%") - using macros of date and timedt_nextmonth(dt_now()) - using the "now" functiondt_nextmonth(dt_now_tz()) - using the function "now - taking into account the time zone of the bot"
Example: received 22.01.2022 22:22:22 will return 01.02.2022 00:00:00.
dt_now_tz()
dt_now_tz()
The function is similar to dt_now(), but generates the time "now" according to the time zone configured in the bot (_tz - Time Zone).
Use this function only for displaying the time and such. We do not recommend using local Time Zones to store or check any data. With functions like: dt_left(), dt_passed() - this function will work INCORRECTLY.
dt_format()
dt_format(date, "$a $b $c $d $e")
Where: $a, $b, $c, $d, $e this is any of the values:
● $Y - year (4 digits)
● $m - month
● $d - day
● $H - hour
● $M - minute
● $S - second
The function allows you to format the date output in any way you need. You can use any text symbols inside "quotes" (except for the "" quotes themselves, of course).
For example:{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)
❖ Additional Information
Date and Time can be written to Variables
About what variables are and how to work with them.
• • •
Functions and Variables with Date / Time can be used in Expressions
For information on how to use Expressions, see the Expressions guide.
• • •
Functions and Variables with Date / Time can be used in Conditions
For information on how to apply Conditions, see the Conditions guide.
• • •
Date and Time can be used in Actions
For more information about what Actions are, how convenient they are and how to use them, see the separate Action Guide.