datetime: timezone support

Closes #2886

Author: ligurio

doc/reference/reference_lua/datetime.rst

@@ -50,7 +50,7 @@ Below is a list of ``datetime`` functions, properties, and related objects.
             -
 
         *   -   :ref:`datetime.TZ <datetime-tz>`
-            -   An array of timezone names and abbreviations
+            -   A Lua table that maps timezone names and abbreviations to its index and vice-versa.
 
         *   -   **Methods**
             -
@@ -327,7 +327,8 @@ Functions
         - 1970-01-01T03:00:00.125+0300
         ...
 
-        tarantool> dt = datetime.parse('01:01:01', {format ='%H:%M:%S'})
+        tarantool> dt = datetime.parse('01:01:01 MSK', {format ='%H:%M:%S %Z'})
+
         ---
         ...
 
@@ -346,6 +347,11 @@ Functions
         - 5
         ...
 
+        tarantool> dt.tz
+        ---
+        - MSK
+        ...
+
 ..  _datetime-interval-is_interval:
 
 ..  function:: datetime.interval.is_interval([value])
@@ -497,9 +503,20 @@ Properties
 
     Since: :doc:`2.11.0 </release/2.11.0>`
 
-    An array of timezone names and abbreviations.
+    A Lua table that maps timezone names (like ``Europe/Moscow``) and
+    timezone abbreviations (like ``MSK``) to its index and vice-versa.
 
+    ..  code-block:: tarantoolsession
 
+        tarantool> datetime.TZ['Europe/Moscow']
+        ---
+        - 947
+        ...
+
+        tarantool> datetime.TZ[947]
+        ---
+        - Europe/Moscow
+        ...
 
 ..  _datetime-module-api-reference-objects:
 
@@ -522,6 +539,8 @@ datetime_object
         Modify an existing datetime object by adding values of the input argument.
         See also: :ref:`interval_arithm`.
 
+        При вычислении :add/:sub и установленном tzindex вычисление производится с учётом tzdata.
+
         :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.
                                 Possible values: ``none``, ``last``, ``excess`` (see **Example #2**). Defaults to ``none``.
@@ -703,6 +722,8 @@ datetime_object
         Modify an existing datetime object by subtracting values of the input argument.
         See also: :ref:`interval_arithm`.
 
+        При вычислении :add/:sub и установленном tzindex вычисление производится с учётом tzdata.
+
         :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.
                                 Possible values: ``none``, ``last``, ``excess``. Defaults to ``none``.
@@ -789,10 +810,14 @@ datetime_object
                     -   Days since the beginning of the year
 
                 *   -   isdst
-                    -   Is the DST (Daylight saving time) applicable for the date. Boolean.
+                    -   Is the DST (Daylight Saving Time) applicable for the date,
+                        see a section :ref:`timezone <timezone>`. Boolean.
 
                 *   -   tzoffset
-                    -   Time zone offset from UTC
+                    -   Time zone offset from UTC, see a section :ref:`timezone <timezone>`. Number.
+
+                *   -   tz
+                    -   Time zone name or abbreviation, see a section :ref:`timezone <timezone>`. String.
 
         :return: table with the date and time parameters
         :rtype: table
@@ -1080,11 +1105,69 @@ This section describes how the ``datetime`` module supports leap seconds:
         - 1970-01-01T00:01:00Z
         ...
 
+.. _timezone:
+
+Time zones
+----------
+
+Full support has been added since :doc:`2.11.0 </release/2.11.0>`.
+
+Tarantool uses `Time Zone Database <https://www.iana.org/time-zones>`__
+(also known as Olson database and supported by IANA) for timezone support.
+You can use the Lua module :ref:`tarantool <tarantool-module>` to get a used version of ``tzdata``.
+
+Every datetime object has three fields that represents timezone support:
+``tz``, ``tzoffset`` and ``isdst``:
+
+*   The field ``isdst`` is calculated using tzindex and attributes of the selected
+    timezone in the Olson DB timezone.
+
+    ..  code-block:: tarantoolsession
+
+        tarantool> require('datetime').parse('2004-06-01T00:00 Europe/Moscow').isdst
+        ---
+        - true
+        ...
+
+*   The field ``tz`` field can be set to timezone name or timezone abbreviation. Timezone name
+    is a human-readable timezone names, basing on the Time Zone Database, for example "Europe/Moscow".
+    Timezone abbreviation represents time zones by `alphabetic abbreviations <https://www.timeanddate.com/time/zones/>`__
+    such as "EST", "WST", and "CST". Both timezone names and abbreviations are available
+    via bidirectional array :ref:`datetime.TZ <datetime-tz>`.
+
+*   The field ``tzoffset`` is calculated automatically using current Olson rule i.e.
+    it would take into consideration summer time, leap year and leap seconds information
+    when timezone name is set. However, field ``tzoffset`` can be set manually when appropriate timezone
+    is not available.
+
+The fields ``tz``, ``tzoffset`` can be set :ref:`datetime.new() <datetime-new>`,
+:ref:`datetime.parse() <datetime-parse>` and :ref:`datetime_object:set() <datetime-set>`.
+
 Limitations
 -----------
 
 The supported date range is from ``-5879610-06-22`` to ``+5879611-07-11``.
 
+There were moments in a past history, when local mean time in some partcular zone
+used timezone offset not representable in a whole minutes, but rather in seconds,
+i.e. in Moscow before 1918 there used to be offset +2 hours 31 minutes and 19 seconds.
+Please see Olson dump for this period:
+
+.. code-block:: console
+
+    $ ./src/lib/tzcode/install/usr/bin/zdump -c1880,1918 -i Europe/Moscow
+
+    TZ="Europe/Moscow"
+    -       -       +023017 MMT
+    1916-07-03      00:01:02        +023119 MMT
+    1917-07-02      00      +033119 MST     1
+    1917-12-27      23      +023119 MMT
+
+Modern ``tzdata`` rules do not use such tiny fraction, and all timezones differ
+to UTC in units measured in minutes, not seconds. Tarantool datetime module uses
+minutes internally as units for ``tzoffset`` so there is some loss of precision
+if you try to operate with such ancient timestamps.
+
 References
 ----------