Skip to content

Commit de58780

Browse files
veod32veod32
authored
Add a new section for the datetime module with the description of its main functions and methods
Closes #2411, #2576
1 parent ef33b9a commit de58780

File tree

5 files changed

+544
-0
lines changed

5 files changed

+544
-0
lines changed

‎doc/reference/reference_lua/datetime.rst

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
2+
Module datetime
3+
===============
4+
5+
Since :doc:`2.10.0 </release/2.10.0>`.
6+
7+
The ``datetime`` module provides support for the :ref:`datetime and interval data types <index-box_datetime>`.
8+
It allows creating the date and time values either via the object interface
9+
or via parsing string values conforming to the 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 time units.
27+
28+
* - :ref:`format() <datetime-format>`
29+
- Convert the standard presentation of a ``datetime`` object into a formatted string.
30+
31+
* - :ref:`totable() <datetime-totable>`
32+
- Convert the information from a ``datetime`` object into the table format.
33+
34+
* - :ref:`set() <datetime-set>`
35+
- Update the field values in the existing ``datetime`` object.
36+
37+
* - :doc:`./datetime/interval_new`
38+
- Create an ``interval`` object from a table of time units.
39+
40+
41+
.. toctree::
42+
:hidden:
43+
44+
datetime/new
45+
datetime/datetime_object
46+
datetime/interval_new

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

