datetime: timezone support

[ligurio]

Stage: https://docs.d.tarantool.io/en/doc/gh-2886-timezone-support/reference/reference_lua/datetime/

Closes #2886

[andreyaksenov]

Please see my comments below:

[ligurio]

Added:

diff --git a/doc/reference/reference_lua/datetime.rst b/doc/reference/reference_lua/datetime.rst
index 32401669..292a0aef 100644
--- a/doc/reference/reference_lua/datetime.rst
+++ b/doc/reference/reference_lua/datetime.rst
@@ -541,7 +541,8 @@ datetime_object
 
         Modify an existing datetime object by adding values of the input argument.
         See also: :ref:`interval_arithm`. The addition is performed taking ``tzdata``
-        into account ``tzoffset`` or ``tz`` fields are set.
+        into account, when ``tzoffset`` or ``tz`` fields are set, see the :ref:`timezone`
+        and the :ref:`interval_arithm` sections.
 
         :param table input: an :ref:`interval object <interval_obj>` or an equivalent table (see **Example #1**)
         :param string adjust: defines how to round days in a month after an arithmetic operation.
@@ -723,7 +724,8 @@ datetime_object
 
         Modify an existing datetime object by subtracting values of the input argument.
         See also: :ref:`interval_arithm`. The subtraction is performed taking ``tzdata``
-        into account ``tzoffset`` or ``tz`` fields are set.
+        into account, when ``tzoffset`` or ``tz`` fields are set, see the :ref:`timezone`
+        and the :ref:`interval_arithm` sections.
 
         :param table input: an :ref:`interval object <interval_obj>` or an equivalent table (see **Example**)
         :param string adjust: defines how to round days in a month after an arithmetic operation.
@@ -1021,6 +1023,16 @@ The matrix of the ``subtraction`` operands eligibility and their result types:
             -   interval
             -   interval
 
+The subtraction and addition of datetime objects are performed taking ``tzdata``
+into account ``tzoffset`` or ``tz`` fields are set:
+
+..  code-block:: tarantoolsession
+
+    tarantool> datetime.new({tz='MSK'}) - datetime.new({tz='UTC'})
+    ---
+    - -180 minutes
+    ...
+
 .. _interval_comp:
 
 Datetime and interval comparison

[ligurio]

Updated:

diff --git a/doc/reference/reference_lua/datetime.rst b/doc/reference/reference_lua/datetime.rst
index 292a0aef..d785fe83 100644
--- a/doc/reference/reference_lua/datetime.rst
+++ b/doc/reference/reference_lua/datetime.rst
@@ -541,8 +541,7 @@ datetime_object
 
         Modify an existing datetime object by adding values of the input argument.
         See also: :ref:`interval_arithm`. The addition is performed taking ``tzdata``
-        into account, when ``tzoffset`` or ``tz`` fields are set, see the :ref:`timezone`
-        and the :ref:`interval_arithm` sections.
+        into account, when ``tzoffset`` or ``tz`` fields are set, see the :ref:`timezone`.
 
         :param table input: an :ref:`interval object <interval_obj>` or an equivalent table (see **Example #1**)
         :param string adjust: defines how to round days in a month after an arithmetic operation.
@@ -724,8 +723,7 @@ datetime_object
 
         Modify an existing datetime object by subtracting values of the input argument.
         See also: :ref:`interval_arithm`. The subtraction is performed taking ``tzdata``
-        into account, when ``tzoffset`` or ``tz`` fields are set, see the :ref:`timezone`
-        and the :ref:`interval_arithm` sections.
+        into account, when ``tzoffset`` or ``tz`` fields are set, see the :ref:`timezone`.
 
         :param table input: an :ref:`interval object <interval_obj>` or an equivalent table (see **Example**)
         :param string adjust: defines how to round days in a month after an arithmetic operation.
@@ -1157,6 +1155,8 @@ Every datetime object has three fields that represent timezone support:
 
 The fields ``tz``, ``tzoffset`` can be set in :ref:`datetime.new() <datetime-new>`,
 :ref:`datetime.parse() <datetime-parse>` and :ref:`datetime_object:set() <datetime-set>`.
+The arithmetic on datetime objects are performed taking ``tzdata`` into account, when
+``tzoffset`` or ``tz`` fields are set, see the :ref:`interval_arithm` section.
 
 Limitations
 -----------

[andreyaksenov]

Thanks! A couple of minor things

[andreyaksenov]

Thanks! Merging