Create an object of the datetime type from a table of time units

datetime.now()

Create an object of the datetime type with the current date and time

datetime.is_datetime()

Check whether the specified value is a datetime object

datetime.parse()

Convert an input string with the date and time information into a datetime object

datetime.interval.is_interval()

Check whether the specified value is an interval object

datetime.interval.new()

Create an object of the interval type from a table of time units

Properties

datetime.TZ

A Lua table that maps timezone names and abbreviations to its index and vice-versa.

Methods

datetime_object:add()

Modify an existing datetime object by adding values of the input argument

datetime_object:format()

Convert the standard datetime object presentation into a formatted string

datetime_object:set()

Update the field values in the existing datetime object

datetime_object:sub()

Modify an existing datetime object by subtracting values of the input argument

datetime_object:totable()

Convert the information from a datetime object into the table format

interval_object:totable()

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. Value range: 0 - 60. A leap second is supported at the most basic level, see the section leap second.

number

0

min

Minutes. Value range: 0 - 59.

number

0

hour

Hours. Value range: 0 - 23.

number

0

day

Day number. Value range: 1 - 31. The special value -1 generates the last day of a particular month (see example below).

number

1

month

Month number. Value range: 1 - 12.

number

1

year

Year.

number

1970

timestamp

Timestamp, in seconds. Similar to the Unix timestamp, but can have a fractional part that is converted in nanoseconds in the resulting datetime object. 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. The timestamp is not allowed if you already set time and/or date via specific units, namely, sec, min, hour, day, month, and year.

number

0

tzoffset

A time zone offset from UTC, in minutes. Value range: -720 - 840 inclusive. If both tzoffset and tz are specified, tz has the preference and the tzoffset value is ignored. See a section timezone.

number

0

tz

A time zone name according to the Time Zone Database. See the timezone section.

string

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

adjust :

Defines how to round days in a month after an arithmetic operation.

string

'none'

Examples:**

` tarantoolses rantool> datet

ion me.interval.new()

0 seconds .

rantool> datet mont year } +1 years, 6 mo .

me.interval.new { = 6, = 1 ths

rantool> datet day } -1 days . `

