diff --git a/doc/reference/reference_lua/datetime.rst b/doc/reference/reference_lua/datetime.rst index f218ed319..7cba7ac2e 100644 --- a/doc/reference/reference_lua/datetime.rst +++ b/doc/reference/reference_lua/datetime.rst @@ -50,7 +50,7 @@ Below is a list of ``datetime`` functions, properties, and related objects. - * - :ref:`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. + - A 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 `. - number - 0 * - tz - - Time zone name according to the `tz database `__. + - A time zone name according to the Time Zone Database. See the :ref:`timezone` section. - 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 ` - 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 the :ref:`timezone` section. + + .. code-block:: tarantoolsession + tarantool> datetime.TZ['Europe/Moscow'] + --- + - 947 + ... + tarantool> datetime.TZ[947] + --- + - Europe/Moscow + ... .. _datetime-module-api-reference-objects: @@ -520,7 +540,8 @@ datetime_object .. method:: add( input[, { adjust } ] ) Modify an existing datetime object by adding values of the input argument. - See also: :ref:`interval_arithm`. + See also: :ref:`interval_arithm`. The addition is performed taking ``tzdata`` + into account, when ``tzoffset`` or ``tz`` fields are set, see the :ref:`timezone`. :param table input: an :ref:`interval object ` or an equivalent table (see **Example #1**) :param string adjust: defines how to round days in a month after an arithmetic operation. @@ -701,7 +722,8 @@ datetime_object .. method:: sub( { input[, adjust ] } ) Modify an existing datetime object by subtracting values of the input argument. - See also: :ref:`interval_arithm`. + See also: :ref:`interval_arithm`. The subtraction is performed taking ``tzdata`` + into account, when ``tzoffset`` or ``tz`` fields are set, see the :ref:`timezone`. :param table input: an :ref:`interval object ` or an equivalent table (see **Example**) :param string adjust: defines how to round days in a month after an arithmetic operation. @@ -762,37 +784,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 `. Boolean. * - tzoffset - - Time zone offset from UTC + - Time zone offset from UTC, see a section :ref:`timezone `. Number. + + * - tz + - Time zone name or abbreviation, see a section :ref:`timezone `. String. :return: table with the date and time parameters :rtype: table @@ -809,20 +835,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 @@ -993,6 +1021,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 @@ -1080,10 +1118,70 @@ 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 `. + +Tarantool uses the `Time Zone Database `__ +(also known as the Olson database and supported by IANA) for timezone support. +You can use the Lua module :ref:`tarantool ` to get a used version of ``tzdata``. + +Every datetime object has three fields that represent 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 a timezone name or abbreviation. A timezone name + is a human-readable name based on the Time Zone Database, for example, "Europe/Moscow". + Timezone abbreviations represent time zones by `alphabetic abbreviations `__ + such as "EST", "WST", and "F". Both timezone names and abbreviations are available + via the bidirectional array :ref:`datetime.TZ `. + +* The field ``tzoffset`` is calculated automatically using the current Olson rule. + This means that it takes into account summer time, leap year, and leap seconds information + when a timezone name is set. However, the ``tzoffset`` field can be set manually when + an appropriate timezone is not available. + +The fields ``tz`` and ``tzoffset`` can be set in :ref:`datetime.new() `, +:ref:`datetime.parse() `, and :ref:`datetime_object: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 ----------- -The supported date range is from ``-5879610-06-22`` to ``+5879611-07-11``. +* The supported date range is from ``-5879610-06-22`` to ``+5879611-07-11``. + +* There were moments in past history when local mean time in some particular zone + used a timezone offset not representable in a whole minutes but rather in seconds. + For example, in Moscow before 1918 there used to be offset +2 hours 31 minutes and 19 seconds. + See an Olson dump for this period: + + .. code-block:: console + + $ 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 a tiny fraction, and all timezones differ + from UTC in units measured in minutes, not seconds. Tarantool datetime module uses + minutes internally as units for ``tzoffset``. So there might be some loss of precision + if you try to operate with such ancient timestamps. References ----------