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**
             -
@@ -155,12 +155,14 @@ Functions
                 -   0
 
             *   -   tzoffset
-                -   Time zone offset from UTC, in minutes. If both ``tzoffset`` and ``tz`` are specified, ``tz`` has the preference and the ``tzoffset`` value is ignored.
+                -   Time zone offset from UTC, in minutes. If both ``tzoffset`` and
+                    ``tz`` are specified, ``tz`` has the preference and the ``tzoffset``
+                    value is ignored. See a section :ref:`timezone <timezone>`.
                 -   number
                 -   0
 
             *   -   tz
-                -   Time zone name according to the `tz database <https://en.wikipedia.org/wiki/Tz_database>`__.
+                -   Time zone name according to the Time Zone Database, see a section :ref:`timezone <timezone>`.
                 -   string
                 -   -
 
@@ -327,7 +329,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 +349,11 @@ Functions
         - 5
         ...
 
+        tarantool> dt.tz
+        ---
+        - MSK
+        ...
+
 ..  _datetime-interval-is_interval:
 
 ..  function:: datetime.interval.is_interval([value])
@@ -497,9 +505,21 @@ 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,
+    see a section :ref:`timezone <timezone>`.
 
+    ..  code-block:: tarantoolsession
 
+        tarantool> datetime.TZ['Europe/Moscow']
+        ---
+        - 947
+        ...
+
+        tarantool> datetime.TZ[947]
+        ---
+        - Europe/Moscow
+        ...
 
 ..  _datetime-module-api-reference-objects:
 
@@ -522,6 +542,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 +725,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``.
@@ -762,37 +786,41 @@ datetime_object
                     -   Description
 
                 *   -   nsec
-                    -   Nanoseconds
+                    -   Nanoseconds. Number.
 
                 *   -   sec
-                    -   Seconds
+                    -   Seconds. Number.
 
                 *   -   min
-                    -   Minutes
+                    -   Minutes. Number.
 
                 *   -   hour
-                    -   Hours
+                    -   Hours. Number.
 
                 *   -   day
-                    -   Day number
+                    -   Day number.
 
                 *   -   month
-                    -   Month number
+                    -   Month number.
 
                 *   -   year
-                    -   Year
+                    -   Year. Number.
 
                 *   -   wday
-                    -   Days since the beginning of the week
+                    -   Days since the beginning of the week. Number.
 
                 *   -   yday
-                    -   Days since the beginning of the year
+                    -   Days since the beginning of the year. Number.
 
                 *   -   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
@@ -809,20 +837,22 @@ datetime_object
                         day = 20,
                         month = 8,
                         year = 2021,
+                        tz = 'MAGT',
                         }
             ---
             ...
 
             tarantool> dt:totable()
             ---
-            - sec: 20
+            - tz: 'MAGT'
+              sec: 20
               min: 25
               yday: 232
               day: 20
               nsec: 0
               isdst: false
               wday: 6
-              tzoffset: 0
+              tzoffset: 600
               month: 8
               year: 2021
               hour: 18
@@ -1080,11 +1110,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
 ----------