Class DateTimeZone
Inherited Members
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)
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
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
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
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
Declaration
public static DateTimeZone Utc { get; }
Property Value
Type | Description |
---|---|
DateTimeZone | A UTC DateTimeZone. (The value returned is never null.) |
Remarks
DateTimeZoneProviders.Tzdb["UTC"]
.
Methods
AtLeniently(LocalDateTime)
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
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 NodaTime.DateTimeZone.ResolveLocal(NodaTime.LocalDateTime,NodaTime.TimeZones.AmbiguousTimeResolver,NodaTime.TimeZones.SkippedTimeResolver) and passing the ReturnLater and ReturnStartOfIntervalAfter resolvers.
AtStartOfDay(LocalDate)
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
Exceptions
Type | Condition |
---|---|
SkippedTimeException | The entire day was skipped due to a very large time zone transition. (This is extremely rare.) |
AtStrictly(LocalDateTime)
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
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)
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)
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
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)
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
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)
start
, end
).
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)
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)
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)
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)
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()
Declaration
public override string ToString()
Returns
Type | Description |
---|---|
String | The ID of this time zone. |
Overrides
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).