me.interval.new { -1

nce: ``2.11.0 <`

release/2.11.0>`

Lua table that breviations (l imezone](timez

maps timezone names (like Europe/M ke MSK`) to its index and vice-ver ne) section.

scow`) and tim a. See the

zone

` tarantoolses rantool> datet 947 .

ion me.TZ['Europe/Moscow']

rantool> datet Europe/Moscow . ` :

me.TZ[947]

ts

ect

atetime_object datetime obj

ct.

: method d( input[, {

djust } ] )

dify an existi gument. See al rformed taking e set, see the g datetime object by adding values o: [interval_arithm](interval_arith tzdatainto account, whentzoffs timezone.`

f the input ). The additio tortz` fie

is ds

ram table inpu an [interval **Example #1

object](#interval_obj) or an equival *)

nt table (see

ram string adj defines how Possible val Defaults to st o round days in a month after an ar es: ``none, last, excess (see * none.`

thmetic operat Example #2**).

on.

turn datetime_obj

ct

ype cdata

Example #1:**

` tarantoolses rantool> dt = day mont year tzof } .

ion atetime.new { 26, = 8, = 2021, set = 180

rantool> iv = .

atetime.interval.new {day = 7}

rantool> dt, i 2021-08-26T00: +7 days . 0:00+0300

rantool> dt:ad 2021-09-02T00: .

(iv) 0:00+0300

rantool> dt:ad 2021-09-09T00: . `

{ day = 7 } 0:00+0300

Example #2:**

` tarantoolses rantool> dt = day mont year } .

ion atetime.new { 29, = 2, = 2020

rantool> dt:ad 2020-03-29T00: .

{month = 1, adjust = 'none'} 0:00Z

rantool> dt = day mont year } .

atetime.new { 29, = 2, = 2020

rantool> dt:ad 2020-03-31T00: .

{month = 1, adjust = 'last'} 0:00Z

rantool> dt = day mont year } .

atetime.new { 31, = 1, = 2020

rantool> dt:ad 2020-03-02T00: . ` :

{month = 1, adjust = 'excess'} 0:00Z

: method rmat( ['inpu

_string'] )

nvert the stan ring. The conv trftime](https nction. Additi ich also allow actional part: guments are se '%FT%T.%f%z']

ard datetime object presentation rsion specifications are the same a //www.freebsd.org/cgi/man.cgi?query nal specification for nanoseconds i a modifier to control the output p %5f (see the example for the method, the default conver .title-ref} (see the example below)

nto a formatte in the strftime&sekti [%f]{.title-r ecision of elow). If no ions are used:

n=3) f}

ram string inp string consi ordinary cha

t_string ting of zero or more conversion spe acters

ifications and

turn string with

he formatted date and time informat

on

ype string

Example:**

` tarantoolses rantool> dt = nsec

ion atetime.new { = 123456789,

sec min hour

20, 25, = 18,

day mont year

20, = 8, = 2021,

tzof } .

set = 180

rantool> dt:fo 20.08.21 18:25 .

mat('%d.%m.%y %H:%M:%S.%5f') 20.12345

rantool> dt:fo 2021-08-20T18: .

mat() 5:20.123456789+0300

rantool> dt:fo 2021-08-20T18: . ` :

mat('%FT%T.%f%z') 5:20.123456789+0300

: method t( [{ units }

] )

date the field

values in the existing datetime o

ject.

ram table unit Table of tim same as for

units. The [time units](datetime-n he datetime.new() function.

w-args) are th

turn updated date

ime_object

ype cdata

Example:**

` tarantoolses rantool> dt = nsec

ion atetime.new { = 123456789,

sec min hour

20, 25, = 18,

day mont year

20, = 8, = 2021,

tzof }

set = 180

rantool> dt:se 2021-08-20T18: .

{msec = 567} 5:20.567+0300

rantool> dt:se 2021-08-20T18: . ` :

{tzoffset = 60} 5:20.567+0100

: method b( { input[,

djust ] } )

dify an existi gument. See al performed tak elds are set, g datetime object by subtracting va o: [interval_arithm](interval_arith ng tzdatainto account, whentzo ee the timezone.`

ues of the inp ). The subtrac fsetortz`

t ion

ram table inpu an [interval Example)

object](#interval_obj) or an equival

nt table (see

ram string adj defines how Possible val logic is sim [Example #2] st o round days in a month after an ar es: ``none, last, excess. Defau lar to the one of the :add() meth datetime-add-example2).

thmetic operat ts to none. d -- see

on. he

turn datetime_obj

ct

ype cdata

Example:**

` tarantoolses rantool> dt = day mont year tzof } .

ion atetime.new { 26, = 8, = 2021, set = 180

rantool> iv = .

atetime.interval.new {day = 5}

rantool> dt, i 2021-08-26T00: +5 days . 0:00+0300

rantool> dt:su 2021-08-21T00: .

(iv) 0:00+0300

rantool> dt:su 2021-08-20T00: . ` :

{ day = 1 } 0:00+0300

ethod table()

nvert the info e resulting ta

mation from a datetime object int le has the following fields:

the table for

at.

Field name nsec

Description Nanoseconds. Number.

sec

Seconds. Number.

min

Minutes. Number.

hour

Hours. Number.

day

Day number.

month

Month number.

year

Year. Number.

wday

Days since the beginning of is Sunday as for `os.date('*

he week. Numbe ')`.

. 1

yday

Days since the beginning of

he year. Numbe

.

timestamp

Timestamp, in seconds. Numbe

.

isdst

Is the DST (Daylight Saving the date, see a section [tim Boolean.

ime) applicabl zone](timezone

for .

tzoffset

Time zone offset from UTC, s timezone. Number

e a section

tz :

Time zone name or abbreviati timezone. String

n, see a secti

n

turn table with t

e date and time parameters

ype table

Example:**

` tarantoolses rantool> dt = sec min hour

ion atetime.new { 20, 25, = 18,

day mont year tz = } .

20, = 8, = 2021, 'MAGT',

rantool> dt:to tz: 'MAGT' sec: 20 min: 25 yday: 232 day: 20 nsec: 0 isdst: false wday: 6 tzoffset: 600 month: 8 year: 2021 hour: 18 . `

able()

ect

nterval_object interval ob

ect.

ethod table()

nvert the info e resulting ta

mation from an interval object in le has the following fields:

o the table fo

mat.

Field name nsec

Description Nanoseconds

sec

Seconds

min

Minutes

hour

Hours

day

Day number

month

Month number

year

Year

week

Week number

adjust :

Defines how to round days in arithmetic operation.

a month after

n

turn table with t

e date and time parameters

ype table

Example:**

` tarantoolses rantool> iv = .

ion atetime.interval.new{month = 1, adj

st = 'last'}

rantool> iv:to adjust: last sec: 0 nsec: 0 day: 0 week: 0 hour: 0 month: 1 year: 0 min: 0 . `

able()

Datetime and

nterval arithmetic

e datetime m atetimeand

dule enables creating of objects of nterval`. two types:

you need to s e modifier met [datetime_obj ithmetic using

ift the datetime object values, y ods, that is, the datetime_object: ct:sub() methods, or overloaded + (__add) or - (`_

u can use eith dd()](datetime apply interval sub`) methods.

r add)

atetime_object ject, but +/

add()/datetime_object:sub() modi - create copy of the object as the

y the current operation resu

t.

the interval quentially cal allest (nsec

peration, each of the interval subc ulated starting from the largest (` :

mponents is ear`) to the

year -- yea month -- mo week -- wee day -- days hour -- hou min -- minu sec -- seco nsec -- nan

s ths s s es ds seconds

the results o mponents, an e

the operation exceed the allowed r ception is raised.

nge for any of

the

e datetime a erations:

d interval objects can participat

in arithmetic

The sum of two sum of each pa The result of interval objec of particular If you add dat object. The ad largest compon Subtraction of difference of the epoch seco is, years, mon An untyped tab datetime or in object with an

intervals is an interval object, wh ticular component of operands. ubtraction of two intervals is simi where each subcomponent is the res ields in the original operands. time and interval objects, the resu ition is performed in a determined nt (year) to the smallest (nsec two datetime objects produces an in wo time values is performed not as ds, but as difference of all the su hs, days, hours, minutes, and secon e object can be used in each contex erval objects are used if the left overloaded operation of + or -. se fields are ar: it's an lt of subtract t is a datetim rder from the . erval object. he difference components, th s. where the typ perand is a ty

he on he f t d ed

e matrix of th pes:

addition operands eligibility an

their result

datetime

datetime interval unsupported datetime

table datetime

interval :

datetime interval

interval

e matrix of th pes:

subtraction operands eligibility

and their resu

t

datetime

datetime interval interval datetime

table datetime

interval :

unsupported interval

interval

e subtraction zdata` into ac

nd addition of datetime objects are ount tzoffset or tz fields are performed taki et:

g

tarantoolses rantool> datet -180 minutes .

ion me.new({tz='MSK'}) - datetime.new({

z='UTC'})

Datetime and

nterval comparison

you need to c n use standard d <=. These tamethods to c

mpare the datetime and interval Lua relational operators: ==, ~= perators use the overloaded __eq`, mpare values.

object values, , >, <, > _lt, and

you , le

pport for rela nce `2.11.0 </

ional operators for interval obje elease/2.11.0>`.

ed

Example 1:**

` tarantoolses rantool> dt1 = .

ion datetime.new({ year = 2010 })

rantool> dt2 = .

datetime.new({ year = 2024 })

rantool> dt1 = false .

dt2

rantool> dt1 < true . `

dt2

Example 2:**

` tarantoolses rantool> iv1 = .

ion datetime.interval.new({month = 1})

rantool> iv2 = .

datetime.interval.new({month = 2})

rantool> iv1 < true . `

iv2

Leap second

eap seconds](h e-second adjus ep a system/'s rth/'s rotatio ents, and due predictable. tps://en.wikipedia.org/wiki/Leap_se ment of Coordinated Universal Time time of day close to the mean solar speed varies in response to climat o this, UTC leap seconds are irregu

ond) are a per UTC) in order time. However, c and geologic arly spaced an

odic o the l

rantool includ tabase](https: scription file dule [tarantoo

s the Time Zone /www.iana.org/time-zones) that besi also contains a leapseconds file. to get a used v

es the time zo ou can use the rsion of `tzda

e Lua a`.

e datetime m

dule supports leap seconds at the m

st basic level

The function [ input string w

atetime.parse()](#datetime-parse) co th 60 seconds:

rectly parses

n