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 net45, netstandard1.3, netstandard2.0
Inheritance
Object
DateTimeZone
BclDateTimeZone
Inherited Members
Object.Equals(Object)
Object.Equals(Object, Object)
Object.ReferenceEquals(Object, Object)
Object.GetHashCode()
Object.GetType()
Object.MemberwiseClone()
Namespace: NodaTime
Assembly: NodaTime.dll
Syntax
public abstract class DateTimeZone : IZoneIntervalMapWithMinMax, 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 .NET Standard 1.3 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. Comparing two time zones for equality is not straightforward: if you care about whether two zones act the same way within a particular portion of time, use ZoneEqualityComparer. Additional guarantees are provided by IDateTimeZoneProvider and ForOffset(Offset).

Constructors

DateTimeZone(String, Boolean, Offset, Offset)

Initializes a new instance of the DateTimeZone class.
Since 1.0.x
Availability net45, netstandard1.3, netstandard2.0
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
Exceptions
Type Condition
ArgumentNullException id is null.

Properties

Id

Get the provider's ID for the time zone.
Since 1.0.x
Availability net45, netstandard1.3, netstandard2.0
Declaration
public string Id { get; }
Property Value
Type Description
String The provider's ID for the time zone. (The value returned is never null.)
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

Gets the greatest (most positive) offset within this time zone, over all time.
Since 1.0.x
Availability net45, netstandard1.3, netstandard2.0
Declaration
public Offset MaxOffset { get; }
Property Value
Type Description
Offset The greatest (most positive) offset within this time zone, over all time.

MinOffset

Gets the least (most negative) offset within this time zone, over all time.
Since 1.0.x
Availability net45, netstandard1.3, netstandard2.0
Declaration
public Offset MinOffset { get; }
Property Value
Type Description
Offset The least (most negative) offset within this time zone, over all time.

Utc

Gets the UTC (Coordinated Universal Time) time zone.
Since 1.0.x
Availability net45, netstandard1.3, netstandard2.0
Declaration
public static DateTimeZone Utc { get; }
Property Value
Type Description
DateTimeZone A UTC DateTimeZone. (The value returned is never null.)
Remarks
This is a single instance which is not provider-specific; it is guaranteed to have the ID "UTC", and to compare equal to an instance returned by calling ForOffset(Offset) with an offset of zero, but it may or may not compare equal to an instance returned by e.g. DateTimeZoneProviders.Tzdb["UTC"].

Methods

AtLeniently(LocalDateTime)

Maps the given LocalDateTime to the corresponding ZonedDateTime in a lenient manner: ambiguous values map to the earlier of the alternatives, and "skipped" values are shifted forward by the duration of the "gap".
Since 1.0.x
Availability net45, netstandard1.3, netstandard2.0
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 earlier result if the mapping is ambiguous, or the forward-shifted value 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.

Note: The behavior of this method was changed in version 2.0 to fit the most commonly seen real-world usage pattern. Previous versions returned the later instance of ambiguous values, and returned the start of the zone interval after the gap for skipped value. The previous functionality can still be used if desired, by using ResolveLocal(LocalDateTime, ZoneLocalMappingResolver), passing in a resolver created from ReturnLater and ReturnStartOfIntervalAfter.

AtStartOfDay(LocalDate)

Returns the earliest valid ZonedDateTime with the given local date.
Since 1.0.x
Availability net45, netstandard1.3, netstandard2.0
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 net45, netstandard1.3, netstandard2.0
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.
Sample snippet
using NodaTime;
using System;

DateTimeZone dublin = DateTimeZoneProviders.Tzdb["Europe/Dublin"];
ZonedDateTime dt = dublin.AtStrictly(new LocalDateTime(2010, 6, 9, 15, 15, 0));

Console.WriteLine(dt.Hour);
Console.WriteLine(dt.Year);

