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:

• AtStrictly(LocalDateTime) will throw an exception if the mapping from local time is either ambiguous or impossible, i.e. if there is anything other than one instant which maps to the given local time.
• AtLeniently(LocalDateTime) will never throw an exception due to ambiguous or skipped times, resolving to the earlier option of ambiguous matches, or to a value that's forward-shifted by the duration of the gap for skipped times.
• ResolveLocal(LocalDateTime, ZoneLocalMappingResolver) will apply a ZoneLocalMappingResolver to the result of a mapping.
• MapLocal(LocalDateTime) will return a ZoneLocalMapping with complete information about whether the given local time occurs zero times, once or twice. This is the most fine-grained approach, which is the fiddliest to use but puts the caller in the most control.

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 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 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

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:

• AtStrictly(LocalDateTime) will throw an exception if the mapping from local time is either ambiguous or impossible, i.e. if there is anything other than one instant which maps to the given local time.
• AtLeniently(LocalDateTime) will never throw an exception due to ambiguous or skipped times, resolving to the earlier option of ambiguous matches, or to a value that's forward-shifted by the duration of the gap for skipped times.
• ResolveLocal(LocalDateTime, ZoneLocalMappingResolver) will apply a ZoneLocalMappingResolver to the result of a mapping.
• MapLocal(LocalDateTime) will return a ZoneLocalMapping with complete information about whether the given local time occurs zero times, once or twice. This is the most fine-grained approach, which is the fiddliest to use but puts the caller in the most control.

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 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 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).

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.

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:

• AtStrictly(LocalDateTime) will throw an exception if the mapping from local time is either ambiguous or impossible, i.e. if there is anything other than one instant which maps to the given local time.
• AtLeniently(LocalDateTime) will never throw an exception due to ambiguous or skipped times, resolving to the earlier option of ambiguous matches, or to a value that's forward-shifted by the duration of the gap for skipped times.
• ResolveLocal(LocalDateTime, ZoneLocalMappingResolver) will apply a ZoneLocalMappingResolver to the result of a mapping.
• MapLocal(LocalDateTime) will return a ZoneLocalMapping with complete information about whether the given local time occurs zero times, once or twice. This is the most fine-grained approach, which is the fiddliest to use but puts the caller in the most control.

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 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 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).

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.

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:

• AtStrictly(LocalDateTime) will throw an exception if the mapping from local time is either ambiguous or impossible, i.e. if there is anything other than one instant which maps to the given local time.
• AtLeniently(LocalDateTime) will never throw an exception due to ambiguous or skipped times, resolving to the earlier option of ambiguous matches, or to a value that's forward-shifted by the duration of the gap for skipped times.
• ResolveLocal(LocalDateTime, ZoneLocalMappingResolver) will apply a ZoneLocalMappingResolver to the result of a mapping.
• MapLocal(LocalDateTime) will return a ZoneLocalMapping with complete information about whether the given local time occurs zero times, once or twice. This is the most fine-grained approach, which is the fiddliest to use but puts the caller in the most control.

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 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 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).

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(Interval)

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

GetZoneInterval(Instant)

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

GetZoneInterval(Instant)

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

Object.ToString()

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:

• AtStrictly(LocalDateTime) will throw an exception if the mapping from local time is either ambiguous or impossible, i.e. if there is anything other than one instant which maps to the given local time.
• AtLeniently(LocalDateTime) will never throw an exception due to ambiguous or skipped times, resolving to the earlier option of ambiguous matches, or to a value that's forward-shifted by the duration of the gap for skipped times.
• ResolveLocal(LocalDateTime, ZoneLocalMappingResolver) will apply a ZoneLocalMappingResolver to the result of a mapping.
• MapLocal(LocalDateTime) will return a ZoneLocalMapping with complete information about whether the given local time occurs zero times, once or twice. This is the most fine-grained approach, which is the fiddliest to use but puts the caller in the most control.

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 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 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).