Instant

Standard library struct · Made with Instant.now() or Instant.parse(text)

An Instant is an exact moment, the same everywhere in the world: when a message was sent, when an order was placed, a deadline. Two people in different time zones looking at the same Instant agree on when it is, even though their clocks show different times.

const sent = Instant.parse("2026-09-25T14:30:00Z")
const received = Instant.parse("2026-09-25T14:32:30Z")
print(received - sent)
print(sent + Duration(hours: 2))

2m 30s
2026-09-25T16:30:00Z

An Instant counts nanoseconds from the start of 1 January 1970 in UTC, and covers the years 1 through 9999. It is a value: instants for the same moment are equal, an earlier one is less than a later one, and an instant can be a dictionary key.

An Instant always prints in UTC, marked with Z: 2026-10-01T13:00:00Z. To see what a calendar and clock in some place show at that moment, use to_date_time.

Because Instant and Duration are exact, they have operators: an instant plus a duration is always the same moment. Calendar steps such as “the same day next month” are different, and belong to Date and DateTime.

At a glance

Making one
`Instant.now()`	The moment now
`Instant.parse(text)`, `Instant.parse_maybe(text)`	A moment read from text such as `2026-09-25T14:30:00Z`
`Instant.from_unix_seconds(seconds)`, `Instant.from_unix_milliseconds(milliseconds)`	A moment from a Unix timestamp
`DateTime.to_instant(zone)`	The moment a `DateTime` is in a zone

Reading
`unix_seconds`, `unix_milliseconds`	The Unix timestamp
`to_date_time(zone)`	What the calendar and clock show there

Arithmetic
`instant + duration`, `instant - duration`	A later or earlier moment
`instant - other`	The exact time between two moments

Making one

Instant.now(): Instant

The moment now, from the computer’s clock. To measure how long something takes, use a Stopwatch instead, which a change to the computer’s clock can’t disturb.

const start = Instant.now()
print(start > Instant.parse("2026-01-01T00:00:00Z"))

true

Instant.parse(text: String): Instant

Reads a date and a time followed by Z for UTC, or by an offset from UTC. This is the form most web services use.

print(Instant.parse("2026-09-25T14:30:00Z"))
print(Instant.parse("2026-09-25T14:30:00+02:00"))

2026-09-25T14:30:00Z
2026-09-25T12:30:00Z

The second one is two hours ahead of UTC, so it is the earlier moment, 12:30 in UTC.

Raises a DateTimeError for any other layout. Text with no Z or offset could be any moment, so the message suggests adding Z, or reading it with DateTime.parse instead.

Instant.parse_maybe(text: String): Instant?

Like parse, but gives nothing instead of raising an error.

print(Instant.parse_maybe("2026-09-25T14:30:00"))

nothing

Instant.from_unix_seconds(seconds: Int): Instant

The moment a Unix timestamp names: the number of seconds since the start of 1970, as many systems and file formats store a time.

print(Instant.from_unix_seconds(0))
print(Instant.from_unix_seconds(1790346600))

1970-01-01T00:00:00Z
2026-09-25T14:30:00Z

Raises a DateTimeError for a moment outside the years 1 to 9999.

Instant.from_unix_milliseconds(milliseconds: Int): Instant

The same, for a timestamp counted in milliseconds, as many web systems use.

print(Instant.from_unix_milliseconds(1500))

1970-01-01T00:00:01.500Z

Raises a DateTimeError for a moment outside the years 1 to 9999.

Reading

unix_seconds: Int

The Unix timestamp: whole seconds since the start of 1970. unix_milliseconds is the same in milliseconds. Both round toward the past, as Unix time does, and neither needs parentheses.

const moment = Instant.parse("2026-09-25T14:30:00Z")
print(moment.unix_seconds)
print(moment.unix_milliseconds)

1790346600
1790346600000

to_date_time(zone: TimeZone = TimeZone.local): DateTime

What a calendar and clock in zone show at this moment, as a DateTime. The zone is the computer’s own unless you say otherwise.

const moment = Instant.parse("2026-09-25T14:30:00Z")
print(moment.to_date_time(TimeZone.utc))
print(moment.to_date_time(TimeZone("Europe/Paris")))
print(moment.to_date_time(TimeZone.fixed(hours: 5, minutes: 30)))

2026-09-25T14:30:00
2026-09-25T16:30:00
2026-09-25T20:00:00

This is how a meeting at 09:00 in New York is shown to someone in Paris:

const meeting = DateTime(2026, 10, 1, 9).to_instant(TimeZone("America/New_York"))
print(meeting.to_date_time(TimeZone("Europe/Paris")))

2026-10-01T15:00:00

Arithmetic

instant + duration: Instant

A later moment, exactly duration away; instant - duration gives an earlier one. The methods after(duration) and before(duration) do the same.

const moment = Instant.parse("2026-09-25T14:30:00Z")
print(moment + Duration(hours: 2))
print(moment - Duration(minutes: 30))
print(moment.after(Duration(days: 1)))

2026-09-25T16:30:00Z
2026-09-25T14:00:00Z
2026-09-26T14:30:00Z

Raises a DateTimeError for a moment outside the years 1 to 9999.

instant - other: Duration

The exact time from other to this moment, as a Duration. It is negative when other is later. The method since(other) does the same.

const sent = Instant.parse("2026-09-25T14:30:00Z")
const later = Instant.parse("2026-09-26T16:00:00Z")
print(later - sent)
print(sent - later)

1d 1h 30m
-1d 1h 30m