Date

Source: shiva-fw/libs/date/init.lua

Immutable date/time objects with arithmetic, comparison, and formatting. All arithmetic methods return new DateObject instances — the original is never mutated.

Availability

Date is a global in every shiva module (loaded by sh_init.lua). No import required.

Static Constructors

Date.now()

Current date and time.

local now = Date.now()

Date.today()

Today at midnight (00:00:00).

local today = Date.today()

Date.create(year, month, day, hour?, minute?, second?)

Build a date from components. Time components default to 0.

local d = Date.create(2024, 6, 15)
local d = Date.create(2024, 6, 15, 14, 30, 0)

Date.parse(str)

Parse a date string. Supported formats: 'YYYY-MM-DD' and 'YYYY-MM-DD HH:MM:SS' / 'YYYY-MM-DDTHH:MM:SS'.

local d = Date.parse('2024-06-15')
local d = Date.parse('2024-06-15T14:30:00')

Date.fromTimestamp(ts)

Create from a Unix timestamp.

local d = Date.fromTimestamp(os.time())

Date.isLeapYear(year)

Date.isLeapYear(2024)  -- true

Date.daysInMonth(year, month)

Date.daysInMonth(2024, 2)  -- 29

Date.diff(a, b, unit)

Difference between two DateObjects (a − b) in 'seconds', 'minutes', 'hours', or 'days'.

local days = Date.diff(Date.now(), pastDate, 'days')

Instance Getters

local d = Date.now()
d:timestamp()   -- Unix timestamp (integer)
d:year()        -- e.g. 2024
d:month()       -- 1–12
d:day()         -- 1–31
d:hour()        -- 0–23
d:minute()      -- 0–59
d:second()      -- 0–59
d:dayOfWeek()   -- 1 (Sunday) – 7 (Saturday)
d:dayOfYear()   -- 1–366
d:isLeapYear()  -- boolean
d:daysInMonth() -- integer

Formatting

:format(pattern)

Format using an os.date pattern string.

d:format('%Y-%m-%d')   -- '2024-06-15'
d:format('%H:%M:%S')   -- '14:30:00'

:toISO()

ISO 8601: 'YYYY-MM-DDTHH:MM:SS'

:toDateString()

Date only: 'YYYY-MM-DD'

:toTimeString()

Time only: 'HH:MM:SS'

Arithmetic

All methods return a new DateObject.

d:addSeconds(n)    d:subSeconds(n)
d:addMinutes(n)    d:subMinutes(n)
d:addHours(n)      d:subHours(n)
d:addDays(n)       d:subDays(n)
d:addMonths(n)     d:subMonths(n)   -- clamps to last valid day
d:addYears(n)      d:subYears(n)    -- clamps Feb 29 on non-leap years

Comparison

d:isBefore(other)    -- boolean
d:isAfter(other)     -- boolean
d:isSame(other)      -- exact timestamp equality
d:isSameDay(other)   -- same calendar day

Difference (instance methods)

d:diffInSeconds(other)
d:diffInMinutes(other)
d:diffInHours(other)
d:diffInDays(other)

Period Boundaries

d:startOfDay()     -- 00:00:00
d:endOfDay()       -- 23:59:59
d:startOfMonth()   -- 1st at 00:00:00
d:endOfMonth()     -- last day at 23:59:59
d:startOfYear()    -- Jan 1 at 00:00:00
d:endOfYear()      -- Dec 31 at 23:59:59