time library Time

The main API for dates, times and timezones.

All classes in this library are based on the ISO calendar system. It is not a goal to support other calendar systems.

All dates and times are all immutable. They are stored to microsecond precision. Weeks start on Monday and end on Sunday.

Except for the toNative() functions, classes do not use or return DateTimes. See sugar.time.interop for working with native DateTimes.

Dates and times

LocalDate stores a date without a time such as 2023-05-08.

LocalTime stores a time without a date such as 11:30.

LocalDateTime stores a date-time such as 2023-05-08 11:30.

OffsetTime stores a time with a fixed offset from UTC such as 11:30+08:00.

ZonedDateTime stores a date-time and timezone such as 2023-05-08T11:30+08:00[Asia/Singapore]. It is useful for representing date-times with a dynamic offset, typically due to Daylight Saving Time (DST). A class without a timezone should be preferred whenever possible.

Durations and Periods

A Duration stores a fixed amount of time in microseconds while a Period stores the conceptual units of time. For example, a duration of 1 day is always 86,400,000,000 microseconds while a period of 1 day is 1 "day". Adding either to a DateTime or ZonedDateTime nearing a DST transition can produce different results.

// DST occurs at 2023-03-12 02:00
// https://www.timeanddate.com/time/change/usa/detroit?year=2023

final datetime = ZoneDateTime('America/Detroit', 2023, 3, 12);

datetime.add(Duration(days: 1)); // 2023-03-13 01:00 [America/Detroit]
datetime + Period(days: 1);      // 2023-03-13 00:00 [America/Detroit]

Classes

LocalDate
A date without a timezone, as seen in a calendar, such as 2023-04-11.
LocalDateTime
A date-time without a timezone, such as 2023-04-10 09:30.
LocalTime
The time of the day without a timezone, as seen on a wall clock, such as. 12:30.
Offset
An offset is the time difference between a timezone and UTC.
OffsetTime
The time of the day with an offset from UTC/Greenwich, such as 10:15+08:00.
Period
A Period represents a quantity of time in terms of its individual parts.
TemporalUnit
A unit of date-time, such as days or hours.
ZonedDateTime
A date-time with a timezone such as 2023-04-13 10:15:30+08:00 Asia/Singapore.

Enums

DateUnit
A unit of date, such as months and days.
TimeUnit
A unit of time, such as hours and minutes.

Typedefs

DayMicroseconds = int
The microseconds in a day since midnight.
DayMilliseconds = int
The milliseconds in a day since midnight.
DaySeconds = int
The seconds in a day since midnight.
EpochDays = int
The days since Unix epoch, 1st January 1970.
EpochMicroseconds = int
The microseconds since Unix epoch, 1st January 1970.
EpochMilliseconds = int
The milliseconds since Unix epoch, 1st January 1970.
EpochSeconds = int
The seconds since Unix epoch, 1st January 1970.