Describe datetime module and its functions and methods

doc/reference/reference_lua/datetime.rst

@@ -0,0 +1,46 @@
+
+Module datetime
+===============
+
+Since :doc:`2.10.0 </release/2.10.0>`.
+
+The ``datetime`` module provides support for the :ref:`datetime and interval data types <index-box_datetime>`.
+It allows creating the date and time values either via the object interface
+or via parsing string values conforming to the ISO-8601 standard.
+
+Below is a list of the ``datetime`` module functions and methods.
+
+.. container:: table
+
+    ..  rst-class:: left-align-column-1
+    ..  rst-class:: left-align-column-2
+
+    ..  list-table::
+        :widths: 25 75
+        :header-rows: 1
+
+        *   -   Name
+            -   Use
+
+        *   -   :doc:`./datetime/new`
+            -   Create a ``datetime`` object from a table of time units.
+
+        *   -   :ref:`format() <datetime-format>`
+            -   Convert the standard presentation of a ``datetime`` object into a formatted string.
+
+        *   -   :ref:`totable() <datetime-totable>`
+            -   Convert the information from a ``datetime`` object into the table format.
+
+        *   -   :ref:`set() <datetime-set>`
+            -   Update the field values in the existing ``datetime`` object.
+
+        *   -   :doc:`./datetime/interval_new`
+            -   Create an ``interval`` object from a table of time units.
+
+
+..  toctree::
+    :hidden:
+
+    datetime/new
+    datetime/datetime_object
+    datetime/interval_new

doc/reference/reference_lua/datetime/datetime_object.rst

@@ -0,0 +1,245 @@
+.. _datetime_object:
+
+datetime_object
+===============
+
+..  class:: datetime_object
+
+    Since :doc:`2.10.0 </release/2.10.0>`.
+
+    ..  _datetime-totable:
+
+    ..  method:: totable()
+
+        Convert the information from the ``datetime`` object into the table format.
+        Resulting table has the following fields:
+
+        ..  container:: table
+
+            ..  list-table::
+                :widths: 30 70
+                :header-rows: 1
+
+                *   -   Field name
+                    -   Description
+
+                *   -   nsec
+                    -   Nanosecods
+
+                *   -   sec
+                    -   Seconds
+
+                *   -   min
+                    -   Minutes
+
+                *   -   hour
+                    -   Hours
+
+                *   -   day
+                    -   Day number
+
+                *   -   month
+                    -   Month number
+
+                *   -   year
+                    -   Year
+
+                *   -   wday
+                    -   Days since the beginning of the week
+
+                *   -   yday
+                    -   Days since the beginning of the year
+
+                *   -   isdst
+                    -   Is the DST (Daylight saving time) applicable for the date. Boolean.
+
+                *   -   tzoffset
+                    -   Time zone offset from UTC
+
+        :return: table with the date and time parameters
+        :rtype: table
+
+        **Example:**
+
+        ..  code-block:: tarantoolsession
+
+            tarantool> dt = datetime.new {
+                        sec = 20,
+                        min = 25,
+                        hour = 18,
+
+                        day = 20,
+                        month = 8,
+                        year = 2021,
+                        }
+            ---
+            ...
+
+            tarantool> dt:totable()
+            ---
+            - sec: 20
+              min: 25
+              yday: 232
+              day: 20
+              nsec: 0
+              isdst: false
+              wday: 6
+              tzoffset: 0
+              month: 8
+              year: 2021
+              hour: 18
+            ...
+
+    ..  _datetime-format:
+
+    ..  method:: format( ['convensions'] )
+
+        Convert the standard ``datetime`` object presentation into a formatted string.
+        The formatting convension specifications are the same as in the `strftime <https://www.freebsd.org/cgi/man.cgi?query=strftime&sektion=3>`__ library.
+        Additional convension for nanoseconds is `%f` which also allows a modifier to control the output precision of fractional part: `%5f` (see the example below).
+        If no arguments are set for the method, the default convensions are used: `'%FT%T.%f%z'` (see the example below).
+
+        :param string convensions: string consisting of zero or more conversion specifications and ordinary characters
+
+        :return: string with the formatted date and time information
+        :rtype: string
+
+        **Example:**
+
+        ..  code-block:: tarantoolsession
+
+            tarantool> dt = datetime.new {
+                        nsec = 123456789,
+
+                        sec = 20,
+                        min = 25,
+                        hour = 18,
+
+                        day = 20,
+                        month = 8,
+                        year = 2021,
+
+                        tzoffset  = 180
+                        }
+            ---
+            ...
+
+            tarantool> dt:format('%d.%m.%y %H:%M:%S.%5f')
+            ---
+            - 20.08.21 18:25:20.12345
+            ...
+
+            tarantool> dt:format()
+            ---
+            - 2021-08-20T18:25:20.123456789+0300
+            ...
+
+            tarantool> dt:format('%FT%T.%f%z')
+            ---
+            - 2021-08-20T18:25:20.123456789+0300
+            ...
+
+    ..  _datetime-set:
+
+    ..  method:: set( [{ units }] )
+
+        Update the field values in the existing ``datetime`` object.
+
+        :param table units: Table of time units. The :ref:`time units <datetime-new-args>` are the same as for the ``datetime.new()`` function.
+
+        :return: updated datetime_object
+        :rtype: cdata
+
+        **Example:**
+
+        ..  code-block:: tarantoolsession
+
+            tarantool> dt = datetime.new {
+                        nsec = 123456789,
+
+                        sec = 20,
+                        min = 25,
+                        hour = 18,
+
+                        day = 20,
+                        month = 8,
+                        year = 2021,
+
+                        tzoffset  = 180
+                        }
+
+            tarantool> dt:set {msec = 567}
+            ---
+            - 2021-08-20T18:25:20.567+0300
+            ...
+
+            tarantool> dt:set {tzoffset = 60}
+            ---
+            - 2021-08-20T18:25:20.567+0100
+            ...
+
+    ..  _datetime-parse:
+
+    ..  method:: parse( 'input_string'[, {format, tzoffset} ] )
+
+        Convert an input string with the date and time information into a ``datetime`` object.
+        The input string should be formatted according to one of the following standards:
+
+        *   ISO 8601
+        *   RFC 3339
+        *   extended `strftime <https://www.freebsd.org/cgi/man.cgi?query=strftime&sektion=3>`__ -- see description of the :ref:`format() <datetime-format>` for details.
+
+        :param string input_string: string with the date and time information.
+        :param string format: indicator of the input_sting format. Possible values: 'iso8601', 'rfc3339', or ``strptime``-like format string.
+                                If no value is set, the default formating  is used.
+        :param number tzoffset: time zone offset from UTC, in minutes.
+
+        :return: a datetime_object
+        :rtype: cdata
+
+        **Example:**
+
+        ..  code-block:: tarantoolsession
+
+            tarantool> t = datetime.parse('1970-01-01T00:00:00Z')
+
+            tarantool> t
+            ---
+            - 1970-01-01T00:00:00Z
+            ...
+
+            tarantool> t = datetime.parse('1970-01-01T00:00:00', {format = 'iso8601', tzoffset = 180})
+
+            tarantool> t
+            ---
+            - 1970-01-01T00:00:00+0300
+            ...
+
+            tarantool> t = datetime.parse('2017-12-27T18:45:32.999999-05:00', {format = 'rfc3339'})
+
+            tarantool> t
+            ---
+            - 2017-12-27T18:45:32.999999-0500
+            ...
+
+            tarantool> T = datetime.parse('Thu Jan  1 03:00:00 1970', {format = '%c'})
+
+            tarantool> T
+            ---
+            - 1970-01-01T03:00:00Z
+            ...
+
+            tarantool> T = datetime.parse('12/31/2020', {format = '%m/%d/%y'})
+
+            tarantool> T
+            ---
+            - 2020-12-31T00:00:00Z
+            ...
+
+            tarantool> T = datetime.parse('1970-01-01T03:00:00.125000000+0300', {format = '%FT%T.%f%z'})
+
+            tarantool> T
+            ---
+            - 1970-01-01T03:00:00.125+0300
+            ...
+

