Skip to content

Commit 7196565

Browse files
veod32veod32
committed
Add new sections for the datetime module and its new() function and methods of the datetime object
Part of #2411
1 parent b03db3f commit 7196565

File tree

4 files changed

+322
-0
lines changed

4 files changed

+322
-0
lines changed

‎doc/reference/reference_lua/datetime.rst

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
2+
Module datetime
3+
===============
4+
5+
Since :doc:`2.10.0 </release/2.10.0>`.
6+
7+
The ``datetime`` module provides support of the timestamp and interval data types. [TDB -- links].
8+
It allows to create the date and timestamp values using either object interface,
9+
or via parsing the string values conforming to ISO-8601 standard.
10+
11+
Below is a list of the ``datetime`` module functions and methods.
12+
13+
.. container:: table
14+
15+
.. rst-class:: left-align-column-1
16+
.. rst-class:: left-align-column-2
17+
18+
.. list-table::
19+
:widths: 25 75
20+
:header-rows: 1
21+
22+
* - Name
23+
- Use
24+
25+
* - :doc:`./datetime/new`
26+
- Create a datetime object from a table of date and time values/parameters
27+
28+
* - :ref:`format() <datetime-format>`
29+
- Convert a datetime object into a string of a particular format
30+
31+
* - :ref:`totable() <datetime-totable>`
32+
- Convert a datetime object into a Lua table
33+
34+
* - :ref:`set() <datetime-set>`
35+
- Update the field values in the existing datetime object
36+
37+
38+
39+
.. toctree::
40+
:hidden:
41+
42+
datetime/new
43+
datetime/datetime_object

‎doc/reference/reference_lua/datetime/datetime_object.rst

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
.. _datetime_object:
2+
3+
datetime_object
4+
===============
5+
6+
.. class:: datetime_object
7+
8+
Since :doc:`2.10.0 </release/2.10.0>`.
9+
10+
.. _datetime-totable:
11+
12+
.. method:: totable()
13+
14+
Export a table with the date and time parameters taken from the ``datetime`` object values.
15+
Additional parameters ``wday``, ``yday``, and ``isdst`` are as in :ref:`os.date() <os-date>`.
16+
17+
:return: table with the date and time parameters
18+
:rtype: table
19+
20+
**Example:**
21+
22+
.. code-block:: tarantoolsession
23+
24+
tarantool> dt = datetime.new {
25+
nsec = 123456789,
26+
27+
sec = 20,
28+
min = 25,
29+
hour = 18,
30+
31+
day = 20,
32+
month = 8,
33+
year = 2021,
34+
35+
tzoffset = 180
36+
}
37+
38+
tarantool> dt:totable()
39+
---
40+
- sec: 20
41+
min: 25
42+
yday: 232
43+
day: 20
44+
nsec: 123456789
45+
isdst: false
46+
wday: 6
47+
tzoffset: 180
48+
month: 8
49+
year: 2021
50+
hour: 18
51+
...
52+
53+
54+
.. _datetime-format:
55+
56+
.. method:: format( ['format units'] )
57+
58+
Convert standard ``datetime`` object presentation into a formatted string based on the format notation according to the FreeBSD/Olson ``strftime``.
59+
60+
61+
:return: formatted string with the date and time information
62+
:rtype: string
63+
64+
**Example:**
65+
66+
.. code-block:: tarantoolsession
67+
68+
tarantool> dt = datetime.new {
69+
nsec = 123456789,
70+
71+
sec = 20,
72+
min = 25,
73+
hour = 18,
74+
75+
day = 20,
76+
month = 8,
77+
year = 2021,
78+
79+
tzoffset = 180
80+
}
81+
82+
tarantool> dt:format('%d.%m.%y %H:%M:%S')
83+
---
84+
- 20.08.21 18:25:20
85+
...
86+
87+
.. _datetime-set:
88+
89+
.. method:: set( [{ time_units }] )
90+
91+
Update the field values in the existing ``datetime`` object.
92+
93+
:param table time_units: Table of time units. The :ref:`time units <datetime-new-args>` are the same as for the ``datetime.new()`` function.
94+
95+
:return: updated datetime_object
96+
:rtype: cdata
97+
98+
**Example:**
99+
100+
.. code-block:: tarantoolsession
101+
102+
tarantool> dt = datetime.new {
103+
nsec = 123456789,
104+
105+
sec = 20,
106+
min = 25,
107+
hour = 18,
108+
109+
day = 20,
110+
month = 8,
111+
year = 2021,
112+
113+
tzoffset = 180
114+
}
115+
116+
tarantool> dt:set {msec = 567}
117+
---
118+
- 2021-08-20T18:25:20.567+0300
119+
...
120+
121+
tarantool> dt:set {tzoffset = 60}
122+
---
123+
- 2021-08-20T18:25:20.567+0100
124+
...

