Early Preview
This is currently very much a preview. Please feel free to try things out,
but don't be upset if anything is not yet working. Feedback is welcome over on our
GitHub Dicussions page.
class NodaTime.TimeZones.BclDateTimeZone
Assembly: NodaTime
Inheritance: object → DateTimeZone → BclDateTimeZone
Implemented Interfaces
- IZoneIntervalMap Implemented by: DateTimeZone
Representation of a time zone converted from a <see cref="T:System.TimeZoneInfo" /> from the Base Class Library.
Remarks
<para>
Two instances of this class are deemed equal if and only if they refer to the exact same
<see cref="T:System.TimeZoneInfo" /> object.
</para> <para>
This implementation does not always give the same results as <c>TimeZoneInfo</c>, in that it doesn't replicate
the bugs in the BCL interpretation of the data. These bugs are described in
<a href="https://codeblog.jonskeet.uk/2014/09/30/the-mysteries-of-bcl-time-zone-data/">a blog post</a>, but we're
not expecting them to be fixed any time soon. Being bug-for-bug compatible would not only be tricky, but would be painful
if the BCL were ever to be fixed. As far as we are aware, there are only discrepancies around new year where the zone
changes from observing one rule to observing another.
</para> <para>
As of version 3.0, a new "incompatible but doing the right thing" category of differences has been implemented,
for time zones which have a transition at 24:00. The Windows time zone data represents this as a transition at 23:59:59.999,
and that's faithfully represented by TimeZoneInfo (and BclDateTimeZone in version 2.x). As of 3.0, this is spotted
and converted to a midnight-on-the-following-day transition.
</para>
Properties
public
System.TimeZoneInfo
OriginalZone
Gets the original <see cref="T:System.TimeZoneInfo" /> from which this was created.
public
string
DisplayName
Gets the display name associated with the time zone, as provided by the Base Class Library.
public
string
Id
Get the provider's ID for the time zone.
Remarks <para>
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.
</para>
public
Offset
MinOffset
Gets the least (most negative) offset within this time zone, over all time.
public
Offset
MaxOffset
Gets the greatest (most positive) offset within this time zone, over all time.
Methods
public
ZoneInterval
GetZoneInterval(Instant 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).
Returns The defined <see cref="T:NodaTime.TimeZones.ZoneInterval" /> .
instant
The <see cref="T:NodaTime.Instant" /> to query.
Remarks
This will always return a valid zone interval, as time zones cover the whole of time.
public static
BclDateTimeZone
FromTimeZoneInfo(System.TimeZoneInfo bclZone)
Creates a new <see cref="T:NodaTime.TimeZones.BclDateTimeZone" /> from a <see cref="T:System.TimeZoneInfo" /> from the Base Class Library.
Returns A <see cref="T:NodaTime.TimeZones.BclDateTimeZone" /> wrapping the given <c>TimeZoneInfo</c> .
bclZone
The original time zone to take information from.
public static
BclDateTimeZone
ForSystemDefault()
Returns a time zone converted from the BCL representation of the system local time zone.
Returns A <see cref="T:NodaTime.TimeZones.BclDateTimeZone" /> wrapping the "local" (system) time zone as returned by
<see cref="P:System.TimeZoneInfo.Local" /> .
Remarks
<para>
This method is approximately equivalent to calling <see cref="M:NodaTime.IDateTimeZoneProvider.GetSystemDefault" /> with
an implementation that wraps <see cref="T:NodaTime.TimeZones.BclDateTimeZoneSource" /> (e.g.
<see cref="P:NodaTime.DateTimeZoneProviders.Bcl" />), with the exception that it will succeed even if the current local
time zone was not one of the set of system time zones captured when the source was created (which, while
highly unlikely, might occur either because the local time zone is not a system time zone, or because the
system time zones have themselves changed).
</para> <para>
This method will retain a reference to the returned <c>BclDateTimeZone</c>, and will attempt to return it if
called repeatedly (assuming that the local time zone has not changed) rather than creating a new instance,
though this behaviour is not guaranteed.
</para>
public
Offset
GetUtcOffset(Instant instant)
Inherited from DateTimeZone
Returns the offset from UTC, where a positive duration indicates that local time is
later than UTC. In other words, local time = UTC + offset.
Returns The offset from UTC at the specified instant.
instant
The instant for which to calculate the offset.
Remarks
This is mostly a convenience method for calling <c>GetZoneInterval(instant).WallOffset</c> ,
although it can also be overridden for more efficiency.
public
ZoneLocalMapping
MapLocal(LocalDateTime localDateTime)
Inherited from DateTimeZone
Returns complete information about how the given <see cref="T:NodaTime.LocalDateTime" /> is mapped in this time zone.
Returns A mapping of the given local date and time to zero, one or two zoned date/time values.
localDateTime
The local date and time to map in this time zone.
Remarks
<para>
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.
</para> <para>
As an alternative, consider <see cref="M:NodaTime.DateTimeZone.ResolveLocal(NodaTime.LocalDateTime,NodaTime.TimeZones.ZoneLocalMappingResolver)" />, which uses a caller-provided strategy to
convert the <see cref="T:NodaTime.TimeZones.ZoneLocalMapping" /> returned here to a <see cref="T:NodaTime.ZonedDateTime" />.
</para>
public
ZonedDateTime
AtStartOfDay(LocalDate date)
Inherited from DateTimeZone
Returns the earliest valid <see cref="T:NodaTime.ZonedDateTime" /> with the given local date.
Returns The <see cref="T:NodaTime.ZonedDateTime" /> representing the earliest time in the given date, in this time zone.
date
The local date to map 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.
public
ZonedDateTime
ResolveLocal(LocalDateTime localDateTime,
ZoneLocalMappingResolver resolver)
Inherited from DateTimeZone
Maps the given <see cref="T:NodaTime.LocalDateTime" /> to the corresponding <see cref="T:NodaTime.ZonedDateTime" /> , following
the given <see cref="T:NodaTime.TimeZones.ZoneLocalMappingResolver" /> to handle ambiguity and skipped times.
Returns The result of resolving the mapping.
localDateTime
The local date and time to map in this time zone.
resolver
The resolver to apply to the mapping.
Remarks
<para>
This is a convenience method for calling <see cref="M:NodaTime.DateTimeZone.MapLocal(NodaTime.LocalDateTime)" /> and passing the result to the resolver.
Common options for resolvers are provided in the static <see cref="T:NodaTime.TimeZones.Resolvers" /> class.
</para> <para>
See <see cref="M:NodaTime.DateTimeZone.AtStrictly(NodaTime.LocalDateTime)" /> and <see cref="M:NodaTime.DateTimeZone.AtLeniently(NodaTime.LocalDateTime)" /> for alternative ways to map a local time to a
specific instant.
</para>
public
ZonedDateTime
AtStrictly(LocalDateTime localDateTime)
Inherited from DateTimeZone
Maps the given <see cref="T:NodaTime.LocalDateTime" /> to the corresponding <see cref="T:NodaTime.ZonedDateTime" /> , if and only if
that mapping is unambiguous in this time zone. Otherwise, <see cref="T:NodaTime.SkippedTimeException" /> or
<see cref="T:NodaTime.AmbiguousTimeException" /> is thrown, depending on whether the mapping is ambiguous or the local
date/time is skipped entirely.
Returns The unambiguous matching <see cref="T:NodaTime.ZonedDateTime" /> if it exists.
localDateTime
The local date and time to map into this time zone.
Remarks
See <see cref="M:NodaTime.DateTimeZone.AtLeniently(NodaTime.LocalDateTime)" /> and <see cref="M:NodaTime.DateTimeZone.ResolveLocal(NodaTime.LocalDateTime,NodaTime.TimeZones.ZoneLocalMappingResolver)" /> for alternative ways to map a local time to a
specific instant.
public
ZonedDateTime
AtLeniently(LocalDateTime localDateTime)
Inherited from DateTimeZone
Maps the given <see cref="T:NodaTime.LocalDateTime" /> to the corresponding <see cref="T:NodaTime.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".
Returns 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.
localDateTime
The local date/time to map.
Remarks
See <see cref="M:NodaTime.DateTimeZone.AtStrictly(NodaTime.LocalDateTime)" /> and <see cref="M:NodaTime.DateTimeZone.ResolveLocal(NodaTime.LocalDateTime,NodaTime.TimeZones.ZoneLocalMappingResolver)" /> for alternative ways to map a local time to a
specific instant.
<para>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 <see cref="M:NodaTime.DateTimeZone.ResolveLocal(NodaTime.LocalDateTime,NodaTime.TimeZones.ZoneLocalMappingResolver)" />, passing in a resolver
created from <see cref="P:NodaTime.TimeZones.Resolvers.ReturnLater" /> and <see cref="P:NodaTime.TimeZones.Resolvers.ReturnStartOfIntervalAfter" />.</para>
Returns The ID of this time zone.
GetZoneIntervals(Instant start,
Instant end)
Inherited from DateTimeZone
Returns all the zone intervals which occur for any instant in the interval [ <paramref name="start" /> , <paramref name="end" /> ).
Returns A sequence of zone intervals covering the given interval.
start
Inclusive start point of the interval for which to retrieve zone intervals.
end
Exclusive end point of the interval for which to retrieve zone intervals.
Remarks
<para>This method is simply a convenience method for calling <see cref="M:NodaTime.DateTimeZone.GetZoneIntervals(NodaTime.Interval)" /> without
explicitly constructing the interval beforehand.
</para>
GetZoneIntervals(Interval interval)
Inherited from DateTimeZone
Returns all the zone intervals which occur for any instant in the given interval.
Returns A sequence of zone intervals covering the given interval.
interval
Interval to find zone intervals for. This is allowed to be unbounded (i.e.
infinite in both directions).
Remarks
<para>The zone intervals are returned in chronological order.
This method is equivalent to calling <see cref="M:NodaTime.DateTimeZone.GetZoneInterval(NodaTime.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.
</para>
public
bool
Equals(object obj)
Inherited from object
protected
void
Finalize()
Inherited from object
public
int
GetHashCode()
Inherited from object
protected
object
MemberwiseClone()
Inherited from object