Working with Date and Time in MenuBuilderBot
MegaHubTelegram
The Menu Builder constructor allows you to work in Date and Time using them in mathematical Expressions. You can add and subtract time by calculating the elapsed or remaining time "from" or "to" a given event in the future, or marks in the past. To do this, a whole set of entities has been added to the @MenuBuilderBot constructor that allows you to work with Dates and Time and the ability to save timestamps in variables. Working with Time is mainly focused on the concept of "relative time", that is the time between some events, which will allow you to count the time in hours "from" and "to" the time marks. But you as well can use absolute values of time, displaying specific dates.
📜 The translation of this materials into your native language can be automatically done using the Google translator. Follow the link and select the desired language in the title:
https://translate.googleusercontent.com/translate_c?depth=1&sl=en&tl=es&u=https://telegra.ph/Working-with-Date-and-Time-in-MenuBuilder-EN-04-16
⬛ Table of content
◾ Basic functions for working with Date and Time
◾ The Types of Expression’s results
⬛ Date and Time format used
Date and Time are always Entered and Derived in a fixed format:
DD.MM.YYYY HH:mm:ss
where:
● DD - days
● MM - months
● YYYY - years (4 digits)
● HH - hours
● mm - minutes
● ss - seconds
Examples:
● "01.01.2020 00:00:01" - new 2020 year
● "17.05.2020 19:45:05" - here is some more unambiguous example of the time format displayed.
⬛ Variable of Date and Time
A special type of variables has been added for storing Date and Time data:
«📕 Time».
Technically, you can save Time 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 not performed with any actions.
In Bot’s Messages, Date and Time is outputed as usual, through the macros of the variable where it is stored.
In Expressions of Time Functions, when using Time Variables, macros of these variables MUST be taken "in quotation marks", because in fact they are text.
An example of writing the variable "date1" in expressions of TIME FUNCTIONS: {"%date1%"}. The expression itself is naturally in {braces}.
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 point will become clear to you later) for example:
{dt_passed (dt_now()...)}
In the example, the dt_now() function passed as a parameter to the dt_passed() function - no quotes are needed. You will understand this example when you read about functions below.
IMPORTANT! Once again: generally, when using "Time Variables" in Expressions of "Time Functions" ALWAYS take their macros "in quotes"! Otherwise, nothing will work.
Examples:
● Message: "You pressed the button on %date1%."
(Will show time stored in variable "date1")
● Expression: {dt_add ("%date1%", 1)}
(Will show time stored in variable "date1" plus 1 hour)
⬛ Basic functions for working with Date and Time
ALL (!) Real work with Dates goes ONLY through the special Time Functions (Except for the case when Date and Time just need to displayed in the message). Basic Time Functions are 3 in total:
dt_now - Current Time
dt_now() - the function of getting "now", that is, the current Date and Time. It is necessary for you to be able to count the time from "now", compare it, etc.
Returns a value type of "Date/Time".
A function has practical meaning only in Expressions, in combination with other functions or variable values.
The result of this function can also be used to save the current time into a variable (for example, the time at the moment when the button was pressed). In the future, such a record can be used as a “cutoff” for calculating the time elapsed from this moment.
Examples:
If used in the Message, it will display the current date and time (without taking into account the time zone so far) at the moment it is showed to the user.
If used in the button Expression or in the Action, the current date (at the moment of operation) can be written to a variable.
dt_add - Add Time
dt_add(date, hours) - function to get a date that differs from "date" by "hours" of hours.
Returns a value of type "Date/Time".
The function accepts (requires for operation) two parameters:
● date - the date from which the time is counted.
Usually, at the moment of use, it is already stored in some Time Variable (in this case, the macro of that variable in quotation marks should be used), however, it can also be the Current Time from the «dt_now()» function).
● hours - this is the number of hours for which you need to change the date - the hours are given in fractional numbers (for example, 0.5 hours is 30 minutes, etc.). This parameter can be not only hard-coded using a specific number, but can also be represented by the value of a Numeric Variable, in this case, use the macros of this variable (without quotes).
The Hours can be negative (if the date needs to be reduced), in this case, the time is calculated in the opposite direction relative to the date in the variable.
In fact, this is the function of adding time, in hours, to a certain Date. The result will show a new Date. The function is needed to display in a message or save in a variable, a point in the future (for example, the end of a "trip to the forest" in games) - calculated in this function.
Examples:
It will calculate the date an hour later than the one stored in the variable "date1". Note that the "%date1%" Time Variable macros are in quotation marks, this is important!
It will calculate the date one and a half hours later than "now" (at the time the expression was triggered). For example: "You are gone, return back at {dt_add(dt_now(), 1.5)}"
It will calculate the date “var1” hours later than the one stored in the variable “date1”. Note that the "%date1%" Time Variable macros is in quotes, and the macros of Numeric Variable %var1% is without quotes!
Adding standard time periods.
There are situations when you need to add a certain standard period of time to a particular date (today's or any other), for example: hour, day, week, month or year. For convenience, the following expressions have been introduced:
will add 1 hour (for hours, you can use the following expression {dt_add (dt_now (), 1)}).
add 1 day
add 1 week
will add 1 month
will add 1 year
INFO: Obviously, instead of the dt_now() function, you can use any date or macros of a Time variable containing a date.
dt_diff - Time Difference
dt_diff(date1, date2) - function to get the difference in hours (fractional) between two dates. Computes "date1" minus "date2". If "date2" is larger (that is, later in time) than "date1", the result will be a negative number.
Returns the fractional number of hours.
The function is needed to get information about how much time has passed between the two events "date1" and "date2".
Examples:
Suppose you previously saved the Date/Time in the variable "date1". This example will calculate how many hours have passed from the time stored in the variable "date1" (that is, from some event in the past) to the current moment from the function «dt_now()».
Note that the Time Variable macros "%date1%" is in quotation marks, this is important!
● For example: "{dt_diff(dt_now(), "%date1%")} hours has passed since you left."
● Or more interesting: "Over the past {dt_diff(dt_now(), "%date1%")} hours, you have earned {dt_diff(dt_now(), "%date1%") * 10} coins." (presuming that the user receives 10 coins per hour)
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("%date%", dt_now(), "s")} - result in seconds.
{dt_diff("%date%", dt_now(), "d")} - result in days (fractional).
{dt_diff("%dater%", dt_now(), "d", "u")} - result in days (whole, rounded up).
⬛ Comparing Date and Time
The Time Functions, as well as Variables containing data on Date and Time, can serve as a condition for performing certain comparisons in Buttons and «Actions». To do this, the Time can be compared in the Conditions of these buttons and «Actions».
Dates and Time are compared by the usual comparison operators:
● >, >= (Greater, Greater than or Equal)
● <, <= (Less, Less, or Equal)
and others.
Technically, you can compare dates to "equal/not equal" (==, !=), But there is no practical sense in this: it is unlikely that the dates will coincide to within milliseconds.
Example:
Checks whether the time, saved in the variable "date1" has arrived (the time in the variable is less than “now”).
⬛ The Types of Expression’s results
When writing the results of the Time Functions to variables (when they are saved to a variable through the buttons such as «Bonus», «Exchange», or through «Actions»), it is important to understand and consider what type of result this or that Time Function returns. The method of writing data and, accordingly, what will remain recorded in the variable, after all, will depend on this.
Results come in two Types:
● Type – Date and Time. If the expression returns "Date and Time" - then the date will be ASSIGNED to the variable. Assigned means: that, 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. It works on the principle similar to the «dt_add()» function.
What type of result this or that function returns, see above, in the description of the functions themselves.
⬛ Additional Functions
Additional functions provide opportunities that, in principle, can be "assembled" using the "Basic Time Functions" - by doing all the calculations yourself. However, the use of "Additional Functions" for "typical scenarios" allows you to reduce the visual complexity of Expressions and simplify your work.
The set of additional functions will most likely expand as new “typical”, actively used scenarios are identified (in other words, at your requests).
dt_left
the function that returns how many HOURS remain before the specified (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). It is more intended for the convenience of calculations 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("%date%", dt_now(), "s")} - result in seconds.
{dt_left("%date%", dt_now(), "d")} - result in days (fractional).
{dt_left("%dater%", dt_now(), "d", "u")} - result in days (whole, rounded up).
dt_left_hm
the function that returns a string in HH:MM, how much time left in HOURS and MINUTES before the specified (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 convenient for understanding by the person, the number of hours and minutes (1:12, 7:42, 36:24). Designed to simplify the understanding for the user and the convenience of displaying values in Messages.
dt_passed
the function that returns how much time IN HOURS has passed from the specified (date). If the date has not yet arrived 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). It is more intended for the convenience of calculations 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("%date%", dt_now(), "s")} - result in seconds.
{dt_passed("%date%", dt_now(), "d")} - result in days (fractional).
{dt_passed("%dater%", dt_now(), "d", "u")} - result in days (whole, rounded up).
dt_passed_hm
the function that returns a string in HH:MM how many HOURS and MINUTES have passed since the specified (date). If the date has not yet come relative to the current moment, the function will return 00:00.
The function will return, the usual and convenient for understanding by the person, the number of hours and minutes (1:12, 7:42, 36:24). Designed to simplify the understanding for the user and the convenience of displaying values in Messages.
dt_passedm
the function that returns how many HOURS have passed since the specified date (date), but not more than (max) hours. If the date has not yet come relative to the current moment, the function will return 0 (zero). If more than (max) hours have passed relative to (data), the function will return (max).
The function will return a fractional, decimal number of hours (1.2, 5.7, 34.4). It is more intended for the convenience of calculations in Expressions.
dt_passedm_hm
the function that returns a string in HH:MM how many HOURS and MINUTES have passed since the specified (date), but not more than (max) hours. If the date has not yet come relative to the current moment, the function will return 00:00. If more than (max) hours have passed relative to (data), the function will return (max) in the format of HH:MM.
The function will return, the usual and convenient for understanding by the person, the number of hours and minutes (1:12, 7:42, 36:24). Designed to simplify the understanding for the user and the convenience of displaying values in Messages.
⬛ Additional Information
◾ Date and Time can be written to Variables.
What variables are and how to work with them, see the Help Bot
https://t.me/MenuBuilderHelpBot?start=m10089
◾ Functions and Variables with Date and Time can be used in Expressions.
For how to use Expressions, read the Guide on Expressions.
◾ Functions and Variables with Date and Time can be used in the Conditions.
For how to use Conditions, read the Guide for Conditions
◾ Date and Time can be used in Actions.
For more information on what Actions are, what they are convenient for and how to use them, see the separate Action Guide.
