Skip to content

Commit e7b071c

Browse files
veod32veod32
authored
Document methods and logic of interval arithmetic in the datetime module
Closes #2835
1 parent ae9aaf0 commit e7b071c

File tree

6 files changed

+341
-13
lines changed

6 files changed

+341
-13
lines changed

‎doc/reference/reference_lua/datetime.rst

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,19 +28,35 @@ Below is a list of the ``datetime`` module functions and methods.
2828
* - :ref:`format() <datetime-format>`
2929
- Convert the standard presentation of a ``datetime`` object into a formatted string.
3030

31-
* - :ref:`totable() <datetime-totable>`
31+
* - :ref:`datetime_object:totable() <datetime-totable>`
3232
- Convert the information from a ``datetime`` object into the table format.
3333

3434
* - :ref:`set() <datetime-set>`
3535
- Update the field values in the existing ``datetime`` object.
3636

37+
* - :ref:`parse() <datetime-parse>`
38+
- Convert an input string with the date and time information into a ``datetime`` object.
39+
40+
* - :ref:`add() <datetime-add>`
41+
- Modify an existing datetime object by adding values of the input arguments.
42+
43+
* - :ref:`sub() <datetime-sub>`
44+
- Modify an existing datetime object by subtracting values of the input arguments.
45+
3746
* - :doc:`./datetime/interval_new`
3847
- Create an ``interval`` object from a table of time units.
3948

49+
* - :ref:`interval_object:totable() <interval-totable>`
50+
- Convert the information from an ``interval`` object into the table format.
51+
52+
* - :doc:`./datetime/interval_arithm`
53+
- Arithmetic operations with datetime and interval objects.
4054

4155
.. toctree::
4256
:hidden:
4357

4458
datetime/new
4559
datetime/datetime_object
4660
datetime/interval_new
61+
datetime/interval_object
62+
datetime/interval_arithm

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

Lines changed: 143 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ datetime_object
1111

1212
.. method:: totable()
1313

14-
Convert the information from the ``datetime`` object into the table format.
14+
Convert the information from a ``datetime`` object into the table format.
1515
Resulting table has the following fields:
1616

1717
.. container:: table
@@ -92,14 +92,14 @@ datetime_object
9292
9393
.. _datetime-format:
9494

95-
.. method:: format( ['convensions'] )
95+
.. method:: format( ['input_string'] )
9696

9797
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).
98+
The conversion specifications are the same as in the `strftime <https://www.freebsd.org/cgi/man.cgi?query=strftime&sektion=3>`__ library.
99+
Additional specification 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 conversions are used: `'%FT%T.%f%z'` (see the example below).
101101

102-
:param string convensions: string consisting of zero or more conversion specifications and ordinary characters
102+
:param string input_string: string consisting of zero or more conversion specifications and ordinary characters
103103

