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.
| Signature | What it does |
|---|---|
Duration Duration.fromNanoseconds(long count), fromMicroseconds, fromMilliseconds, fromSeconds | A span of so many units |
long nanoseconds(read this), microseconds, milliseconds, seconds | The 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
| Signature | What 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.
| Signature | What 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, nanosecond | The parts, in UTC |
DayOfWeek dayOfWeek(read this) | Monday to Sunday |
long unixSeconds(read this), unixMilliseconds | The count since 1970, rounded down |
Duration since(read this, DateTime earlier) | The time from earlier to this |
DateTime plus(read this, Duration span), minus | A 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.
| Signature | What 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, dayOfWeek | The parts as the clocks of the place show them |
since, plus, minus, compare | As 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.