Class DateTimeZone

Represents a time zone - a mapping between UTC and local time. A time zone maps UTC instants to local times - or, equivalently, to the offset from UTC at any particular instant.
Since 1.0.x
Availability net35-Client, PCL
Inheritance
Object
DateTimeZone
BclDateTimeZone
Implements
IEquatable<DateTimeZone>
Inherited Members
Object.Equals(Object, Object)
Object.ReferenceEquals(Object, Object)
Object.GetType()
Object.MemberwiseClone()
Namespace: NodaTime
Assembly: NodaTime.dll
Syntax
public abstract class DateTimeZone : IEquatable<DateTimeZone>, IZoneIntervalMap
Remarks

The mapping is unambiguous in the "UTC to local" direction, but the reverse is not true: when the offset changes, usually due to a Daylight Saving transition, the change either creates a gap (a period of local time which never occurs in the time zone) or an ambiguity (a period of local time which occurs twice in the time zone). Mapping back from local time to an instant requires consideration of how these problematic times will be handled.

Noda Time provides various options when mapping local time to a specific instant:

Noda Time has two built-in sources of time zone data available: a copy of the tz database (also known as the IANA Time Zone database, or zoneinfo or Olson database), and the ability to convert .NET's own System.TimeZoneInfo format into a "native" Noda Time zone. Which of these is most appropriate for you to use will very much depend on your exact needs. The zoneinfo database is widely used outside Windows, and has more historical data than the Windows-provided information, but if you need to interoperate with other Windows systems by specifying time zone IDs, you may wish to stick to the Windows time zones.

To obtain a DateTimeZone for a given timezone ID, use one of the methods on IDateTimeZoneProvider (and see DateTimeZoneProviders for access to the built-in providers). The UTC timezone is also available via the Utc property on this class.

To obtain a DateTimeZone representing the system default time zone, you can either call GetSystemDefault() on a provider to obtain the DateTimeZone that the provider considers matches the system default time zone, or you can construct a BclDateTimeZone via BclDateTimeZone.ForSystemDefault, which returns a DateTimeZone that wraps the system local System.TimeZoneInfo. The latter will always succeed, but has access only to that information available via the .NET time zone; the former may contain more complete data, but may (in uncommon cases) fail to find a matching DateTimeZone. Note that BclDateTimeZone is not available on the PCL build of Noda Time, so this fallback strategy can only be used with the desktop version.

Note that Noda Time does not require that DateTimeZone instances be singletons. As far as reasonably possible, implementations should implement System.IEquatable<T> in such a way that equivalent time zones compare as equal.

Constructors

DateTimeZone(String, Boolean, Offset, Offset)

Initializes a new instance of the DateTimeZone class.
Since 1.0.x
Availability net35-Client, PCL
Declaration
protected DateTimeZone(string id, bool isFixed, Offset minOffset, Offset maxOffset)
Parameters
Type Name Description
String id The unique id of this time zone.
Boolean isFixed Set to true if this time zone has no transitions.
Offset minOffset Minimum offset applied within this zone
Offset maxOffset Maximum offset applied within this zone

Properties

Id

The provider's ID for the time zone.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public string Id { get; }
Property Value
Type Description
String
Remarks

This identifies the time zone within the current time zone provider; a different provider may provide a different time zone with the same ID, or may not provide a time zone with that ID at all.

MaxOffset

Returns the greatest (most positive) offset within this time zone, over all time.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public Offset MaxOffset { get; }
Property Value
Type Description
Offset

MinOffset

Returns the least (most negative) offset within this time zone, over all time.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public Offset MinOffset { get; }
Property Value
Type Description
Offset

Utc

Gets the UTC (Coordinated Universal Time) time zone. This is a single instance which is not provider-specific; it is guaranteed to have the ID "UTC", but may or may not be the instance returned by e.g. DateTimeZoneProviders.Tzdb["UTC"].
Since 1.0.x
Availability net35-Client, PCL
Declaration
public static DateTimeZone Utc { get; }
Property Value
Type Description
DateTimeZone A UTC DateTimeZone.

Methods

AtLeniently(LocalDateTime)

