Periods

A Period represents an interval of years, months and days. Unlike Timespan which is an exact amount, Period represents a more fluid interval of time. The exact amount depends on which years, months and days it’s applied to.

You can make one with any combination of years, months or days:

Period(years: 3);
Period(months: 2, days: 25);

Periods represent time intervals the way humans tend to think about them. Adding or subtracting a period from a datetime takes the length of the specific years, months and days into account.

For example, adding a Period of one month to February 3, 2025 gives March 3, 2025 at the same time of day:

final date = LocalDateTime(2025, 2, 3, 12, 49);
date.plusPeriod(Period(months: 1)) == LocalDateTime(2025, 3, 3, 12, 49);

You can also find the period of time between two dates. For example, the time period between January 3 and March 3, is always exactly two months. Even on a leap year:

LocalDate(2024, 1, 3).periodUntil(LocalDate(2024, 3, 3)) ==
  Period(months: 2);

It’s important to note that a Period of n days is not the same as a Timespan of n days. A Timespan is a fixed amount of time. So a Timespan of one day represents exactly 24 hours. A Period of one day, on the other hand, could be more or less than that, depending on the day in question.

This distinction is particularly important for ZonedDateTime. Civil time usually has discontinuities. The time may be adjusted forward or back in the spring and fall. Or it may just be changed by government decree.

Using the same example from Timespans, what is the Period between November 1, 2025 at 12:30 PM and November 2, 2025 at the same time of day?

defaultZoneId = 'America/Los_Angeles';
final date1 = ZonedDateTime(2025, 11, 1, 12, 30);
final date2 = ZonedDateTime(2025, 11, 2, 12, 30);
date1.timespanUntil(date2) // == What?

If you answered one day, or Period(days: 1), good work. You’re getting the hang of this. Just remember that Timespan is for exact time intervals, and Period is for calendar intervals.