doc/reference/reference_lua/datetime/interval_new.rst

@@ -0,0 +1,100 @@
+..  _datetime-new:
+
+datetime.interval.new()
+=======================
+
+..  function:: datetime.interval.new( [{ units }] )
+
+    Since :doc:`2.10.0 </release/2.10.0>`.
+
+    Create an object of the :ref:`interval type <index-box_interval>` from a table of time units.
+    See :ref:`description of units <interval-new-args>` and :ref:`examples <interval-new-example>` below.
+
+    :param table units: Table of :ref:`time units <interval-new-args>`. For all possible time units, the values are not restricted.
+                                If an empty table or no arguments are passed, the ``interval`` object with the default value ``0 seconds`` is created.
+
+    :return: :doc: interval object
+    :rtype: cdata
+
+    ..  _interval-new-args:
+
+    **Possible input time units for ``datetime.interval.new()**
+
+    ..  container:: table
+
+        ..  list-table::
+            :widths: 20 50 20 10
+            :header-rows: 1
+
+            *   -   Name
+                -   Description
+                -   Type
+                -   Default
+
+            *   -   nsec (usec, msec)
+                -   Fractional part of the last second. You can specify either nanoseconds (``nsec``), or microseconds (``usec``), or milliseconds (``msec``).
+                    Specifying two of these units simultaneously or all three ones lead to an error.
+                -   number
+                -   0
+
+            *   -   sec
+                -   Seconds
+                -   number
+                -   0
+
+            *   -   min
+                -   Minutes
+                -   number
+                -   0
+
+            *   -   hour
+                -   Hours
+                -   number
+                -   0
+
+            *   -   day
+                -   Day number
+                -   number
+                -   0
+
+            *   -   week
+                -   Week number
+                -   number
+                -   0
+
+            *   -   month
+                -   Month number
+                -   number
+                -   0
+
+            *   -   year
+                -   Year
+                -   number
+                -   0
+
+    ..  _interval-new-example:
+
+    **Examples:**
+
+    ..  code-block:: tarantoolsession
+
+        tarantool> datetime.interval.new()
+
+        ---
+        - 0 seconds
+        ...
+
+        tarantool> datetime.interval.new {
+                    month = 6,
+                    year = 1
+                    }
+        ---
+        - +1 years, 6 months
+        ...
+
+        tarantool> datetime.interval.new {
+                    day = -1
+                    }
+        ---
+        - -1 days
+        ...