Skip to main content

Time

A Duration is a span of time. An Instant is a reading of the monotonic clock, which never goes back, for measuring how long something took. A DateTime is a moment of the calendar in UTC, and a DateTimeOffset the same moment as the clocks of a place show it. All four are Copyable, Equatable, Hashable and Comparable, and all but Instant are printed. They are written in SG, in the language's own module std, which a program gets by naming one of them.

A method that compares (compare) takes the other value as read: a.compare(read b). <, == and the others need nothing written.

Duration​

A count of nanoseconds in a long; it may be negative. Its arithmetic follows the rule of the numbers: an overflow panics in a debug build and in a test, and wraps in a release build.

SignatureWhat it does
Duration Duration.fromNanoseconds(long count), fromMicroseconds, fromMilliseconds, fromSecondsA span of so many units
long nanoseconds(read this), microseconds, milliseconds, secondsThe whole units in the span, cut toward zero
double totalSeconds(read this)The span in seconds, with the fraction
Duration plus(read this, Duration other), minus(read this, Duration other)The sum, the difference
Duration times(read this, long factor)The span factor times
int compare(read this, read Duration other)Negative, 0 or positive

print writes it in the unit its size calls for, with the fewest digits after the point: 1.5s, 250ms, 3µs, -2ms, 0s. Seconds stay seconds: 90s.

void main() {
var step = Duration.fromMilliseconds(1500)
print(step)
print($"{step.seconds()} {step.milliseconds()} {step.totalSeconds()}")
print(Duration.fromSeconds(90))
print(Duration.fromMicroseconds(3))
print(Duration.fromNanoseconds(-2000000))
var total = step.plus(Duration.fromMilliseconds(250)).times(2)
print(total)
print(total.minus(Duration.fromSeconds(4)))
print($"{step < total} {step.compare(read total)}")
}

It prints:

1.5s
1 1500 1.5
90s
3µs
-2ms
3.5s
-500ms
true -1

Instant​

SignatureWhat it does
Instant Instant.now()Reads the monotonic clock
Duration elapsed(read this)The time gone by since this moment
Duration since(read this, Instant earlier)The time from earlier to this; negative when earlier is later
Instant plus(read this, Duration span), minus(read this, Duration span)A moment a span later, or earlier

Only the time between two instants means something, so an Instant is not printed:

void main() {
var start = Instant.now()
print(start)
}
error: `Instant` cannot be written as text: it is not `Formattable`
an `Instant` means something only next to another one
--> example.sg:3:11
3 | print(start)
| ^^^^^
hint: the time between two is a `Duration`, which is written: `start.elapsed()`, `later.since(earlier)`
long work() {
long total = 0
for i in 0..1000000 {
total += i
}
return total
}

void main() {
var start = Instant.now()
print(work())
var took = start.elapsed()
print(took >= Duration.fromSeconds(0))
var later = start.plus(Duration.fromSeconds(2))
print(later.since(start))
}

It prints:

499999500000
true
2s

Mixing the two clocks is an error: i.since(t) with t a DateTime says that the time between two readings is taken on one clock, since the clock of the system can be set and go back.

DateTime​

The nanoseconds since 1970-01-01T00:00:00Z, without leap seconds, for the years 1677 to 2262, in the Gregorian calendar.

SignatureWhat it does
DateTime DateTime.now()Reads the clock of the system, in UTC; it can be set, and can go back
Result<DateTime, DateError> DateTime.utc(int year, int month, int day, int hour, int minute, int second)A moment from its parts, each checked
DateTime DateTime.fromUnixSeconds(long seconds), fromUnixMilliseconds(long milliseconds)A moment from a count since 1970
Result<DateTime, DateError> DateTime.parse(read string text)A moment in RFC 3339, taken to UTC
int year(read this), month, day, hour, minute, second, nanosecondThe parts, in UTC
DayOfWeek dayOfWeek(read this)Monday to Sunday
long unixSeconds(read this), unixMillisecondsThe count since 1970, rounded down
Duration since(read this, DateTime earlier)The time from earlier to this
DateTime plus(read this, Duration span), minusA moment a span later, or earlier
DateTimeOffset toLocal(read this)The moment at the offset of the system's time zone then
Result<DateTimeOffset, DateError> withOffset(read this, Duration offset)The moment at an offset of your own