Lines changed: 245 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,245 @@
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+
Convert the information from the ``datetime`` object into the table format.
15+
Resulting table has the following fields:
16+
17+
.. container:: table
18+
19+
.. list-table::
20+
:widths: 30 70
21+
:header-rows: 1
22+
23+
* - Field name
24+
- Description
25+
26+
* - nsec
27+
- Nanosecods
28+
29+
* - sec
30+
- Seconds
31+
32+
* - min
33+
- Minutes
34+
35+
* - hour
36+
- Hours
37+
38+
* - day
39+
- Day number
40+
41+
* - month
42+
- Month number
43+
44+
* - year
45+
- Year
46+
47+
* - wday
48+
- Days since the beginning of the week
49+
50+
* - yday
51+
- Days since the beginning of the year
52+
53+
* - isdst
54+
- Is the DST (Daylight saving time) applicable for the date. Boolean.
55+
56+
* - tzoffset
57+
- Time zone offset from UTC
58+
59+
:return: table with the date and time parameters
60+
:rtype: table
61+
62+
**Example:**
63+
64+
.. code-block:: tarantoolsession
65+
66+
tarantool> dt = datetime.new {
67+
sec = 20,
68+
min = 25,
69+
hour = 18,
70+
71+
day = 20,
72+
month = 8,
73+
year = 2021,
74+
}
75+
---
76+
...
77+
78+
tarantool> dt:totable()
79+
---
80+
- sec: 20
81+
min: 25
82+
yday: 232
83+
day: 20
84+
nsec: 0
85+
isdst: false
86+
wday: 6
87+
tzoffset: 0
88+
month: 8
89+
year: 2021
90+
hour: 18
91+
...
92+
93+
.. _datetime-format:
94+
95+
.. method:: format( ['convensions'] )
96+
97+
Convert the standard ``datetime`` object presentation into a formatted string.
98+
The formatting convension specifications are the same as in the `strftime <https://www.freebsd.org/cgi/man.cgi?query=strftime&sektion=3>`__ library.
99+
Additional convension for nanoseconds is `%f` which also allows a modifier to control the output precision of fractional part: `%5f` (see the example below).
100+
If no arguments are set for the method, the default convensions are used: `'%FT%T.%f%z'` (see the example below).
101+
102+
:param string convensions: string consisting of zero or more conversion specifications and ordinary characters
103+
104+
:return: string with the formatted date and time information
105+
:rtype: string
106+
107+
**Example:**
108+
109+
.. code-block:: tarantoolsession
110+
111+
tarantool> dt = datetime.new {
112+
nsec = 123456789,
113+
114+
sec = 20,
115+
min = 25,
116+
hour = 18,
117+
118+
day = 20,
119+
month = 8,
120+
year = 2021,
121+
122+
tzoffset = 180
123+
}
124+
---
125+
...
126+
127+
tarantool> dt:format('%d.%m.%y %H:%M:%S.%5f')
128+
---
129+
- 20.08.21 18:25:20.12345
130+
...
131+
132+
tarantool> dt:format()
133+
---
134+
- 2021-08-20T18:25:20.123456789+0300
135+
...
136+
137+
tarantool> dt:format('%FT%T.%f%z')
138+
---
139+
- 2021-08-20T18:25:20.123456789+0300
140+
...
141+
142+
.. _datetime-set:
143+
144+
.. method:: set( [{ units }] )
145+
146+
Update the field values in the existing ``datetime`` object.
147+
148+
:param table units: Table of time units. The :ref:`time units <datetime-new-args>` are the same as for the ``datetime.new()`` function.
149+
150+
:return: updated datetime_object
151+
:rtype: cdata
152+
153+
**Example:**
154+
155+
.. code-block:: tarantoolsession
156+
157+
tarantool> dt = datetime.new {
158+
nsec = 123456789,
159+
160+
sec = 20,
161+
min = 25,
162+
hour = 18,
163+
164+
day = 20,
165+
month = 8,
166+
year = 2021,
167+
168+
tzoffset = 180
169+
}
170+
171+
tarantool> dt:set {msec = 567}
172+
---
173+
- 2021-08-20T18:25:20.567+0300
174+
...
175+
176+
tarantool> dt:set {tzoffset = 60}
177+
---
178+
- 2021-08-20T18:25:20.567+0100
179+
...
180+
181+
.. _datetime-parse:
182+
183+
.. method:: parse( 'input_string'[, {format, tzoffset} ] )
184+
185+
Convert an input string with the date and time information into a ``datetime`` object.
186+
The input string should be formatted according to one of the following standards:
187+
188+
* ISO 8601
189+
* RFC 3339
190+
* extended `strftime <https://www.freebsd.org/cgi/man.cgi?query=strftime&sektion=3>`__ -- see description of the :ref:`format() <datetime-format>` for details.
191+
192+
:param string input_string: string with the date and time information.
193+
:param string format: indicator of the input_sting format. Possible values: 'iso8601', 'rfc3339', or ``strptime``-like format string.
194+
If no value is set, the default formating is used.
195+
:param number tzoffset: time zone offset from UTC, in minutes.
196+
197+
:return: a datetime_object
198+
:rtype: cdata
199+
200+
**Example:**
201+
202+
.. code-block:: tarantoolsession
203+
204+
tarantool> t = datetime.parse('1970-01-01T00:00:00Z')
205+
206+
tarantool> t
207+
---
208+
- 1970-01-01T00:00:00Z
209+
...
210+
211+
tarantool> t = datetime.parse('1970-01-01T00:00:00', {format = 'iso8601', tzoffset = 180})
212+
213+
tarantool> t
214+
---
215+
- 1970-01-01T00:00:00+0300
216+
...
217+
218+
tarantool> t = datetime.parse('2017-12-27T18:45:32.999999-05:00', {format = 'rfc3339'})
219+
220+
tarantool> t
221+
---
222+
- 2017-12-27T18:45:32.999999-0500
223+
...
224+
225+
tarantool> T = datetime.parse('Thu Jan 1 03:00:00 1970', {format = '%c'})
226+
227+
tarantool> T
228+
---
229+
- 1970-01-01T03:00:00Z
230+
...
231+
232+
tarantool> T = datetime.parse('12/31/2020', {format = '%m/%d/%y'})
233+
234+
tarantool> T
235+
---
236+
- 2020-12-31T00:00:00Z
237+
...
238+
239+
tarantool> T = datetime.parse('1970-01-01T03:00:00.125000000+0300', {format = '%FT%T.%f%z'})
240+
241+
tarantool> T
242+
---
243+
- 1970-01-01T03:00:00.125+0300
244+
...
245+

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

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
.. _datetime-new:
2+
3+
datetime.interval.new()
4+
=======================
5+
6+
.. function:: datetime.interval.new( [{ units }] )
7+
8+
Since :doc:`2.10.0 </release/2.10.0>`.
9+
10+
Create an object of the :ref:`interval type <index-box_interval>` from a table of time units.
11+
See :ref:`description of units <interval-new-args>` and :ref:`examples <interval-new-example>` below.
12+
13+
:param table units: Table of :ref:`time units <interval-new-args>`. For all possible time units, the values are not restricted.
14+
If an empty table or no arguments are passed, the ``interval`` object with the default value ``0 seconds`` is created.
15+
16+
:return: :doc: interval object
17+
:rtype: cdata
18+
19+
.. _interval-new-args:
20+
21+
**Possible input time units for ``datetime.interval.new()**
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
42+
- number
43+
- 0
44+
45+
* - min
46+
- Minutes
47+
- number
48+
- 0
49+
50+
* - hour
51+
- Hours
52+
- number
53+
- 0
54+
55+
* - day
56+
- Day number
57+
- number
58+
- 0
59+
60+
* - week
61+
- Week number
62+
- number
63+
- 0
64+
65+
* - month
66+
- Month number
67+
- number
68+
- 0
69+
70+
* - year
71+
- Year
72+
- number
73+
- 0
74+
75+
.. _interval-new-example:
76+
77+
**Examples:**
78+
79+
.. code-block:: tarantoolsession
80+
81+
tarantool> datetime.interval.new()
82+
83+
---
84+
- 0 seconds
85+
...
86+
87+
tarantool> datetime.interval.new {
88+
month = 6,
89+
year = 1
90+
}
91+
---
92+
- +1 years, 6 months
93+
...
94+
95+
tarantool> datetime.interval.new {
96+
day = -1
97+
}
98+
---
99+
- -1 days
100+
...

0 commit comments

Comments
 (0)