Skip to main content

Time

The time library provides functionality for measuring and displaying time.

The calendrical calculations always assume a Gregorian calendar, with no leap seconds.

time.now​

-- @return object
function time.now()
end

Returns timestamp object with current local time. The timezone is as site timezone.

time.new​

-- @param params table
-- @return object
function time.new(params)
end

Return timestamp object with passed as a table parameters. The timezone is as site timezone.

Parameters are: year, month, day, hour, minute, second, millisecond. The year, month, and day are required, other parameters are optional and assumed to be zero if ommited. The month should be one of month constants. The hour, minute, second, and millisecond values may be outside their usual ranges and will be normalized. For example, October 32 converts to November 1.

Example​

local timestamp = time.new({
   year = 2025, month = time.DECEMBER, day = 23,
   hour = 15, minute = 04, second = 05, millisecond = 100
})
enapter.log("Timestamp: "..tostring(timestamp)) -- Timestamp: 2025-12-23T15:04:05.1Z

time.unix​

function time.unix(sec)
end

Returns timestamp object corresponding to the given Unix time (seconds since January 1, 1970 UTC). The timezone is as site timezone.

Constants​

Duration​

time.MILLISECOND, time.SECOND, time.MINUTE, time.HOUR

Weekdays​

time.MONDAY, time.TUESDAY, time.WEDNESDAY, time.THURSDAY, time.FRIDAY, time.SATURDAY, time.SUNDAY

Months​

time.JANUARY, time.FEBRUARY, time.MARCH, time.APRIL, time.MAY, time.JUNE, time.JULY, time.AUGUST, time.SEPTEMBER, time.OCTOBER, time.NOVEMBER, time.DECEMBER

timestamp object​

timestamp:unix​

-- @return number
function timestamp:unix()
end

Return timestamp as a Unix time, the number of seconds elapsed since January 1, 1970 UTC. The result does not depend on the timezone.

timestamp:day​

-- @return number
function timestamp:day()
end

Returns the day of the month specified by the timestamp.

timestamp:month​

-- @return string
function timestamp:month()
end

Returns the month of the year specified by the timestamp.

The returned value corresponds to one of the month constants, such as time.JANUARY, time.FEBRUARY, etc.

timestamp:year​

-- @return number
function timestamp:year()
end

Returns the year specified by the timestamp.

timestamp:hour​

-- @return number
function timestamp:hour()
end

Returns the hour within the day specified by the timestamp, in the range [0, 23].

timestamp:minute​

-- @return number
function timestamp:minute()
end

Returns the minute offset within the hour specified by timestamp, in the range [0, 59].

timestamp:second​

-- @return number
function timestamp:second()
end

Returns the second offset within the minute specified by timestamp, in the range [0, 59].

timestamp:millisecond​

-- @return number
function timestamp:millisecond()
end

Returns the millisecond offset within the second specified by timestamp, in the range [0, 999].

timestamp:weekday​

-- @return string
function timestamp:weekday()
end

Returns the day of the week specified by timestamp.

The returned value corresponds to one of the weekday constants, such as time.MONDAY, time.TUESDAY, etc.

Example​

scheduler.add(time.HOUR, function()
   local now = time.now()
   if now:weekday() == time.MONDAY then
      -- do something every Monday
   end
end)

timestamp:year_day​

-- @return number
function timestamp:year_day()
end

Returns the day of the year specified by timestamp, in the range [1, 365] for non-leap years, and [1, 366] in leap years.

timestamp:add​

-- @param duration number milliseconds to add
-- @return timestamp
function timestamp:add(duration)
end

Returns the new timestamp by adding duration millisecond to the given timestamp. Use duration constants to conveniently build time durations.

Use arithmetic operators for shorthand usage of this method.

Example​

local ts1 = time.now()
local ts2 = ts1:add(time.HOUR + 3 * time.MINUTE)

enapter.log("ts1: "..tostring(ts1)..", ts2: "..tostring(t2))
-- ts1: 2025-12-23T15:04:05.1Z, ts2: 2025-12-23T16:07:05.1Z

timestamp:sub​

-- @param other number|timestamp
-- @return timestamp
function timestamp:sub(arg)
end

If arg is a number, returns a new timestamp decreased by the given number of milliseconds. Use duration constants to conveniently build time durations.

