tempo 0.7.0

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.

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';

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));

You can also get the current date and time:

LocalDateTime.now();

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);

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);

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);

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;

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);

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);

An OffsetDateTime with a fixed offset from UTC:

var offset = ZoneOffset(-7);
OffsetDateTime(offset, 2000, 4, 21, 12, 30);

A ZonedDateTime with a proper time zone:

// Default time zone:
ZonedDateTime(2023, 5, 9, 10, 47);
// Specified time zone:
ZonedDateTime.withZoneId('America/Los_Angeles', 2023, 5, 9, 10, 47);

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).toInstant();
ZonedDateTime('America/Los_Angeles', 2023, 1, 2, 3).toInstant();

The default for ZonedDateTime and OffsetDateTime is "UTC." You can change this by setting defaultZoneId:

defaultZoneId = 'America/Los_Angeles';

Determining the system time zone in plain Dart in a portable way is impossible. However, if you're using Flutter, you have options. I recommend the flutter_timezone package.

import 'package:flutter_timezone/flutter_timezone.dart';

defaultZoneId = await FlutterTimeZone.getLocalTimeZone();

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');

You can list all time zones in a given country:

timeZonesForCountry('CA');

Or you can just list them all:

allTimeZones();

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));

Additional information

• Tempo API documentation
• Testing API documentation
• File a bug