tempo library

A date and time library that replaces the standard dart:core DateTime and Duration classes.

This is heavily inspired by the java.time package in Java 8+, although there are plenty of differences.

Overview

This library can be broken down into four main categories: local dates and times, absolute dates and times, periods and timespans, time zone lookups.

Conversions

Converting from one type to another is designed to be as consistent as possible, and the method names for doing so are the same no matter what you're converting from. Note, however, that conversions will often lose information (such as time zones). See the documentation for the specific method you're calling for any caveats.

Dates and times:

Target Conversion
DateTime toDateTime()
Instant toInstant()
OffsetDateTime atOffset()
ZonedDateTime inTimezone()
LocalDateTime toLocal()
LocalDate toLocal().date
LocalTime toLocal().time

The DateTime extension method TempoDateTime.toLocalDateTime is an exception to the above. This is necessary because DateTime already has a toLocal method.

Relative times:

Target Conversion
Duration toDuration()
Timespan toTimespan()

Note: Period has no associated conversion methods, because it doesn't represent a fixed amount of time. There's no general way to make such a conversion. If you must convert something to a Period, you'll need to do what makes sense for your application. (The only potentially legitimate reason for this is working with an API you can't change. If you need to for some other reason, you may need to re-evaluate your approach. In either case, sticking with Duration and Timespan may be the safest approach.)

Here are some examples:

var dt = DateTime.utc(2025, 1, 1);
dt.toLocal() == LocalDate(2025, 1, 1);
dt.toInstant() == Instant.fromUnix(Timespan(seconds: 1735689600));
dt.atOffset(ZoneOffset(-5)) =
  OffsetDateTime(ZoneOffset(-5), 2024, 12, 31, 19, 0);
dt.inTimeZone('America/New_York') ==
  ZonedDateTime.withZoneId('America/New_York', 2024, 12, 31, 19, 0);

var LocalDateTime ldt = LocalDateTime(2025, 1, 1);
ldt.inTimeZone('America/New_York') ==
   ZonedDateTime.withZoneId('America/New_York', 2025, 1, 1);

var zdt = ZonedDateTime(2025, 1, 1);
zdt.toLocal() == LocalDateTime(2025, 1, 1);

Formatting

Date and time objects may be formatted and parsed as ISO 8601 strings, and formatted using the intl package.

ISO 8601

Local, absolute, and relative times may all be formatted as ISO 8601 strings either by calling their toString methods, or interpolating them into a string:

final d = ZonedDateTime.withZoneId('America/Los_Angeles', 2025, 1, 2, 3, 4, 5, 6);
print(d.toString);  // Outputs '2025-01-02T03:04:05.000000006-0800'
print('Date: $d');  // Outputs 'Date: 2025-01-02T03:04:05.000000006-0800'

Similarly, they can all be parsed by using their parse constructors:

OffsetDateTime.parse('2025-01-02T03:04:05+0200');
ZonedDateTime.parse('2025-01-02T03:04:05-0800');

Custom formats with intl

All local and absolute time objects have a format method that accepts a DateFormat object and returns a string. Since different objects convert to DateTime differently, using tempo's format methods instead of calling DateFormat.format directly can avoid some surprising results.

final dtFormat = DateTime.yMMMd().add_Hm();
final date = ZonedDateTime(2005, 1, 2, 3, 4);

// Do this:
date.format(dtFormat) == 'Jan 2, 2025 03:04';

// Don't do this:
dtFormat.format(date.toDateTime()) == '???';

Classes

HasDate Local times
Interface implemented by objects that have a date on the ISO 8601 calendar.
HasDateTime Local times
Interface for classes that provide date and time fields.
HasInstant Absolute times
Interface implemented by any class that is tied to a specific Instant in time.
HasTime Local times
Interface implemented by classes that provide the time of day.
Instant Absolute times
Represents a single instant in time as a Timespan since January 1, 1970 UTC.
LocalDate Local times
A date with no timezone.
LocalDateTime Local times
A date and time with no time zone.
LocalTime Local times
A time of day without a time zone.
NamedZoneOffset Absolute times
A ZoneOffset with an associated name.
OffsetDateTime Absolute times
A date and time at a fixed offset from UTC.
Period Relative times
Represents a period between two dates on a calendar.
RelativeTime Relative times
Either a Timespan or a Period.
Timespan Relative times
A duration of time with nanosecond precision.
ZonedDateTime Absolute times
A date and time in a specific time zone.
ZoneDescription Time zone lookups
Information about a time zone that may be helpful when trying to choose one.
ZoneOffset Absolute times
A time zone offset from UTC.

Enums

Weekday
The day of the week.

Extensions

TempoDateTime on DateTime
Adds Tempo conversion methods to the standard DateTime class.
TempoDuration on Duration
Adds Tempo conversion methods to the standard Duration class.

Properties

defaultZoneId ↔ String
The default time zone id.
getter/setter pair

Functions

allTimeZones() → List<ZoneDescription> Time zone lookups
Returns a table of time zones with information useful for choosing one.
timeZonesByProximity(double latitude, double longitude, [String? country]) → List<ZoneDescription> Time zone lookups
Provides a list of time zones sorted by proximity to a given set of geographic coordinates. Optionally filters by country.
timeZonesForCountry(String country) → List<ZoneDescription> Time zone lookups
Provides a list of time zones relevant to a specific country.