104104
:return: string with the formatted date and time information
105105
:rtype: string
@@ -243,3 +243,140 @@ datetime_object
243243
- 1970-01-01T03:00:00.125+0300
244244
...
245245
246+
.. _datetime-add:
247+
248+
.. method:: add( input[, { adjust } ] )
249+
250+
Modify an existing datetime object by adding values of the input argument.
251+
252+
:param table input: an :ref:`interval object <interval-new>` or an equivalent table (see **Example #1**)
253+
:param string adjust: defines how to round days in a month after an arithmetic operation.
254+
Possible values: ``none``, ``last``, ``excess`` (see **Example #2**). Defaults to ``none``.
255+
256+
:return: datetime_object
257+
:rtype: cdata
258+
259+
**Example #1:**
260+
261+
.. code-block:: tarantoolsession
262+
263+
tarantool> dt = datetime.new {
264+
day = 26,
265+
month = 8,
266+
year = 2021,
267+
tzoffset = 180
268+
}
269+
---
270+
...
271+
272+
tarantool> iv = datetime.interval.new {day = 7}
273+
---
274+
...
275+
276+
tarantool> dt, iv
277+
---
278+
- 2021-08-26T00:00:00+0300
279+
- +7 days
280+
...
281+
282+
tarantool> dt:add(iv)
283+
---
284+
- 2021-09-02T00:00:00+0300
285+
...
286+
287+
tarantool> dt:add{ day = 7 }
288+
---
289+
- 2021-09-09T00:00:00+0300
290+
...
291+
292+
.. _datetime-add-example2:
293+
294+
**Example #2:**
295+
296+
.. code-block:: tarantoolsession
297+
298+
tarantool> dt = datetime.new {
299+
day = 29,
300+
month = 2,
301+
year = 2020
302+
}
303+
---
304+
...
305+
306+
tarantool> dt:add{month = 1, adjust = 'none'}
307+
---
308+
- 2020-03-29T00:00:00Z
309+
...
310+
311+
tarantool> dt = datetime.new {
312+
day = 29,
313+
month = 2,
314+
year = 2020
315+
}
316+
---
317+
...
318+
319+
tarantool> dt:add{month = 1, adjust = 'last'}
320+
---
321+
- 2020-03-31T00:00:00Z
322+
...
323+
324+
tarantool> dt = datetime.new {
325+
day = 31,
326+
month = 1,
327+
year = 2020
328+
}
329+
---
330+
...
331+
332+
tarantool> dt:add{month = 1, adjust = 'exсess'}
333+
---
334+
- 2020-03-02T00:00:00Z
335+
...
336+
337+
.. _datetime-sub:
338+
339+
.. method:: sub( { input[, adjust ] } )
340+
341+
Modify an existing datetime object by subtracting values of the input argument.
342+
343+
:param table input: an :ref:`interval object <interval-new>` or an equivalent table (see **Example**)
344+
:param string adjust: defines how to round days in a month after an arithmetic operation.
345+
Possible values: ``none``, ``last``, ``excess``. Defaults to ``none``.
346+
The logic is similar to the one of the ``:add()`` method -- see :ref:`Example #2 <datetime-add-example2>`.
347+
348+
:return: datetime_object
349+
:rtype: cdata
350+
351+
**Example:**
352+
353+
.. code-block:: tarantoolsession
354+
355+
tarantool> dt = datetime.new {
356+
day = 26,
357+
month = 8,
358+
year = 2021,
359+
tzoffset = 180
360+
}
361+
---
362+
...
363+
364+
tarantool> iv = datetime.interval.new {day = 5}
365+
---
366+
...
367+
368+
tarantool> dt, iv
369+
---
370+
- 2021-08-26T00:00:00+0300
371+
- +5 days
372+
...
373+
374+
tarantool> dt:sub(iv)
375+
---
376+
- 2021-08-21T00:00:00+0300
377+
...
378+
379+
tarantool> dt:sub{ day = 1 }
380+
---
381+
- 2021-08-20T00:00:00+0300
382+
...

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

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
.. _interval_arithm:
2+
3+
Interval arithmetic
4+
===================
5+
6+
Since :doc:`2.10.0 </release/2.10.0>`.
7+
8+
The :doc:`datetime module </reference/reference_lua/datetime>` enables creating objects of two types: ``datetime`` and ``interval``.
9+
10+
If you need to shift the ``datetime`` object values, you can use either the modifier methods, that is, the :ref:`:add <datetime-add>` or :ref:`:sub <datetime-sub>` methods,
11+
or apply interval arithmetic using overloaded `+ (__add)` or `- (__sub)` methods.
12+
13+
``:add``/``:sub`` modify the current object, but ``+``/``-`` create copy of the object as the operation result.
14+
15+
In the interval operation, each of the interval subcomponents are sequentially calculated starting from the largest (``year``) to the smallest (``nsec``):
16+
17+
* ``year`` -- years
18+
* ``month`` -- months
19+
* ``week`` -- weeks
20+
* ``day`` -- days
21+
* ``hour`` -- hours
22+
* ``min`` -- minutes
23+
* ``sec`` -- seconds
24+
* ``nsec`` -- nanoseconds.
25+
26+
If results of the operation exceed the allowed range for any of the components, an exception is raised.
27+
28+
The ``datetime`` and ``interval`` objects can participate in arithmetic operations:
29+
30+
* The sum of two intervals is an interval object, which fields are sum of each particular component of operands.
31+
32+
* The result of subtraction of two intervals is similar: it's an interval object where each subcomponent is the result of subtraction of particular fields in the original operands.
33+
34+
* If you add datetime and interval objects, the result is a datetime object. Addition is being performed in a determined order from the largest component (``year``) to the smallest (``nsec``).
35+
36+
* Subtraction of two datetime objects produce an interval object. Difference of two time values is performed not as difference of the epoch seconds,
37+
but as difference of all the subcomponents, that is, years, months, days, hours, minutes, and seconds.
38+
39+
* An untyped table object can be used in each context where the typed datetime or interval objects are used if left operand is typed object with overloaded operation of ``+`` or ``-``.
40+
41+
The matrix of the ``addition`` operands eligibility and their result types:
42+
43+
.. container:: table
44+
45+
.. list-table::
46+
:widths: 25 25 25 25
47+
:header-rows: 1
48+
49+
* -
50+
- datetime
51+
- interval
52+
- table
53+
54+
* - **datetime**
55+
-
56+
- datetime
57+
- datetime
58+
59+
* - **interval**
60+
- datetime
61+
- interval
62+
- interval
63+
64+
* - **table**
65+
-
66+
-
67+
-
68+
69+
The matrix of the ``subtraction`` operands eligibility and their result types:
70+
71+
.. container:: table
72+
73+
.. list-table::
74+
:widths: 25 25 25 25
75+
:header-rows: 1
76+
77+
* -
78+
- datetime
79+
- interval
80+
- table
81+
82+
* - **datetime**
83+
- interval
84+
- datetime
85+
- datetime
86+
87+
* - **interval**
88+
-
89+
- interval
90+
- interval
91+
92+
* - **table**
93+
-
94+
-
95+
-

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

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -3,22 +3,22 @@
33
datetime.interval.new()
44
=======================
55

6-
.. function:: datetime.interval.new( [{ units }] )
6+
.. function:: datetime.interval.new( [{ input }] )
77

88
Since :doc:`2.10.0 </release/2.10.0>`.
99

1010
Create an object of the :ref:`interval type <index-box_interval>` from a table of time units.
1111
See :ref:`description of units <interval-new-args>` and :ref:`examples <interval-new-example>` below.
1212

13-
:param table units: Table of :ref:`time units <interval-new-args>`. For all possible time units, the values are not restricted.
13+
:param table input: Table with :ref:`time units and parameters<interval-new-args>`. For all possible time units, the values are not restricted.
1414
If an empty table or no arguments are passed, the ``interval`` object with the default value ``0 seconds`` is created.
1515

16-
:return: :doc: interval object
16+
:return: interval_object
1717
:rtype: cdata
1818

1919
.. _interval-new-args:
2020

21-
**Possible input time units for ``datetime.interval.new()**
21+
**Possible input time units and parameters for ``datetime.interval.new()**
2222

2323
.. container:: table
2424

@@ -72,6 +72,11 @@ datetime.interval.new()
7272
- number
7373
- 0
7474

75+
* - adjust
76+
- Defines how to round days in a month after an arithmetic operation.
77+
- string
78+
- 'none'
79+
7580
.. _interval-new-example:
7681

7782
**Examples:**

0 commit comments

Comments
 (0)