DateTime API

Date and time helpers are available under ptool.datetime and p.datetime.

ptool.datetime works with concrete instants. Every DateTime value carries a timezone or numeric offset.

ptool.datetime.now

Unreleased - Introduced.

ptool.datetime.now([tz]) returns the current time as a DateTime.

• tz (string, optional): An IANA timezone such as UTC, America/New_York, or Asia/Shanghai. If omitted, the local system timezone is used.
• Returns: DateTime.

local local_now = p.datetime.now()
local utc_now = p.datetime.now("UTC")

print(local_now)
print(utc_now:format("%Y-%m-%d %H:%M:%S %Z"))

ptool.datetime.parse

Unreleased - Introduced.

ptool.datetime.parse(input[, options]) parses a datetime string and returns a DateTime.

• input (string, required): A datetime string.
• options.timezone (string, optional): An IANA timezone used only when the input does not already include a timezone or offset.
• Returns: DateTime.

Accepted inputs:

• Zoned inputs such as 2024-07-15T16:24:59-04:00.
• Zoned inputs with bracketed timezone annotations when supported by the parser.
• Naive inputs such as 2024-07-15 16:24:59, but only when options.timezone is provided.

Behavior:

• Empty strings are rejected.
• If input already includes a timezone or offset, setting options.timezone raises an error.
• Without options.timezone, naive inputs are rejected.

local a = p.datetime.parse("2024-07-15T16:24:59-04:00")
local b = p.datetime.parse("2024-07-15 16:24:59", {
  timezone = "America/New_York",
})

print(a.offset)   -- -04:00
print(b.timezone) -- America/New_York

ptool.datetime.from_unix

Unreleased - Introduced.

ptool.datetime.from_unix(value[, options]) constructs a DateTime from a Unix timestamp.

• value (integer, required): The Unix timestamp.
• options.unit (string, optional): One of s, ms, or ns. Defaults to s.
• options.timezone (string, optional): An IANA timezone. If omitted, the timestamp is interpreted in UTC.
• Returns: DateTime.

local a = p.datetime.from_unix(1721075099)
local b = p.datetime.from_unix(1721075099000, {
  unit = "ms",
  timezone = "Asia/Tokyo",
})

print(a) -- 2024-07-15T20:24:59+00:00
print(b)

ptool.datetime.compare

Unreleased - Introduced.

ptool.datetime.compare(a, b) compares two instants.

• a / b (string|DateTime, required): A datetime string or DateTime object.
• Returns: -1 | 0 | 1.

String arguments are parsed using the same strict rules as ptool.datetime.parse(input), so they must already include a timezone or offset.

print(ptool.datetime.compare(
  "2024-07-15T20:24:59+00:00",
  "2024-07-15T16:24:59-04:00"
)) -- 0

ptool.datetime.is_valid

Unreleased - Introduced.

ptool.datetime.is_valid(input[, options]) checks whether a datetime string can be parsed.

• input (string, required): A datetime string.
• options.timezone (string, optional): An IANA timezone for naive input.
• Returns: boolean.

print(ptool.datetime.is_valid("2024-07-15T16:24:59-04:00")) -- true
print(ptool.datetime.is_valid("2024-07-15 16:24:59")) -- false
print(ptool.datetime.is_valid("2024-07-15 16:24:59", {
  timezone = "America/New_York",
})) -- true

DateTime

Unreleased - Introduced.

DateTime represents a concrete instant returned by ptool.datetime.now(...), parse(...), or from_unix(...).

It is implemented as a Lua userdata.

Fields and methods:

• Fields:
  • year (integer)
  • month (integer)
  • day (integer)
  • hour (integer)
  • minute (integer)
  • second (integer)
  • nanosecond (integer)
  • offset (string)
  • timezone (string)
• Methods:
  • dt:format(fmt) -> string
  • dt:to_string() -> string
  • dt:unix([unit]) -> integer
  • dt:in_tz(tz) -> DateTime
  • dt:compare(other) -> -1|0|1
• Metamethods:
  • tostring(dt) is available.
  • ==, <, and <= comparisons are supported.

format

Canonical API name: ptool.datetime.DateTime:format.

dt:format(fmt) formats the datetime using strftime-style directives.

• fmt (string, required): A format string such as %Y-%m-%d %H:%M:%S %Z.
• Returns: string.

local dt = p.datetime.parse("2024-07-15T16:24:59-04:00")
print(dt:format("%Y-%m-%d %H:%M:%S %:z"))

to_string

Canonical API name: ptool.datetime.DateTime:to_string.

dt:to_string() returns the canonical string form with a numeric offset.

• Returns: string.

local dt = p.datetime.parse("2024-07-15T16:24:59-04:00")
print(dt:to_string()) -- 2024-07-15T16:24:59-04:00

unix

Canonical API name: ptool.datetime.DateTime:unix.

dt:unix([unit]) returns the Unix timestamp of the instant.

• unit (string, optional): One of s, ms, or ns. Defaults to s.
• Returns: integer.

Notes:

• ns may raise an error if the result does not fit in Lua's integer range.

local dt = p.datetime.parse("2024-07-15T20:24:59+00:00")
print(dt:unix())       -- seconds
print(dt:unix("ms"))   -- milliseconds

in_tz

Canonical API name: ptool.datetime.DateTime:in_tz.

dt:in_tz(tz) converts the same instant into another timezone.

• tz (string, required): An IANA timezone.
• Returns: DateTime.

local dt = p.datetime.parse("2024-07-15T20:24:59+00:00")
local tokyo = dt:in_tz("Asia/Tokyo")

print(dt)
print(tokyo)

compare

Canonical API name: ptool.datetime.DateTime:compare.

dt:compare(other) compares the current instant with other.

• other (string|DateTime, required): A datetime string or another DateTime object.
• Returns: -1 | 0 | 1.

local a = p.datetime.parse("2024-07-15T20:24:59+00:00")
local b = p.datetime.parse("2024-07-15T21:24:59+00:00")

print(a:compare(b)) -- -1
print(a < b)        -- true

Notes

• ptool.datetime does not parse natural-language phrases such as "tomorrow 8am".
• Timezone names should be IANA identifiers such as UTC, Asia/Tokyo, or America/New_York.
• Comparisons operate on the instant, not on the displayed wall-clock fields.