`toml.values`

import toml.values

toml lifts part of this module out to its own top level; each name below is shown with the path that reaches it. Anything still spelled toml.values.* needs import toml.values.

The TOML types that Zuri has no built-in equal for.

TOML carries four temporal types and draws a line between an integer and a float. Zuri has one number, which is an IEEE-754 double, and a date.Date that always knows an offset. Neither gap can be closed by picking a near-enough built-in: a local date that decoded as a Date would grow a UTC offset it never had, and a float that decoded as a number would be written back out as an integer.

So the four temporal types are their own classes here, and Float marks a number that must stay a float. Each temporal class validates on construction, renders itself in the exact form TOML specifies, and answers equals() rather than ==, which compares instances by identity.

import toml

var released = toml.LocalDate(2026, 9, 19)
echo released.to_string()

var stamp = toml.DateTime(2026, 9, 19, 13, 4, 5, 0, -300)
echo stamp.to_string()

2026-09-19
2026-09-19T13:04:05-05:00

Classes

`LocalDate`

class toml.LocalDate

A calendar date with no time and no offset, TOML’s local-date.

Spelled 1979-05-27. This is a date on the wall calendar: a birthday, a release day, a contract term. It names no instant, so two LocalDates from different timezones are comparable directly.

import toml

var released = toml.LocalDate(2026, 9, 19)

echo released.to_string()
echo released.year
echo released.equals(toml.LocalDate(2026, 9, 19))

2026-09-19
2026
true

printable — has a @to_string(), so echo and print() show something useful

Constructor

toml.LocalDate(year, month, day)

Parameters

year (number) — From 0 to 9999.
month (number) — From 1 to 12.
day (number) — From 1 to the length of that month, leap years included.

Raises TomlError If any field is fractional or out of range, or if the day does not exist in that month.

`LocalDate.to_string()`

toml.LocalDate.to_string() -> string

Returns the date as TOML spells it, YYYY-MM-DD.

Returns string

`LocalDate.equals()`

toml.LocalDate.equals(other) -> bool

Returns true when other is a LocalDate naming the same day. == makes the same comparison.

Parameters

other (any)

Returns bool

`LocalDate.to_date()`

toml.LocalDate.to_date() -> Date

Returns this date as a date.Date at midnight UTC.

The offset is an artefact of the conversion: a date.Date always has one and a LocalDate never did. Use it for calendar arithmetic, not to claim an instant the TOML file did not state.

Returns Date

`LocalTime`

class toml.LocalTime

A wall-clock time with no date and no offset, TOML’s local-time.

Spelled 07:32:00 or 07:32:00.999999. This is a time of day that recurs: an opening hour, a cron-like schedule, a curfew.

Fractional seconds are kept to nanosecond precision and render with trailing zeros removed, so half a second is .5 rather than .500000000.

import toml

echo toml.LocalTime(7, 32, 0).to_string()
echo toml.LocalTime(7, 32, 0, 500000000).to_string()

07:32:00
07:32:00.5

printable — has a @to_string(), so echo and print() show something useful

Constructor

toml.LocalTime(hour, minute, second, nanosecond)

Parameters

hour (number) — From 0 to 23.
minute (number) — From 0 to 59.
second (number) — From 0 to 60, the 60 admitting a leap second.
nanosecond (?number) — From 0 to 999999999. Defaults to 0.

Raises TomlError If any field is fractional or out of range.

`LocalTime.to_string()`

toml.LocalTime.to_string() -> string

Returns the time as TOML spells it, HH:MM:SS with a fractional part only when there is one.

Returns string

`LocalTime.equals()`

toml.LocalTime.equals(other) -> bool

Returns true when other is a LocalTime naming the same instant of the clock, fractional seconds included.

Parameters

other (any)

Returns bool

`LocalDateTime`

class toml.LocalDateTime

A date and a wall-clock time with no offset, TOML’s local-date-time.

Spelled 1979-05-27T07:32:00. It names a moment on somebody’s calendar and clock without saying whose, which is what a log format or a schedule written for one site means by a timestamp.

