tempo

Description:

tempo

A complete time and date solution that replaces Dart's core
DateTime with a rich set of date and time
classes, advanced arithmetic features and full time zone
support.
Features #
Everything DateTime can do, plus:

Local and zoned date and time classes
Period arithmetic:

Add and subtract months or years without changing the day or time
Count the number of years, months and days between two dates


Create and parse ISO 8601 strings
Easy conversion to and from DateTime
Lookup time zones by name, country and geographic coordinates
Nanosecond precision

Quick start #
import 'package:tempo/tempo.dart';
copied to clipboard
We'll use a local datetime to get started, but all of the classes largely
work the same. First, these all create the exact same date and time
of May 1, 2023 at 12:00 PM:
LocalDateTime(2023, 5, 1, 12, 0);
LocalDateTime.parse('2023-05-01T12:00');
LocalDateTime.fromDateTime(DateTime(2023, 5, 1, 12, 0));
copied to clipboard
You can also get the current date and time:
LocalDateTime.now();
copied to clipboard
And you can convert back to a Dart core DateTime if necessary:
LocalDateTime(2023, 5, 1, 12, 0).toDateTime() == DateTime(2023, 5, 1, 12, 0);
copied to clipboard
Add a fixed Timespan of 30 days, 3 minutes (Timespan replaces
the Dart core Duration class):
var dt = LocalDateTime(2023, 5, 1, 12, 0);
var span = Timespan(days: 30, minutes: 3);
dt.plusTimespan(span) == LocalDateTime(2023, 5, 31, 12, 3);
copied to clipboard
Find the amount of time between two dates:
var dt1 = LocalDateTime(2023, 5, 1, 12, 0);
var dt2 = LocalDateTime(2023, 6, 1, 14, 3);
dt1.timespanUntil(dt2) == Timespan(days: 31, hours: 2, minutes: 3);
copied to clipboard
Comparisons:
var dt1 = LocalDateTime(2023, 5, 6, 12, 0);
var dt2 = LocalDateTime(2023, 5, 6, 13, 0);
dt1 != dt2;
dt1 < dt2;
dt2 > dt1;
dt1.compareTo(dt2) == -1;
copied to clipboard
Add a Period of 1 month. Unlike Timespan, the exact
amount of time a Period covers varies. Some months are shorter than others:
var dt = LocalDateTime(2023, 5, 1, 12, 0);
var period = Period(months: 1);
dt.plusPeriod(period) == LocalDateTime(2023, 6, 1, 12, 0);
copied to clipboard
Find the Period between one LocalDate and another
(this works for any combination of LocalDate and LocalDateTime):
var date1 = LocalDate(2023, 1, 1);
var date2 = LocalDate(2024, 3, 2);
date1.periodUntil(date2) == Period(years: 1, months: 2, days: 1);
copied to clipboard
An OffsetDateTime with a fixed offset from UTC:
var offset = ZoneOffset(-7);
OffsetDateTime(offset, 2000, 4, 21, 12, 30);
copied to clipboard
A ZonedDateTime with a proper time zone:
ZonedDateTime('America/Los_Angeles', 2023, 5, 9, 10, 47);
copied to clipboard
Both OffsetDateTime and ZonedDateTime
contain an offset from UTC and represent an absolute moment in time.
This moment is stored in an Instant:
Instant.now();
Instant.fromUnix(Timespan(seconds: 1683654985));
OffsetDateTime(ZoneOffset(3), 2023, 1, 2, 3).asInstant;
ZonedDateTime('America/Los_Angeles', 2023, 1, 2, 3).asInstant;
copied to clipboard
You can get a list of time zones nearest to a geographical
location, optionally filtered by country. All of these functions return
a list of ZoneDescription:
timeZonesByProximity(latitude, longitude);
timeZonesByProximity(latitude, longitude, country: 'US');
copied to clipboard
You can list all time zones in a given country:
timeZonesForCountry('CA');
copied to clipboard
Or you can just list them all:
allTimeZones();
copied to clipboard
Testing #
This package also contains a testing library with a useful set
of matchers for your unit tests that produce helpful error messages.
import 'package:tempo/testing.dart';

var dt = LocalDateTime(2020, 1, 2, 3, 4);
expect(dt, hasYear(2020));
expect(dt, hasHour(4));
expect(dt, hasDate(2020, 1, 2));
expect(dt, hasTime(3, 4));
copied to clipboard
Additional information #

Tempo API documentation
Testing API documentation
File a bug