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
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.