‎doc/reference/reference_lua/datetime/new.rst

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
.. _datetime-new:
2+
3+
datetime.new()
4+
==============
5+
6+
.. function:: datetime.new( [{ time_units }] )
7+
8+
Since :doc:`2.10.0 </release/2.10.0>`.
9+
10+
Create an object of the :ref:`datetime type <index-box_data-types>` from a table of time units.
11+
See :ref:`description of units <datetime-new-args>` and :ref:`examples <datetime-new-example>` below.
12+
If an empty table or no arguments are passed, create the ``datetime`` object with the default values corresponding to Unix Epoch: ``1970-01-01T00:00:00Z``.
13+
14+
:param table time_units: Table of time units. [TDB]
15+
16+
:return: :doc:`datetime object <./datetime/datetime_object>`
17+
:rtype: cdata
18+
19+
.. _datetime-new-args:
20+
21+
**Possible time units for ``datetime.new()** [TBD]
22+
23+
.. container:: table
24+
25+
.. list-table::
26+
:widths: 20 50 20 10
27+
:header-rows: 1
28+
29+
* - Name
30+
- Description
31+
- Type
32+
- Default
33+
34+
* - nsec (usec, msec)
35+
- Fractional part of the last second. You can specify either nanoseconds (``nsec``), or microseconds (``usec``), or milliseconds (``msec``).
36+
Specifying two of these units simultaneously or all three ones lead to an error.
37+
- number
38+
- 0
39+
40+
* - sec
41+
- Seconds. Value range: 0 - 60.
42+
- number
43+
- 0
44+
45+
* - min
46+
- Minutes. Value range: 0 - 59.
47+
- number
48+
- 0
49+
50+
* - hour
51+
- Hours. Value range: 0 - 23.
52+
- number
53+
- 0
54+
55+
* - day
56+
- Day number. Value range: 1 - 31. The special value ``-1`` generates the last day of a particular month. [TBD link to examples]
57+
- number
58+
- 1
59+
60+
* - month
61+
- Month number. Value range: 1 - 12.
62+
- number
63+
- 1
64+
65+
* - year
66+
- Year
67+
- number
68+
- 1
69+
70+
* - timestamp
71+
- Timestamp, in seconds. Similar to the Unix timestamp, but can have a fractional part which is converted in nanoseconds in the resulting ``datetime`` object.
72+
If the fractional part for the last second is set via the ``nsec``, ``usec``, or ``msec`` units, the timestamp value should be integer otherwise an error occurs. [TBD link to examples]
73+
Timestamp is not allowed if you already set time and/or date via specific units, namely, ``sec``, ``min``, ``hour``, ``day``, ``month``, and ``year``.
74+
- number
75+
- 0
76+
77+
* - tzoffset
78+
- Time zone offset from UTC, in minutes. If both ``tzoffset`` and ``tz`` are specified, ``tz`` has the preference and the ``tzoffset`` value is ignored.
79+
- number
80+
- 0
81+
82+
* - tz
83+
- Time zone name according to the `tz database <https://en.wikipedia.org/wiki/Tz_database>`__.
84+
- string
85+
- -
86+
87+
.. _datetime-new-example:
88+
89+
**Examples:**
90+
91+
.. code-block:: tarantoolsession
92+
93+
tarantool> datetime.new {
94+
nsec = 123456789,
95+
96+
sec = 20,
97+
min = 25,
98+
hour = 18,
99+
100+
day = 20,
101+
month = 8,
102+
year = 2021,
103+
104+
tzoffset = 180
105+
}
106+
---
107+
- 2021-08-20T18:25:20.123456789+0300
108+
...
109+
110+
tarantool> datetime.new {
111+
nsec = 123456789,
112+
113+
sec = 20,
114+
min = 25,
115+
hour = 18,
116+
117+
day = 20,
118+
month = 8,
119+
year = 2021,
120+
121+
tzoffset = 60,
122+
tz = Europe/Moscow
123+
}
124+
---
125+
- 2021-08-20T18:25:20.123456789 Europe/Moscow
126+
...
127+
128+
tarantool> datetime.new {
129+
day = -1,
130+
month = 2,
131+
year = 2021,
132+
}
133+
---
134+
- 2021-02-28T00:00:00Z
135+
...
136+
137+
tarantool> datetime.new {
138+
timestamp = 1656664205.123,
139+
tz = 'Europe/Moscow'
140+
}
141+
---
142+
- 2022-07-01T08:30:05.122999906 Europe/Moscow
143+
...
144+
145+
tarantool> datetime.new {
146+
nsec = 123,
147+
148+
timestamp = 1656664205,
149+
150+
tz = 'Europe/Moscow'
151+
}
152+
---
153+
- 2022-07-01T08:30:05.000000123 Europe/Moscow
154+
...

‎doc/reference/reference_lua/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ This reference covers Tarantool's built-in Lua modules.
2626
console
2727
crypto
2828
csv
29+
datetime
2930
decimal
3031
digest
3132
errno

0 commit comments

Comments
 (0)