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

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>

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 later option of ambiguous matches or the start of the zone interval after 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 "zoneinfo" (aka tz 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 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 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

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

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

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

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 DateTimeZoneProviders.Default["UTC"]; that depends on whether the default provider has its own mapping for that ID.

Since 1.0.x

Availability net35-Client

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

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

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

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

Declaration

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

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

Declaration

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

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

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

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.

Since 1.0.x

Availability net35-Client

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.

MapLocal(LocalDateTime)

Returns complete information about how the given LocalDateTime is mapped in this time zone.

Since 1.0.x

Availability net35-Client

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.

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

Declaration

public ZonedDateTime ResolveLocal(LocalDateTime localDateTime, ZoneLocalMappingResolver resolver)

Parameters

Type	Name	Description
LocalDateTime	localDateTime
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
System.ArgumentNullException	resolver is null

ToString()

Returns the ID of this time zone.

Since 1.0.x

Availability net35-Client

Declaration

public override string ToString()

Returns

Type	Description
String	The ID of this time zone.

Overrides

System.Object.ToString()

Implements

System.IEquatable<T>