Period class

A duration of time that understands human-scale units — including years and months.

Dart's built-in Duration only works with fixed-length units (days, hours, etc.). Period adds support for years and months, using approximate lengths (365 days/year, 30 days/month) so you can express things like "6 months" or "2 years" in a single object.

Internally, everything is stored as a total number of microseconds, which keeps arithmetic simple and consistent.

Creating a Period

final twoWeeks = Period(days: 14);
final halfYear = Period(months: 6);
final custom = Period(years: 1, months: 3, days: 15, hours: 8);

Arithmetic

Periods support addition, subtraction, multiplication, and negation:

final doubled = twoWeeks * 2;
final combined = halfYear + twoWeeks;
final inverted = -twoWeeks;

Using with Moment

The primary use case is shifting Moment values forward or backward:

final nextMonth = Moment.now() + Period(months: 1);
final lastYear = Moment.now() - Period(years: 1);

Constructors

Period({int years = 0, int months = 0, int days = 0, int hours = 0, int minutes = 0, int seconds = 0, int milliseconds = 0, int microseconds = 0}): Creates a Period from human-friendly units.
const

Properties

hashCode → int: The hash code for this object.
no setteroverride
isNegative → bool: Returns true if this period represents a negative duration (going backward in time).
no setter
moment → Moment: Converts this period into a Moment anchored at the Unix epoch (1970-01-01), effectively treating the stored microseconds as an absolute timestamp.
no setter
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited

Methods

abs() → Period: Returns the absolute (non-negative) version of this period.
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
toString() → String: A string representation of this object.
override

Operators

operator *(num factor) → Period: Returns a new Period scaled by factor.
operator +(Period other) → Period: Returns a new Period that is the sum of this and other.
operator -(Period other) → Period: Returns a new Period that is the difference of this and other.
operator <(Period other) → bool: Returns true if this period is shorter than other.
operator <=(Period other) → bool: Returns true if this period is shorter than or equal to other.
operator ==(Object other) → bool: The equality operator.
override
operator >(Period other) → bool: Returns true if this period is longer than other.
operator >=(Period other) → bool: Returns true if this period is longer than or equal to other.
operator unary-() → Period: Returns the negation of this period (flips the sign).

Constants

hoursPerDay → const int: Hours in one day (24).
microsecondsPerDay → const int: Microseconds in one day (86,400,000,000).
microsecondsPerHour → const int: Microseconds in one hour (3,600,000,000).
microsecondsPerMillisecond → const int: Microseconds in one millisecond (1,000).
microsecondsPerMinute → const int: Microseconds in one minute (60,000,000).
microsecondsPerSecond → const int: Microseconds in one second (1,000,000).
millisecondsPerDay → const int: Milliseconds in one day (86,400,000).
millisecondsPerHour → const int: Milliseconds in one hour (3,600,000).
millisecondsPerMinute → const int: Milliseconds in one minute (60,000).
millisecondsPerSecond → const int: Milliseconds in one second (1,000).
minutesPerDay → const int: Minutes in one day (1,440).
minutesPerHour → const int: Minutes in one hour (60).
secondsPerDay → const int: Seconds in one day (86,400).
secondsPerHour → const int: Seconds in one hour (3,600).
secondsPerMinute → const int: Seconds in one minute (60).