Maps the given LocalDateTime to the corresponding ZonedDateTime in a lenient manner: ambiguous values map to the later of the alternatives, and "skipped" values map to the start of the zone interval after the "gap".
Since 1.0.x
Availability net35-Client, PCL
Declaration
public ZonedDateTime AtLeniently(LocalDateTime localDateTime)
Parameters
Type Name Description
LocalDateTime localDateTime The local date/time to map.
Returns
Type Description
ZonedDateTime The unambiguous mapping if there is one, the later result if the mapping is ambiguous, or the start of the later zone interval if the given local date/time is skipped.
Remarks
See AtStrictly(LocalDateTime) and ResolveLocal(LocalDateTime, ZoneLocalMappingResolver) for alternative ways to map a local time to a specific instant.

AtStartOfDay(LocalDate)

Returns the earliest valid ZonedDateTime with the given local date.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public ZonedDateTime AtStartOfDay(LocalDate date)
Parameters
Type Name Description
LocalDate date The local date to map in this time zone.
Returns
Type Description
ZonedDateTime The ZonedDateTime representing the earliest time in the given date, in this time zone.
Remarks
If midnight exists unambiguously on the given date, it is returned. If the given date has an ambiguous start time (e.g. the clocks go back from 1am to midnight) then the earlier ZonedDateTime is returned. If the given date has no midnight (e.g. the clocks go forward from midnight to 1am) then the earliest valid value is returned; this will be the instant of the transition.
Exceptions
Type Condition
SkippedTimeException The entire day was skipped due to a very large time zone transition. (This is extremely rare.)

AtStrictly(LocalDateTime)

Maps the given LocalDateTime to the corresponding ZonedDateTime, if and only if that mapping is unambiguous in this time zone. Otherwise, SkippedTimeException or AmbiguousTimeException is thrown, depending on whether the mapping is ambiguous or the local date/time is skipped entirely.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public ZonedDateTime AtStrictly(LocalDateTime localDateTime)
Parameters
Type Name Description
LocalDateTime localDateTime The local date and time to map into this time zone.
Returns
Type Description
ZonedDateTime The unambiguous matching ZonedDateTime if it exists.
Remarks
See AtLeniently(LocalDateTime) and ResolveLocal(LocalDateTime, ZoneLocalMappingResolver) for alternative ways to map a local time to a specific instant.
Exceptions
Type Condition
SkippedTimeException The given local date/time is skipped in this time zone.
AmbiguousTimeException The given local date/time is ambiguous in this time zone.

Equals(DateTimeZone)

Determines whether the specified DateTimeZone is equal to this instance.
Since 1.0.x
Availability net35-Client, PCL
Declaration
[Obsolete("General DateTimeZone equality is not supported in 2.0")]
public bool Equals(DateTimeZone obj)
Parameters
Type Name Description
DateTimeZone obj The DateTimeZone to compare with this instance.
Returns
Type Description
Boolean true if the specified DateTimeZone is equal to this instance; otherwise, false.
Remarks
This implementation performs initial checks which would be common to all child implementations, and then delegates to EqualsImpl(DateTimeZone).

Equals(Object)

Determines whether the specified System.Object is equal to this instance.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public override sealed bool Equals(object obj)
Parameters
Type Name Description
Object obj The System.Object to compare with this instance.
Returns
Type Description
Boolean true if the specified System.Object is equal to this instance; otherwise, false.
Overrides
System.Object.Equals(System.Object)

EqualsImpl(DateTimeZone)

Implements equality in derived classes.
Since 1.0.x
Availability net35-Client, PCL
Declaration
[Obsolete("General DateTimeZone equality is not supported in 2.0")]
protected abstract bool EqualsImpl(DateTimeZone zone)
Parameters
Type Name Description
DateTimeZone zone The zone to compare with this one. This is guaranteed (when called by Equals(DateTimeZone)) to be a non-null reference of the same type as this instance.
Returns
Type Description
Boolean true if the specified DateTimeZone is equal to this instance; otherwise, false.

ForOffset(Offset)

Returns a fixed time zone with the given offset.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public static DateTimeZone ForOffset(Offset offset)
Parameters
Type Name Description
Offset offset The offset for the returned time zone
Returns
Type Description
DateTimeZone A fixed time zone with the given offset.
Remarks

The returned time zone will have an ID of "UTC" if the offset is zero, or "UTC+/-Offset" otherwise. In the former case, the returned instance will be equal to Utc.

Note also that this method is not required to return the same DateTimeZone instance for successive requests for the same offset; however, all instances returned for a given offset will compare as equal.

GetHashCode()

Returns a hash code for this instance.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public abstract override int GetHashCode()
Returns
Type Description
Int32 A hash code for this instance, suitable for use in hashing algorithms and data structures like a hash table.
Overrides
System.Object.GetHashCode()