print writes ISO 8601: 2026-11-15T09:30:00Z, with the fraction of the second in 3, 6 or 9 digits when there is one. Another format is written with the parts: $"{t.day():D2}.{t.month():D2}.{t.year()}".

A DateTime is made by its functions only; DateTime { ... } is an error whose hint names them.

Result<void, DateError> main() {
var launch = try DateTime.utc(2026, 11, 15, 9, 30, 0)
print(launch)
print($"{launch.hour()}:{launch.minute():D2} {launch.dayOfWeek()} {launch.unixSeconds()}")
print($"{launch.day():D2}.{launch.month():D2}.{launch.year()}")
print(DateTime.fromUnixMilliseconds(1500))
var later = launch.plus(Duration.fromSeconds(36 * 3600))
print(later)
print(later.since(launch))
print(try DateTime.parse("2026-11-18T12:30:05.5+03:00"))
print(DateTime.utc(2026, 2, 30, 0, 0, 0) is Error(InvalidDay))
return Ok()
}

It prints:

2026-11-15T09:30:00Z
9:30 Sunday 1794735000
15.11.2026
1970-01-01T00:00:01.500Z
2026-11-16T21:30:00Z
129600s
2026-11-18T09:30:05.500Z
true

DateTimeOffset​

A moment and the offset from UTC at which it is seen: 2026-11-18T12:30:05+03:00. The offset is kept as it was: plus of a day after the clocks of the place changed gives the old offset, and t.toUtc().plus(span).toLocal() the new one. Two are equal when both the moment and the offset are; a.toUtc() == b.toUtc() asks only for the moment.

SignatureWhat it does
Result<DateTimeOffset, DateError> DateTimeOffset.local(int year, int month, int day, int hour, int minute, int second)The moment the clocks of the system's time zone show that at; SkippedLocalTime in the hour summer time skips, the earlier of two in the hour it repeats
Result<DateTimeOffset, DateError> DateTimeOffset.parse(read string text)RFC 3339: the offset Z, +hh:mm or -hh:mm
DateTime toUtc(read this)The moment in UTC
Duration offset(read this)How far the place is ahead of UTC; negative west of it
year, month, day, hour, minute, second, nanosecond, dayOfWeekThe parts as the clocks of the place show them
since, plus, minus, compareAs on DateTime; plus keeps the offset

The time zone of the system is TZ and /etc/localtime on Linux and macOS, and the zone set in Windows.

Result<void, DateError> main() {
var moment = try DateTime.utc(2026, 11, 15, 9, 30, 0)
var istanbul = try moment.withOffset(Duration.fromSeconds(3 * 3600))
print(istanbul)
print($"{istanbul.hour()} {istanbul.offset()} {istanbul.toUtc()}")
var parsed = try DateTimeOffset.parse("2026-11-18T12:30:05-05:00")
print($"{parsed} {parsed.toUtc()}")
match DateTime.parse("2026-11-18 12:30") {
Ok(t) => print(t)
Error(e) => print(e)
}
print(moment.withOffset(Duration.fromSeconds(86400)) is Error(InvalidOffset))
var now = DateTime.now()
print(now.toLocal().toUtc() == now)
return Ok()
}

It prints:

2026-11-15T12:30:00+03:00
12 10800s 2026-11-15T09:30:00Z
2026-11-18T12:30:05-05:00 2026-11-18T17:30:05Z
InvalidText(10)
true
true

DateError​

InvalidMonth, InvalidDay, InvalidHour, InvalidMinute, InvalidSecond (a second of 60 too: leap seconds are not counted), OutOfRange (outside the years a DateTime holds), InvalidOffset (a day or more either way, or a part of a second), SkippedLocalTime, and InvalidText(nint position), the place where a text stops being RFC 3339. The parts are checked in order, the month before the day, so that the day is checked against its month.

Clock​

Under these types lie three readings that only the module std can call: Clock.monotonic() for Instant, Clock.wall() for DateTime, and Clock.offsetAt(seconds) for the time zone. A program uses the types, so a reading always comes with its meaning:

void main() {
print(Clock.monotonic())
}
error: there is no variable or type named `Clock`

To wait, an async function awaits Task.delay(ms), and a deadline is CancellationSource.after(ms): see Tasks. Neither a const nor the condition of lock ... when may read the clock.