If arg is a timestamp, returns the difference in milliseconds between the given timestamp and arg.

Use arithmetic operators for shorthand usage of this method.

Example​

local ts1 = time.now()
local ts2 = ts1:sub(time.HOUR + 3 * time.MINUTE)

enapter.log("ts1: "..tostring(ts1)..", ts2: "..tostring(ts2))
enapter.log("difference: "..tostring(ts1:sub(ts2)).."ms")
-- ts1: 2025-12-23T15:04:05.1Z, ts2: 2025-12-23T14:01:05.1Z
-- difference: 3780000ms

timestamp:is_before​

-- @param ts timestamp
-- @return boolean
function timestamp:is_before(ts)
end

Returns true if the given timstamp is before passed timestamp. Returns false otherwise.

Use arithmetic operators for shorthand usage of this method.

Example​

local ts1 = time.now()
local ts2 = ts1 + time.MILLISECOND

enapter.log("ts1 < ts2: "..tostring(ts1:is_before(ts2)))
-- ts1 < ts2: true

timestamp:is_after​

-- @param ts timestamp
-- @return boolean
function timestamp:is_after(ts)
end

Returns true if the given timstamp is after passed timestamp. Returns false otherwise.

Use arithmetic operators for shorthand usage of this method.

timestamp:is_equal​

-- @param ts timestamp
-- @return boolean
function timestamp:is_equal(ts)
end

Returns true if the given timstamp is equal to passed timestamp. Returns false otherwise.

Use arithmetic operators for shorthand usage of this method.

Example​

local ts1 = time.now()
local ts2 = ts1 + time.MINUTE - 60 * time.SECOND
enapter.log("ts1 == ts2: "..tostring(ts1:is_equal(ts2)))
-- ts1 == ts2: true

timestamp:is_clock_between​

-- @param since string in "hh:mm:ss" or "hh:mm:ss.ms" 24h format
-- @param till string in "hh:mm:ss" or "hh:mm:ss.ms" 24h format
-- @return boolean
function timestamp:is_clock_between(since, till)
end

Check if the given timestamp is between the given clock interval boundaries. Interval is a timeframe in a clockwise direction. The since and from strings must be in hh:mm:ss or hh:mm:ss.ms 24h format, like 15:05:00, 15:4:5.999.

Example​

local timestamp = time.new({
   year = 2025, month = time.DECEMBER, day = 23,
   hour = 15, minute = 04, second = 05, millisecond = 100
})

local result = timestamp:is_clock_between("15:00:00", "15:05:00")
enapter.log(tostring(timestamp).." is between 15:00:00 and 15:05:00: "..tostring(result))
-- 2025-12-23T15:04:05.1Z is between 15:00:00 and 15:05:00: true

local result = timestamp:is_clock_between("15:00:00", "14:00:00")
enapter.log(tostring(timestamp).." is between 15:00:00 and 14:00:00: "..tostring(result))
-- 2025-12-23T15:04:05.1Z is between 15:00:00 and 14:00:00: true

local result = timestamp:is_clock_between("15:04:05.101", "15:04:05.099")
enapter.log(tostring(timestamp).." is between 15:04:05.101 and 15:04:05.099: "..tostring(result))
-- 2025-12-23T15:04:05.1Z is between 15:04:05.101 and 15:04:05.099: false

Arithmetic operators​

Operators -, +, <, >, <=, >=, ==, != are supported for time manipulation.

local ts1 = time.now()
local ts2 = ts1 + time.MINUTE - 60 * time.SECOND
enapter.log("ts1 < ts2: "..tostring(ts1 < ts2))   -- ts1 < ts2: false
enapter.log("ts1 > ts2: "..tostring(ts1 > ts2))   -- ts1 > ts2: false
enapter.log("ts1 <= ts2: "..tostring(ts1 <= ts2)) -- ts1 <= ts2: true
enapter.log("ts1 >= ts2: "..tostring(ts1 >= ts2)) -- ts1 >= ts2: true
enapter.log("ts1 == ts2: "..tostring(ts1 == ts2)) -- ts1 == ts2: true
enapter.log("ts1 != ts2: "..tostring(ts1 != ts2)) -- ts1 != ts2: false

All Rights Reserved © 2025 Enapter AG.

Privacy Policy|Cookies Policy