Period class

Represents a period of time expressed in human chronological terms: hours, days, weeks, months and so on.

A Period contains a set of properties such as years, months, and so on that return the number of each unit contained within this period. Note that these properties are not normalized in any way by default, and so a Period may contain values such as '2 hours and 90 minutes'. The normalize method will convert equivalent periods into a standard representation.

Periods can contain negative units as well as positive units ('+2 hours, -43 minutes, +10 seconds'), but do not differentiate between properties that are zero and those that are absent (i.e. a period created as '10 years' and one created as '10 years, zero months' are equal periods; the months property returns zero in both cases).

Period equality is implemented by comparing each property's values individually.

Periods operate on calendar-related types such as LocalDateTime whereas Time operates on Instants on the time line. (Note that although ZonedDateTime includes both concepts, it only supports Time-based arithmetic.)

Annotations

• @immutable

Constructors

Period({int years = 0, int months = 0, int weeks = 0, int days = 0, int hours = 0, int minutes = 0, int seconds = 0, int milliseconds = 0, int microseconds = 0, int nanoseconds = 0})

Creates a period with the given time values.

const

Properties

days → int

Gets the number of days within this period.

final

hasDateComponent → bool

Returns whether or not this period contains any non-zero date-based properties (days or higher).

no setter

hashCode → int

Returns the hash code for this period.

no setter, override

hasTimeComponent → bool

Returns whether or not this period contains any non-zero-valued time-based properties (hours or lower).

no setter

hours → int

Gets the number of hours within this period.

final

microseconds → int

Gets the number of microseconds within this period.

final

milliseconds → int

Gets the number of milliseconds within this period.

final

minutes → int

Gets the number of minutes within this period.

final

months → int

Gets the number of months within this period.

final

nanoseconds → int

Gets the number of nanoseconds within this period.

final

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

seconds → int

Gets the number of seconds within this period.

final

weeks → int

Gets the number of weeks within this period.

final

years → int

Gets the number of years within this period.

final

Methods

equals(Period other) → bool

Compares the given period for equality with this one.

normalize() → Period

Returns a normalized version of this period, such that equivalent (but potentially non-equal) periods are changed to the same representation.

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

toBuilder() → PeriodBuilder

Creates a PeriodBuilder from this instance. The new builder is populated with the values from this period, but is then detached from it: changes made to the builder are not reflected in this period.

toString() → String

Returns this string formatted according to the PeriodPattern.roundtrip.

override

toTime() → Time

For periods that do not contain a non-zero number of years or months, returns a duration for this period assuming a standard 7-day week, 24-hour day, 60-minute hour etc.

Operators

operator +(Period other) → Period

Adds two periods together, by simply adding the values for each property.

operator -(Period other) → Period

Subtracts one period from another, by simply subtracting each property value.

operator ==(Object other) → bool

The equality operator.

override

Static Properties

NormalizingEqualityComparer → dynamic

Returns an equality comparer which compares periods by first normalizing them - so 24 hours is deemed equal to 1 day, and so on. Note that as per the normalize method, years and months are unchanged by normalization - so 12 months does not equal 1 year.

no setter

Static Methods

createComparer(LocalDateTime baseDateTime) → _PeriodComparer

Creates an Comparer for periods, using the given 'base' local date/time.

differenceBetweenDates(LocalDate start, LocalDate end, [PeriodUnits units = PeriodUnits.yearMonthDay]) → Period

Returns the exact difference between two dates or returns the period between a start and an end date, using only the given units.

differenceBetweenDateTime(LocalDateTime start, LocalDateTime end, [PeriodUnits units = PeriodUnits.dateAndTime]) → Period

Returns the exact difference between two date/times or returns the period between a start and an end date/time, using only the given units.

differenceBetweenTimes(LocalTime start, LocalTime end, [PeriodUnits units = PeriodUnits.allTimeUnits]) → Period

Returns the exact difference between two times or returns the period between a start and an end time, using only the given units.

Constants

zero → const Period

A period containing only zero-valued properties.