ZoneEqualityComparerOptions class

Options to use when comparing time zones for equality. Each option makes the comparison more restrictive.

By default, the comparer only compares the wall offset (total of standard offset and any daylight saving offset) at every instant within the interval over which the comparer operates. In practice, this is done by comparing each ZoneInterval which includes an instant within the interval (using DateTimeZone.getZoneIntervals(Interval)). For most purposes, this is all that's required: from the simple perspective of a time zone being just a function from instants to local time, the default option of onlyMatchWallOffset effectively checks that the function gives the same result across the two time zones being compared, for any given instant within the interval.

It's possible for a time zone to have a transition from one ZoneInterval to another which doesn't adjust the offset: it might just change the name, or the balance between standard offset to daylight saving offset. (As an example, at midnight local time on October 27th 1968, the Europe/London time zone went from a standard offset of 0 and a daylight saving offset of 1 hour to a standard offset of 1 and a daylight saving offset of 0... which left the clocks unchanged.) This transition is irrelevant to the default options, so the two zone intervals involved are effectively coalesced.

The options available change what sort of comparison is performed - which can also change which zone intervals can be coalesced. For example, by specifying just the matchAllTransitions option, you would indicate that even though you don't care about the name within a zone interval or how the wall offset is calculated, you do care about the fact that there was a transition at all, and when it occurred. With that option enabled, zone intervals are never coalesced and the transition points within the operating interval are checked.

Similarly, the matchStartAndEndTransitions option is the only one where instants outside the operating interval are relevant. For example, consider a comparer which operates over the interval [2000-01-01T00:00:00Z, 2011-01-01T00:00:00Z). Normally, anything that happens before the year 2000 (UTC) would be irrelevant - but with this option enabled, the transitions of the first and last zone intervals are part of the comparison... so if one time zone has a zone interval 1999-09-01T00:00:00Z to 2000-03-01T00:00:00Z and the other has a zone interval 1999-10-15T00:00:00Z to 2000-03-01T00:00:Z, the two zones would be considered unequal, despite the fact that the only instants observing the difference occur outside the operating interval.

Annotations
  • @immutable

Constructors

ZoneEqualityComparerOptions(int _value)
const

Properties

hashCode → int
The hash code for this object.
no setteroverride
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
value → int
no setter

Methods

noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
parse(String text) → ZoneEqualityComparerOptions?
toString() → String
A string representation of this object.
override

Constants

matchAllTransitions → const ZoneEqualityComparerOptions
This option prevents adjacent zone intervals from being coalesced, even if they are otherwise considered equivalent according to other options.
matchNames → const ZoneEqualityComparerOptions
Compare the names of zone intervals as well as offsets.
matchOffsetComponents → const ZoneEqualityComparerOptions
Instead of only comparing wall offsets, the standard/savings split is also considered. So when this option is used, two zones which both have a wall offset of +2 at one instant would be considered unequal if one of those offsets was +1 standard, +1 savings and the other was +2 standard with no daylight saving.
matchStartAndEndTransitions → const ZoneEqualityComparerOptions
Includes the transitions into the first zone interval and out of the last zone interval as part of the comparison, even if they do not affect the offset or name for any instant within the operating interval.
onlyMatchWallOffset → const ZoneEqualityComparerOptions
The default comparison, which only cares about the wall offset at any particular instant, within the interval of the comparer. In other words, if DateTimeZone.getUtcOffset returns the same value for all instants in the interval, the comparer will consider the zones to be equal.
strictestMatch → const ZoneEqualityComparerOptions
The combination of all available match options.