import toml

echo toml.LocalDateTime(1979, 5, 27, 7, 32, 0).to_string()

1979-05-27T07:32:00

printable — has a @to_string(), so echo and print() show something useful

Constructor

toml.LocalDateTime(year, month, day, hour, minute, second, nanosecond)

Parameters

year (number) — From 0 to 9999.
month (number) — From 1 to 12.
day (number) — From 1 to the length of that month.
hour (number) — From 0 to 23.
minute (number) — From 0 to 59.
second (number) — From 0 to 60.
nanosecond (?number) — From 0 to 999999999. Defaults to 0.

Raises TomlError If any field is fractional or out of range.

`LocalDateTime.to_string()`

toml.LocalDateTime.to_string() -> string

Returns the timestamp as TOML spells it, the date and the time joined by T.

Returns string

`LocalDateTime.equals()`

toml.LocalDateTime.equals(other) -> bool

Returns true when other is a LocalDateTime naming the same date and time.

Parameters

other (any)

Returns bool

`LocalDateTime.to_date()`

toml.LocalDateTime.to_date() -> Date

Returns this timestamp as a date.Date read as UTC.

The offset is an artefact of the conversion. A LocalDateTime deliberately does not know one, so reading the result as an instant asserts something the TOML file did not.

Returns Date

`DateTime`

class toml.DateTime

A date and time with a UTC offset, TOML’s offset-date-time.

Spelled 1979-05-27T07:32:00Z or 1979-05-27T00:32:00-07:00. This is the only one of the four that names an unambiguous instant, and the only one that can be compared across sites.

The offset is held in minutes, signed, so -300 is -05:00. A zero offset renders as Z; a document that spelled it +00:00 keeps that spelling through an edit, because the raw text is preserved alongside the value.

import toml

echo toml.DateTime(1979, 5, 27, 7, 32, 0, 0, 0).to_string()
echo toml.DateTime(1979, 5, 27, 0, 32, 0, 0, -420).to_string()

1979-05-27T07:32:00Z
1979-05-27T00:32:00-07:00

printable — has a @to_string(), so echo and print() show something useful

Constructor

toml.DateTime(year, month, day, hour, minute, second, nanosecond, offset_minutes)

Parameters

year (number) — From 0 to 9999.
month (number) — From 1 to 12.
day (number) — From 1 to the length of that month.
hour (number) — From 0 to 23.
minute (number) — From 0 to 59.
second (number) — From 0 to 60.
nanosecond (?number) — From 0 to 999999999. Defaults to 0.
offset_minutes (?number) — Minutes east of UTC, from -1439 to 1439. Defaults to 0, which renders as Z.

Raises TomlError If any field is fractional or out of range.

`DateTime.to_string()`

toml.DateTime.to_string() -> string

Returns the timestamp as TOML spells it, with Z for a zero offset and +HH:MM or -HH:MM otherwise.

Returns string

`DateTime.equals()`

toml.DateTime.equals(other) -> bool

Returns true when other is a DateTime with the same fields and the same offset.

Two timestamps naming the same instant through different offsets are not equal here. Compare to_date().to_time() for that.

Parameters

other (any)

Returns bool

`DateTime.to_date()`

toml.DateTime.to_date() -> Date

Returns this timestamp as a date.Date carrying the same offset.

This is the one temporal type that converts without inventing anything: both sides name the same instant.

Returns Date

`Float`

class toml.Float

A number that must be written as a TOML float.

Zuri’s number is an IEEE-754 double, so 1.0 and 1 are one value and nothing distinguishes them afterwards. TOML does distinguish them, and an encoder with only the value to go on has to guess: it writes an integer whenever the number has no fractional part, which turns a 1.0 into a 1.

Wrap the number to settle it. Float means float, whatever the value happens to be:

import toml

echo toml.dump({ ratio: 1.0 })
echo toml.dump({ ratio: toml.Float(1.0) })

ratio = 1

ratio = 1.0

Decoding never produces one: a TOML float decodes to a plain number, because a wrapper on every float would make every read pay for a distinction most programs do not use.