-
-
Notifications
You must be signed in to change notification settings - Fork 2
Tiri Tempus API
The Tempus API is a comprehensive date and time library for Tiri, providing immutable value types for instants, dates, times, time zones, durations, and periods. It follows ISO 8601 conventions and supports the Gregorian calendar with nanosecond precision.
The API can be loaded with the line:
import 'tempus'Tempus values are immutable. All operations that appear to modify a value return a new one instead. Attempting to assign to a field raises an error.
The library distinguishes between:
-
Machine time — an
Instantis a point on the UTC timeline, measured in seconds and nanoseconds since the Unix epoch. -
Civil time —
LocalDate,LocalTime, andLocalDateTimerepresent human-readable calendar/clock values with no attached time zone or offset. -
Offset time — an
OffsetDateTimepairs a local date-time with a fixed UTC offset. -
Zoned time — a
ZonedDateTimepairs an instant with a named time zone, correctly handling daylight saving transitions. -
Durations and Periods — a
Durationis an exact span of seconds and nanoseconds; aPeriodis a calendar span of years, months, weeks, and days.
All value types support tostring() to produce ISO 8601 text. Value equality uses is. Ordered comparisons with
< and <= are available for instant, duration, offset, local date/time, offset date-time, and zoned date-time
values.
Equality is type-specific. OffsetDateTime equality requires the same instant and the same offset, while
ZonedDateTime equality requires the same instant and the same zone. Use instantEquals() when only the represented
instant matters.
Unless a type section explicitly documents readable fields, use methods rather than direct field access. Period component fields are public; the storage layout of other values should be treated as implementation detail.
Every tempus type has a corresponding tempus.is* function that returns true when the argument is a value of that type.
tempus.isInstant(value)
tempus.isDuration(value)
tempus.isOffset(value)
tempus.isLocalDate(value)
tempus.isLocalTime(value)
tempus.isLocalDateTime(value)
tempus.isOffsetDateTime(value)
tempus.isZone(value)
tempus.isZonedDateTime(value)
tempus.isPeriod(value)
tempus.isInterval(value)
tempus.isClock(value)
tempus.isResolver(value)Tempus functions raise ordinary Tiri exceptions for invalid input and failed time-zone lookups:
| Error | Raised when |
|---|---|
ERR_InvalidValue |
A field, operand, type, range, or value combination is invalid. |
ERR_Syntax |
Text cannot be parsed as the requested Tempus type, or a format pattern is invalid. |
ERR_Search |
A named time zone cannot be found. |
ERR_LimitedSuccess |
A resolver rejects a skipped or ambiguous local date-time. |
ERR_OutOfRange |
A time-zone lookup uses an instant or local date-time outside the supported year range. |
instant = tempus.now([Clock])
Returns the current Instant. If Clock is omitted, the system clock is used.
now = tempus.now()
print(now) -- e.g. 2026-05-17T09:30:00Zdate = tempus.today([Zone], [Clock])
Returns today's LocalDate in the given time zone. Both parameters are optional and default to the local zone and system clock respectively.
today = tempus.today()
print(today) -- e.g. 2026-05-17An Instant represents a single point on the UTC timeline with nanosecond precision.
Create instant from epoch seconds and optional nanoseconds
Create instant from a Unix epoch timestamp.
Parse ISO 8601 instant text, e.g. 2024-06-15T10:30:00Z.
| Method | Description |
|---|---|
toUnixSeconds() |
Return epoch seconds as a number. |
toUnixMillis() |
Return epoch milliseconds. |
toUnixNanos() |
Return epoch nanoseconds. |
durationUntil(Other) |
Return the Duration from this instant to Other. |
toZonedDateTime(Zone) |
Convert to a ZonedDateTime in the given zone. |
format(Pattern) |
Format the instant using the given pattern. |
| Operator | Right operand | Result |
|---|---|---|
+ |
Duration |
Instant |
- |
Duration |
Instant |
- |
Instant |
Duration |
a = tempus.instant.parse('2024-01-01T00:00:00Z')
b = tempus.instant.parse('2024-01-02T00:00:00Z')
print(b - a) -- PT24H
print(a + tempus.duration.seconds(3600)) -- 2024-01-01T01:00:00ZA Duration represents an exact time span measured in seconds and nanoseconds.
Signatures:
dur = tempus.duration(KV)
dur = tempus.duration.seconds(Seconds)
dur = tempus.duration.millis(Millis)
dur = tempus.duration.nanos(Nanos)
dur = tempus.duration.parse(Text)
-- From a table of fields
dur = tempus.duration({ hours = 1, minutes = 30 })
-- From individual units
dur = tempus.duration.seconds(90)
dur = tempus.duration.millis(1500)
dur = tempus.duration.nanos(1000000000)
-- Parse ISO 8601 duration text
dur = tempus.duration.parse('PT1H30M')The table form accepts the fields hours, minutes, seconds, millis, and nanos.
| Method | Description |
|---|---|
totalSeconds() |
Return the total duration as fractional seconds. |
totalMillis() |
Return the total duration as fractional milliseconds. |
| Operator | Right operand | Result |
|---|---|---|
+ |
Duration |
Duration |
- |
Duration |
Duration |
- (unary) |
— |
Duration (negated) |
a = tempus.duration.seconds(60)
b = tempus.duration.seconds(30)
print(a + b) -- PT1M30S
print(a:totalMillis()) -- 60000
print(-a) -- -PT1MAn Offset represents a fixed UTC offset in the range -18:00 to +18:00.
Signatures:
offset = tempus.offset(Seconds)
offset = tempus.offset.hours(Hours)
offset = tempus.offset.utc()
offset = tempus.offset.parse(Text)
-- From total seconds
offset = tempus.offset(Seconds)
-- From hours
offset = tempus.offset.hours(5)
-- UTC shorthand
offset = tempus.offset.utc()
-- Parse offset text
offset = tempus.offset.parse('+05:30')
offset = tempus.offset.parse('Z')| Method | Description |
|---|---|
totalSeconds() |
Return the offset in seconds. |
| Operator | Result |
|---|---|
- (unary) |
Offset (negated) |
offset = tempus.offset.hours(5)
print(offset) -- +05:00
print(offset:totalSeconds()) -- 18000
print(-offset) -- -05:00A LocalDate represents a date without a time or time zone, such as 2024-06-15.
Signatures:
date = tempus.localDate(Year, Month, Day)
date = tempus.localDate.from(KV)
date = tempus.localDate.parse(Text)
-- Direct construction
date = tempus.localDate(Year, Month, Day)
-- From a table
date = tempus.localDate.from({ year = 2024, month = 6, day = 15 })
-- Parse ISO 8601 date text
date = tempus.localDate.parse('2024-06-15')| Method | Description |
|---|---|
year() |
Return the year. |
month() |
Return the month (1–12). |
day() |
Return the day of month. |
dayOfWeek() |
Return the ISO day of week (1 = Monday, 7 = Sunday). |
dayOfYear() |
Return the ordinal day of year. |
daysInMonth() |
Return the number of days in this date's month. |
daysInYear() |
Return 365 or 366. |
isLeapYear() |
Return true if this date is in a leap year. |
withFields(KV) |
Return a new date with replacement fields from the table KV. |
atTime(Time) |
Combine with a LocalTime to produce a LocalDateTime. |
format(Pattern) |
Format the date using the given pattern. |
| Operator | Right operand | Result |
|---|---|---|
+ |
Period |
LocalDate |
- |
Period |
LocalDate |
- |
LocalDate |
Period (days only) |
date = tempus.localDate(2024, 3, 1)
print(date) -- 2024-03-01
print(date:isLeapYear()) -- true
print(date + tempus.period.days(10)) -- 2024-03-11
print(date:dayOfWeek()) -- 5 (Friday)
next_month = date:withFields({ month = 4 })
print(next_month) -- 2024-04-01A LocalTime represents a time of day without a date or time zone, such as 14:30:00.
Signatures:
time = tempus.localTime(Hour, [Minute], [Second], [Nano])
time = tempus.localTime.from(KV)
time = tempus.localTime.parse(Text)
-- Direct construction (minute, second, nano are optional)
time = tempus.localTime(Hour, [Minute], [Second], [Nano])
-- From a table
time = tempus.localTime.from({ hour = 14, minute = 30 })
-- Parse ISO 8601 time text
time = tempus.localTime.parse('14:30:00')
time = tempus.localTime.parse('09:15:30.123456789')| Method | Description |
|---|---|
hour() |
Return the hour (0–23). |
minute() |
Return the minute (0–59). |
second() |
Return the second (0–59). |
nano() |
Return the nanosecond (0–999999999). |
withFields(KV) |
Return a new time with replacement fields from the table KV. |
format(Pattern) |
Format the time using the given pattern. |
| Operator | Right operand | Result |
|---|---|---|
+ |
Duration |
LocalTime (wraps at midnight) |
- |
Duration |
LocalTime (wraps at midnight) |
time = tempus.localTime(14, 30, 0)
print(time) -- 14:30:00
later = time + tempus.duration({ hours = 2 })
print(later) -- 16:30:00
evening = time:withFields({ hour = 20 })
print(evening) -- 20:30:00A LocalDateTime combines a LocalDate and a LocalTime without any time zone information.
Signatures:
ldt = tempus.localDateTime(Year, Month, Day, [Hour], [Minute], [Second], [Nano])
ldt = tempus.localDateTime.from(KV)
ldt = tempus.localDateTime.parse(Text)
-- Direct construction (hour through nano are optional)
ldt = tempus.localDateTime(Year, Month, Day, [Hour], [Minute], [Second], [Nano])
-- From a table
ldt = tempus.localDateTime.from({ year = 2024, month = 6, day = 15, hour = 10, minute = 30 })
-- From date and time components
ldt = tempus.localDateTime.from({ date = someLocalDate, time = someLocalTime })
-- Parse ISO 8601 text
ldt = tempus.localDateTime.parse('2024-06-15T10:30:00')| Method | Description |
|---|---|
date() |
Return the LocalDate part. |
time() |
Return the LocalTime part. |
withFields(KV) |
Return a new value with replacement fields. Accepts any combination of year, month, day, hour, minute, second, nano. |
atOffset(Offset) |
Attach an offset to produce an OffsetDateTime. |
toOffsetDateTime(Offset) |
Same as atOffset(). |
inZone(Zone, [Resolver]) |
Resolve into a ZonedDateTime. See Resolvers. |
toZonedDateTime(Zone, [Resolver]) |
Same as inZone(). |
format(Pattern) |
Format using the given pattern. |
| Operator | Right operand | Result |
|---|---|---|
+ |
Duration |
LocalDateTime |
+ |
Period |
LocalDateTime |
- |
Duration |
LocalDateTime |
- |
Period |
LocalDateTime |
ldt = tempus.localDateTime(2024, 6, 15, 10, 30, 0)
print(ldt) -- 2024-06-15T10:30:00
tomorrow = ldt + tempus.period.days(1)
print(tomorrow) -- 2024-06-16T10:30:00
-- Convert to a zoned date-time
zdt = ldt:inZone(tempus.zone('America/New_York'))
print(zdt)An OffsetDateTime pairs a LocalDateTime with a fixed UTC offset.
Signatures:
odt = tempus.offsetDateTime(LocalDateTime, Offset)
odt = tempus.offsetDateTime.from(KV)
odt = tempus.offsetDateTime.parse(Text)
-- Direct construction
odt = tempus.offsetDateTime(LocalDateTime, Offset)
-- From a table
odt = tempus.offsetDateTime.from({ local_date_time = ldt, offset = offset })
-- Parse ISO 8601 text
odt = tempus.offsetDateTime.parse('2024-06-15T10:30:00+05:30')| Method | Description |
|---|---|
instant() |
Return the Instant represented by this value. |
offset() |
Return the Offset. |
date() |
Return the LocalDate. |
time() |
Return the LocalTime. |
localDateTime() |
Return the LocalDateTime. |
instantEquals(Other) |
Compare by instant with another Instant or OffsetDateTime. |
toZonedDateTime(Zone) |
Convert to a ZonedDateTime in the given zone. |
format(Pattern) |
Format using the given pattern. |
| Operator | Right operand | Result |
|---|---|---|
+ |
Duration |
OffsetDateTime |
+ |
Period |
OffsetDateTime |
- |
Duration |
OffsetDateTime |
- |
Period |
OffsetDateTime |
- |
OffsetDateTime |
Duration |
odt = tempus.offsetDateTime.parse('2024-06-15T10:30:00+05:30')
print(odt) -- 2024-06-15T10:30:00+05:30
print(odt:instant()) -- 2024-06-15T05:00:00Z
-- Two offset date-times with the same instant
a = tempus.offsetDateTime.parse('2024-06-15T10:30:00+05:30')
b = tempus.offsetDateTime.parse('2024-06-15T05:00:00Z')
print(a:instantEquals(b)) -- trueA ZonedDateTime pairs an Instant with a named time Zone, correctly accounting for daylight saving time transitions.
Signatures:
zdt = tempus.zonedDateTime(Instant, Zone)
zdt = tempus.zonedDateTime.from(KV)
zdt = tempus.zonedDateTime.parse(Text)
-- From an instant and zone
zdt = tempus.zonedDateTime(Instant, Zone)
-- From a table
zdt = tempus.zonedDateTime.from({ instant = someInstant, zone = someZone })
zdt = tempus.zonedDateTime.from({ local_date_time = ldt, zone = someZone, resolver = tempus.resolve.later })
-- Parse ISO 8601 zoned text
zdt = tempus.zonedDateTime.parse('2024-06-15T10:30:00+12:00[Pacific/Auckland]')| Method | Description |
|---|---|
instant() |
Return the underlying Instant. |
zone() |
Return the Zone. |
offset() |
Return the Offset at this instant. |
localDateTime() |
Return the LocalDateTime in the zone. |
date() |
Return the LocalDate in the zone. |
time() |
Return the LocalTime in the zone. |
withZoneSameInstant(Zone) |
Move to another zone, preserving the instant. |
withZoneSameLocal(Zone, [Resolver]) |
Move to another zone, preserving the local fields. |
withLocal(KV) |
Return a new value with replacement local fields. Accepts year, month, day, hour, minute, second, nano, and an optional resolver. |
toOffsetDateTime() |
Convert to an OffsetDateTime. |
instantEquals(Other) |
Compare by instant with an Instant, OffsetDateTime, or ZonedDateTime. |
format(Pattern) |
Format using the given pattern. |
| Operator | Right operand | Result |
|---|---|---|
+ |
Duration |
ZonedDateTime |
+ |
Period |
ZonedDateTime |
- |
Duration |
ZonedDateTime |
- |
Period |
ZonedDateTime |
- |
ZonedDateTime |
Duration |
Duration arithmetic preserves elapsed time by adding to or subtracting from the underlying instant. Period arithmetic changes the local date-time first, then resolves the result back into the same zone with the default compatible resolver. These operations can produce different local results around daylight-saving transitions.
nz = tempus.zone('Pacific/Auckland')
zdt = tempus.localDateTime(2024, 6, 15, 10, 0, 0):inZone(nz)
print(zdt) -- 2024-06-15T10:00:00+12:00[Pacific/Auckland]
-- Convert the same instant to UTC
utc = zdt:withZoneSameInstant(tempus.zone.utc())
print(utc) -- 2024-06-14T22:00:00Z[UTC]
-- Duration between two zoned date-times
a = tempus.zonedDateTime.parse('2024-06-15T10:00:00+12:00[Pacific/Auckland]')
b = tempus.zonedDateTime.parse('2024-06-15T10:00:00+00:00[Europe/London]')
print(a - b) -- -PT12H (12 hours difference)A Period represents a calendar-based span of years, months, weeks, and days.
Signatures:
period = tempus.period(KV)
period = tempus.period.years(Years)
period = tempus.period.months(Months)
period = tempus.period.weeks(Weeks)
period = tempus.period.days(Days)
period = tempus.period.parse(Text)
-- From a table
period = tempus.period({ years = 1, months = 6 })
-- From individual units
period = tempus.period.years(1)
period = tempus.period.months(6)
period = tempus.period.weeks(2)
period = tempus.period.days(30)
-- Parse ISO 8601 period text
period = tempus.period.parse('P1Y6M')
period = tempus.period.parse('P2W')Period values expose their components as readable fields:
| Field | Description |
|---|---|
years |
Number of years. |
months |
Number of months. |
weeks |
Number of weeks. |
days |
Number of days. |
| Method | Description |
|---|---|
normalise() |
Normalise months into years and convert weeks to days. Returns a new Period. |
| Operator | Right operand | Result |
|---|---|---|
+ |
Period |
Period |
- |
Period |
Period |
- (unary) |
— |
Period (negated) |
p = tempus.period({ years = 1, months = 18, weeks = 2, days = 3 })
print(p) -- P1Y18M2W3D
print(p:normalise()) -- P2Y6M17D
date = tempus.localDate(2024, 1, 1)
print(date + tempus.period.months(3)) -- 2024-04-01An Interval represents a half-open range between two Instant values (inclusive start, exclusive stop).
Signatures:
interval = tempus.interval(Start, Stop)
interval = tempus.interval.from(KV)
interval = tempus.interval.fromStartAndDuration(Start, Duration)
-- From two instants
interval = tempus.interval(Start, Stop)
-- From a table
interval = tempus.interval.from({ start = startInstant, stop = stopInstant })
-- From a start instant and duration
interval = tempus.interval.fromStartAndDuration(Start, Duration)| Method | Description |
|---|---|
start() |
Return the start Instant. |
stop() |
Return the stop Instant. |
duration() |
Return the Duration of the interval. |
contains(Instant) |
Return true if the instant falls within the interval. |
overlaps(Other) |
Return true if two intervals overlap. |
intersection(Other) |
Return the overlapping Interval. |
union(Other) |
Return the combined Interval. The intervals must overlap or be adjacent. |
isEmpty() |
Return true if start equals stop. |
a = tempus.instant.parse('2024-01-01T00:00:00Z')
b = tempus.instant.parse('2024-01-02T00:00:00Z')
c = tempus.instant.parse('2024-01-01T12:00:00Z')
interval = tempus.interval(a, b)
print(interval) -- 2024-01-01T00:00:00Z/2024-01-02T00:00:00Z
print(interval:contains(c)) -- true
print(interval:duration()) -- PT24H
-- From start and duration
morning = tempus.interval.fromStartAndDuration(a, tempus.duration({ hours = 12 }))
print(morning:overlaps(interval)) -- trueA Zone represents a named time zone such as Pacific/Auckland or UTC. Time-zone lookups are supported for years
1601 through 9999; methods that resolve or query zone rules raise ERR_OutOfRange for instants or local date-times
outside that range.
Signatures:
zone = tempus.zone(ZoneID)
zone = tempus.zone.local()
zone = tempus.zone.utc()
-- Named zone (IANA identifier)
zone = tempus.zone('Pacific/Auckland')
zone = tempus.zone('UTC')
-- Local system zone
zone = tempus.zone.local()
-- UTC shorthand
zone = tempus.zone.utc()| Method | Description |
|---|---|
id() |
Return the canonical zone ID (e.g. Pacific/Auckland). |
nativeId() |
Return the OS-native zone identifier. |
source() |
Return the data source name. |
isFallback() |
Return true if fallback zone data is being used. |
offsetAt(Instant) |
Return the Offset at the given instant. |
nameAt(Instant) |
Return the zone display name at the given instant (e.g. New Zealand Standard Time). |
nextTransition(Instant) |
Return the next transition Instant, or nil. |
previousTransition(Instant) |
Return the previous transition Instant, or nil. |
source() identifies the time-zone data provider used by the underlying Core time query. isFallback() returns
true when fallback zone data is being used instead of the preferred platform data. The native ID, source name, and
display names are platform dependent.
zone = tempus.zone('Pacific/Auckland')
print(zone:id()) -- Pacific/Auckland
now = tempus.now()
print(zone:offsetAt(now)) -- e.g. +12:00
print(zone:nameAt(now)) -- e.g. New Zealand Standard Time
-- Find the next DST transition
next = zone:nextTransition(now)
if next then
print('Next transition:', next)
endA Clock provides controlled access to the current instant, supporting system time, fixed instants for testing, and offset clocks.
Signatures:
clock = tempus.clock.system()
clock = tempus.clock.fixed(Instant)
clock = tempus.clock.offset(BaseClock, Duration)
-- System clock (real time)
clock = tempus.clock.system()
-- Fixed clock (always returns the same instant)
clock = tempus.clock.fixed(someInstant)
-- Offset clock (base clock shifted by a duration)
clock = tempus.clock.offset(baseClock, tempus.duration({ hours = -6 }))| Method | Description |
|---|---|
instant() |
Return the current Instant. |
today(Zone) |
Return today's LocalDate in the given zone. |
localDateTime([Zone]) |
Return the current LocalDateTime. Defaults to the local zone. |
zonedDateTime([Zone]) |
Return the current ZonedDateTime. Defaults to the local zone. |
-- Using a fixed clock for deterministic tests
fixed = tempus.clock.fixed(tempus.instant.parse('2024-06-15T12:00:00Z'))
print(fixed:instant()) -- 2024-06-15T12:00:00Z
nz = tempus.zone('Pacific/Auckland')
print(fixed:today(nz)) -- 2024-06-16 (UTC+12)
-- Offset clock: simulates being 24 hours in the future
future = tempus.clock.offset(tempus.clock.system(), tempus.duration({ hours = 24 }))
print(future:instant())When converting a LocalDateTime to a ZonedDateTime, the local time may be ambiguous (during a DST fall-back) or invalid (during a DST spring-forward). A resolver controls how these cases are handled.
Resolvers are accessed through tempus.resolve:
| Resolver | Behaviour |
|---|---|
tempus.resolve.compatible |
Default. Uses the earlier offset for ambiguous times and the pre-transition offset for gaps. |
tempus.resolve.earlier |
Raises an exception for skipped times; selects the earlier instant for ambiguous times. |
tempus.resolve.later |
Raises an exception for skipped times; selects the later instant for ambiguous times. |
tempus.resolve.reject |
Raises an exception for both skipped and ambiguous times. |
tempus.resolve.skip |
Behaves the same as compatible. |
zone = tempus.zone('America/New_York')
-- During spring-forward, 2:30 AM does not exist
ldt = tempus.localDateTime(2024, 3, 10, 2, 30, 0)
-- Default resolver handles the gap gracefully
zdt = ldt:inZone(zone)
print(zdt)
-- Reject resolver raises an exception
try
ok = ldt:inZone(zone, tempus.resolve.reject)
except ex
print(ex.message) -- error message about skipped time
endTempus parsers accept a narrow ISO-style subset. Calendar and clock ranges are validated after the text shape is matched.
| Type | Accepted text |
|---|---|
LocalDate |
YYYY-MM-DD, with at least four year digits and optional leading + or -. |
LocalTime |
HH:MM, HH:MM:SS, or HH:MM:SS.Fraction, where Fraction has 1 to 9 digits. |
LocalDateTime |
A LocalDate, the literal T, and a LocalTime, with no offset or zone suffix. |
Instant |
A LocalDateTime followed by Z. |
Offset |
Z, +HH:MM, or -HH:MM. |
OffsetDateTime |
A LocalDateTime followed by Z, +HH:MM, or -HH:MM. |
ZonedDateTime |
An OffsetDateTime followed by [ZoneID], for example 2024-06-15T10:30:00+12:00[Pacific/Auckland]. |
Duration |
Optional leading -, then PT with one or more H, M, or S time components; fractional values are accepted only on seconds. |
Period |
Optional leading -, then P with one or more Y, M, W, or D date components. |
Unsupported ISO 8601 variants, such as ordinal dates, week dates, offsets without a colon, date-based durations, and
comma decimal separators, raise ERR_Syntax.
All date/time types support a format(Pattern) method. The pattern uses the following tokens:
| Token | Description | Example output |
|---|---|---|
yyyy |
Four-digit year | 2024 |
MM |
Two-digit month | 06 |
dd |
Two-digit day | 15 |
HH |
Two-digit hour (24-hour) | 14 |
mm |
Two-digit minute | 30 |
ss |
Two-digit second | 45 |
SSS |
Milliseconds (3 digits) | 123 |
SSSSSS |
Microseconds (6 digits) | 123456 |
SSSSSSSSS |
Nanoseconds (9 digits) | 123456789 |
XXX |
UTC offset |
+05:30 or Z
|
VV |
Time zone ID | Pacific/Auckland |
Literal text can be included by enclosing it in single quotes:
instant = tempus.instant.parse('2024-06-15T14:30:45Z')
print(instant:format("yyyy-MM-dd'T'HH:mm:ssXXX")) -- 2024-06-15T14:30:45Z
zdt = tempus.localDateTime(2024, 6, 15, 14, 30):inZone(tempus.zone('Pacific/Auckland'))
print(zdt:format("dd/MM/yyyy HH:mm VV")) -- 15/06/2024 14:30 Pacific/AucklandNot all tokens are available for every type. For example, VV is available for Instant and ZonedDateTime values,
and XXX requires an instant, offset, or zoned type. Using an unavailable token raises an error.
| Type | Available tokens |
|---|---|
Instant |
yyyy, MM, dd, HH, mm, ss, SSS–SSSSSSSSS, XXX, VV
|
LocalDate |
yyyy, MM, dd
|
LocalTime |
HH, mm, ss, SSS–SSSSSSSSS
|
LocalDateTime |
yyyy, MM, dd, HH, mm, ss, SSS–SSSSSSSSS
|
OffsetDateTime |
yyyy, MM, dd, HH, mm, ss, SSS–SSSSSSSSS, XXX
|
ZonedDateTime |
yyyy, MM, dd, HH, mm, ss, SSS–SSSSSSSSS, XXX, VV
|
import 'tempus'
-- Get the current time in multiple zones
now = tempus.now()
nz = tempus.zone('Pacific/Auckland')
uk = tempus.zone('Europe/London')
us = tempus.zone('America/New_York')
print('UTC: ', now)
print('Auckland: ', now:toZonedDateTime(nz))
print('London: ', now:toZonedDateTime(uk))
print('New York: ', now:toZonedDateTime(us))
-- Date arithmetic
today = tempus.today()
deadline = today + tempus.period({ weeks = 2 })
print(f'Two weeks from today: {deadline}')
-- Measure elapsed time
clock = tempus.clock.system()
start = clock:instant()
-- ... perform some work ...
elapsed = clock:instant() - start
print(f'Elapsed: {elapsed:totalMillis()} ms')