IcalTimeZoneRules Class

Definition

Namespace: DataStandardizer.File.iCal

The rules of a time zone, as resolved by an IIcalTimeZoneResolver: the UTC offset in use at each instant, and how a local wall-clock time maps to UTC.

Syntax

public abstract class IcalTimeZoneRules

Remarks

You get rules from a resolver, through TryResolve or the IcalTimeZoneResolver.Resolve extension method. The resolvers of this package return internal derived types, described on the IcalTimeZoneResolver page. To supply your own rules, derive from this class and return it from your own resolver.

Deriving. A derived type supplies two things: the offset at an instant (GetUtcOffsetCore) and the transitions over a period (GetTransitionsCore). The OffsetTo of each transition must be what GetUtcOffsetCore gives from its instant until the next transition. The mapping of local time to UTC is built on those two. A derived type may override GetUtcOffsetsForLocalCore when it has a faster or more exact way.

Gaps and overlaps. ToUtc follows RFC 5545 §3.3.5. A time in a gap, as when clocks go forward, is read with the offset in use before the gap, which moves it forward by the length of the gap. A time in an overlap, as when clocks go back, takes its first occurrence, the earlier instant. For example, in Europe/London, 01:30 on the day clocks go forward becomes 01:30 UTC (02:30 BST), and 01:30 on the day clocks go back becomes 00:30 UTC (01:30 BST).

Kinds of DateTime. Times in UTC may be of kind DateTimeKind.Utc or DateTimeKind.Unspecified. Local wall-clock times must be of kind DateTimeKind.Unspecified. A time of kind DateTimeKind.Local, which belongs to the time zone of the machine, is rejected by both with ArgumentException.

Constructors

Constructor Notes
protected IcalTimeZoneRules(string timeZoneId) Creates the rules of a time zone. timeZoneId is the identifier, as given by a TZID parameter. Throws ArgumentNullException if timeZoneId is null, or ArgumentException if it is empty.

Properties

Property Signature Notes
TimeZoneId string TimeZoneId { get; } The time zone identifier the rules were resolved for. For a TZID with a vendor prefix, such as /mozilla.org/20050126_1/America/New_York, this is the identifier as given, prefix included.

Methods

Public

Method Returns Notes
GetTransitions(DateTime fromUtc, DateTime toUtc) IEnumerable<IcalTimeZoneTransition> The transitions between UTC offsets from fromUtc (included) to toUtc (excluded), in chronological order. The arguments are checked when the method is called. Throws ArgumentException if either is of kind DateTimeKind.Local, or ArgumentOutOfRangeException if toUtc precedes fromUtc.
GetUtcOffset(DateTime utc) IcalUtcOffset The UTC offset in use at an instant. Throws ArgumentException if utc is of kind DateTimeKind.Local.
GetUtcOffsetsForLocal(DateTime local) IReadOnlyList<IcalUtcOffset> Every UTC offset in use at a local wall-clock time, in chronological order of the instants at which the local clock shows it: none in a gap, one normally, and two in an overlap. Throws ArgumentException if local is of kind DateTimeKind.Utc or DateTimeKind.Local.
ToLocal(DateTime utc) DateTime Converts an instant to the local wall-clock time of the zone, of kind DateTimeKind.Unspecified. Throws ArgumentException if utc is of kind DateTimeKind.Local, or ArgumentOutOfRangeException if the local time falls outside the range of DateTime.
ToUtc(DateTime local) DateTime Converts a local wall-clock time to an instant of kind DateTimeKind.Utc, applying the RFC 5545 §3.3.5 gap and overlap rules. Throws ArgumentException if local is of kind DateTimeKind.Utc or DateTimeKind.Local, or ArgumentOutOfRangeException if the instant falls outside the range of DateTime. Throws InvalidOperationException if a derived type reports no offset for the time yet no gap around it, which means its offsets and transitions disagree.

Protected

Method Returns Notes
GetTransitionsCore(DateTime fromUtc, DateTime toUtc) IEnumerable<IcalTimeZoneTransition> Abstract. The transitions from fromUtc (included) to toUtc (excluded), in chronological order. Both are of kind DateTimeKind.Utc, and toUtc does not precede fromUtc.
GetUtcOffsetCore(DateTime utc) IcalUtcOffset Abstract. The offset in use at an instant of kind DateTimeKind.Utc.
GetUtcOffsetsForLocalCore(DateTime local) IReadOnlyList<IcalUtcOffset> Virtual. Every offset in use at a local time of kind DateTimeKind.Unspecified, in chronological order. The default takes the offset in use a day before the time and the transitions over the day either side of it, which covers every offset of less than a day. It keeps each offset whose instant, the time less the offset, falls while that offset is in use.

Applies to

Targets netstandard1.1, netstandard2.0, netstandard2.1, and net10.0.

See also


This site uses Just the Docs, a documentation theme for Jekyll.