GetUtcOffset(Instant)

Returns the offset from UTC, where a positive duration indicates that local time is later than UTC. In other words, local time = UTC + offset.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public virtual Offset GetUtcOffset(Instant instant)
Parameters
Type Name Description
Instant instant The instant for which to calculate the offset.
Returns
Type Description
Offset The offset from UTC at the specified instant.
Remarks
This is mostly a convenience method for calling GetZoneInterval(instant).WallOffset, although it can also be overridden for more efficiency.

GetZoneInterval(Instant)

Gets the zone interval for the given instant; the range of time around the instant in which the same Offset applies (with the same split between standard time and daylight saving time, and with the same offset).
Since 1.0.x
Availability net35-Client, PCL
Declaration
public abstract ZoneInterval GetZoneInterval(Instant instant)
Parameters
Type Name Description
Instant instant The Instant to query.
Returns
Type Description
ZoneInterval The defined ZoneInterval.
Remarks
This will always return a valid zone interval, as time zones cover the whole of time.
See Also

GetZoneIntervals(Instant, Instant)

Returns all the zone intervals which occur for any instant in the interval [start, end).
Since 1.1.x
Availability net35-Client, PCL
Declaration
public IEnumerable<ZoneInterval> GetZoneIntervals(Instant start, Instant end)
Parameters
Type Name Description
Instant start Inclusive start point of the interval for which to retrieve zone intervals.
Instant end Exclusive end point of the interval for which to retrieve zone intervals.
Returns
Type Description
IEnumerable<ZoneInterval> A sequence of zone intervals covering the given interval.
Remarks

This method is simply a convenience method for calling GetZoneIntervals(Interval) without explicitly constructing the interval beforehand.

Exceptions
Type Condition
ArgumentOutOfRangeException end is earlier than start.
See Also

GetZoneIntervals(Interval)

Returns all the zone intervals which occur for any instant in the given interval.
Since 1.1.x
Availability net35-Client, PCL
Declaration
public IEnumerable<ZoneInterval> GetZoneIntervals(Interval interval)
Parameters
Type Name Description
Interval interval Interval to find zone intervals for.
Returns
Type Description
IEnumerable<ZoneInterval> A sequence of zone intervals covering the given interval.
Remarks

The zone intervals are returned in chronological order. This method is equivalent to calling GetZoneInterval(Instant) for every instant in the interval and then collapsing to a set of distinct zone intervals. The first and last zone intervals are likely to also cover instants outside the given interval; the zone intervals returned are not truncated to match the start and end points.

See Also

MapLocal(LocalDateTime)

Returns complete information about how the given LocalDateTime is mapped in this time zone.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public ZoneLocalMapping MapLocal(LocalDateTime localDateTime)
Parameters
Type Name Description
LocalDateTime localDateTime The local date and time to map in this time zone.
Returns
Type Description
ZoneLocalMapping A mapping of the given local date and time to zero, one or two zoned date/time values.
Remarks

Mapping a local date/time to a time zone can give an unambiguous, ambiguous or impossible result, depending on time zone transitions. Use the return value of this method to handle these cases in an appropriate way for your use case.

As an alternative, consider ResolveLocal(LocalDateTime, ZoneLocalMappingResolver), which uses a caller-provided strategy to convert the ZoneLocalMapping returned here to a ZonedDateTime.

ResolveLocal(LocalDateTime, ZoneLocalMappingResolver)

Maps the given LocalDateTime to the corresponding ZonedDateTime, following the given ZoneLocalMappingResolver to handle ambiguity and skipped times.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public ZonedDateTime ResolveLocal(LocalDateTime localDateTime, ZoneLocalMappingResolver resolver)
Parameters
Type Name Description
LocalDateTime localDateTime The local date and time to map in this time zone.
ZoneLocalMappingResolver resolver The resolver to apply to the mapping.
Returns
Type Description
ZonedDateTime The result of resolving the mapping.
Remarks

This is a convenience method for calling MapLocal(LocalDateTime) and passing the result to the resolver. Common options for resolvers are provided in the static Resolvers class.

See AtStrictly(LocalDateTime) and AtLeniently(LocalDateTime) for alternative ways to map a local time to a specific instant.

Exceptions
Type Condition
ArgumentNullException resolver is null.

ToString()

Returns the ID of this time zone.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public override string ToString()
Returns
Type Description
String The ID of this time zone.
Overrides
System.Object.ToString()

Implements

System.IEquatable<T>