Instant instant = Instant.FromUtc(2010, 6, 9, 14, 15, 0);
Console.WriteLine(dt.ToInstant());

Output:

15
2010
2010-06-09T14:15:00Z
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.

ForOffset(Offset)

Returns a fixed time zone with the given offset.
Since 1.0.x
Availability net45, netstandard1.3, netstandard2.0
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. (The value returned is never null.)
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.

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 net45, netstandard1.3, netstandard2.0
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.
Sample snippet
using NodaTime;
using System;

// Yes, in 1900 Paris did (according to TZDB) have a UTC offset of 9 minutes, 21 seconds.
DateTimeZone paris = DateTimeZoneProviders.Tzdb["Europe/Paris"];
Offset offset = paris.GetUtcOffset(Instant.FromUtc(1900, 1, 1, 0, 0));
Console.WriteLine(offset.ToString());

Output:

+00:09:21

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 net45, netstandard1.3, netstandard2.0
Declaration
public abstract ZoneInterval GetZoneInterval(Instant instant)
Parameters
Type Name Description
Instant instant The Instant to query.
Returns
Type Description
ZoneInterval The defined ZoneInterval. (The value returned is never null.)
Remarks
This will always return a valid zone interval, as time zones cover the whole of time.
Sample snippet
using NodaTime;
using NodaTime.TimeZones;
using System;

DateTimeZone london = DateTimeZoneProviders.Tzdb["Europe/London"];
ZoneInterval interval = london.GetZoneInterval(Instant.FromUtc(2010, 6, 19, 0, 0));
Console.WriteLine(interval.Name);
Console.WriteLine(interval.Start);
Console.WriteLine(interval.End);
Console.WriteLine(interval.WallOffset);
Console.WriteLine(interval.Savings);

Output:

BST
2010-03-28T01:00:00Z
2010-10-31T01:00:00Z
+01
+01
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 net45, netstandard1.3, netstandard2.0
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. (The value returned is never null.)
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 net45, netstandard1.3, netstandard2.0
Declaration
public IEnumerable<ZoneInterval> GetZoneIntervals(Interval interval)
Parameters
Type Name Description
Interval interval Interval to find zone intervals for. This is allowed to be unbounded (i.e. infinite in both directions).
Returns
Type Description
IEnumerable<ZoneInterval> A sequence of zone intervals covering the given interval. (The value returned is never null.)
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

GetZoneIntervals(Interval, ZoneEqualityComparer.Options)

Returns the zone intervals within the given interval, potentially coalescing some of the original intervals according to options.
Since 2.0.x
Availability net45, netstandard1.3, netstandard2.0
Declaration
public IEnumerable<ZoneInterval> GetZoneIntervals(Interval interval, ZoneEqualityComparer.Options options)
Parameters
Type Name Description
Interval interval Interval to find zone intervals for. This is allowed to be unbounded (i.e. infinite in both directions).
ZoneEqualityComparer.Options options
Returns
Type Description
IEnumerable<ZoneInterval> (The value returned is never null.)
Remarks

This is equivalent to GetZoneIntervals(Interval), but may coalesce some intervals. For example, if the OnlyMatchWallOffset is specified, and two consecutive zone intervals have the same offset but different names, a single zone interval will be returned instead of two separate ones. When zone intervals are coalesced, all aspects of the first zone interval are used except its end instant, which is taken from the second zone interval.

As the options are only used to determine which intervals to coalesce, the MatchStartAndEndTransitions option does not affect the intervals returned.

MapLocal(LocalDateTime)

Returns complete information about how the given LocalDateTime is mapped in this time zone.
Since 1.0.x
Availability net45, netstandard1.3, netstandard2.0
Declaration
public virtual 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. (The value returned is never null.)
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 net45, netstandard1.3, netstandard2.0
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 net45, netstandard1.3, netstandard2.0
Declaration
public override string ToString()
Returns
Type Description
String The ID of this time zone.
Overrides
System.Object.ToString()