TzDataExtensions Class

Definition

Namespace: DataStandardizer.Chronology

Extension methods on TzDataTimezone that calculate the offset from universal time, daylight saving time, transitions and abbreviations of a time zone at an instant, from its zone lines.

public static class TzDataExtensions

Remarks

Offsets, transitions and abbreviations

Each calculation method has an overload that takes a DateTime and one that takes a DateTimeOffset.

  • A DateTime argument is an instant in universal time. A DateTime of kind Unspecified is treated as universal time, and one of kind Local throws ArgumentException.
  • A DateTimeOffset argument is converted to universal time through its UtcDateTime.
  • GetOffsetInfosForLocal is the exception: its DateTime argument is a time on the local clock of the time zone, and must be of kind Unspecified. One of kind Utc or Local throws ArgumentException.
  • default(TzDataTimezone) is Etc/UTC: an offset of 0, no daylight saving time, the abbreviation UTC and no transitions.

The calculations follow the TZ Database’s reference compiler, zic. Rules that continue indefinitely are applied to any future year. Leap seconds are ignored. Data before 1970 is guaranteed only for the zone’s principal location. See Calculate UTC offsets.

The TZ Database decides which time is daylight saving time and which is standard time. Europe/Dublin saves a negative hour in winter, so its winter time (GMT) is daylight saving time, and its summer time (IST) is standard time.

Abbreviations are the TZ Database’s own, formatted from the FORMAT of the zone line in effect as zic formats them. Many are numeric, such as +04. Long and localized names such as “Eastern Standard Time” come from the Unicode CLDR and are not available.

Methods

Extension

Every calculation method below, except GetOffsetInfosForLocal, also has an overload that takes a DateTimeOffset in place of each DateTime, for example GetUtcOffset(DateTimeOffset instant).

Method Extends Returns Notes
GetAbbreviation(DateTime utc) TzDataTimezone string The abbreviation in effect at the instant, for example EST, BST or +0545. The same as TzDataOffsetInfo.Abbreviation.
GetDaylightAbbreviation(DateTime utc) TzDataTimezone string? The daylight saving time abbreviation for the zone line and year in effect at the instant, for example EDT or BST, or null if no daylight saving time is observed in the year. Returns string ([CanBeNull]) on the .NET Standard targets.
GetDaylightSavings(DateTime utc) TzDataTimezone TimeSpan The amount added to the standard offset at the instant. May be negative, as for Europe/Dublin in winter.
GetOffsetInfo(DateTime utc) TzDataTimezone TzDataOffsetInfo The offset, its parts and abbreviation at the instant, with the period over which they are in effect.
GetOffsetInfosForLocal(DateTime local) TzDataTimezone IReadOnlyList<TzDataOffsetInfo> The reverse of GetOffsetInfo: every offset in effect at a time on the local clock, in chronological order. Returns none where the time falls in a gap, one normally, and two where it falls in an overlap. An offset whose instant would fall outside the range of DateTime is left out, so near either end of that range an empty result can mean that rather than a gap; ToDateTimeOffset tells the two apart. local must be of kind Unspecified. To place a local time with a policy for gaps and overlaps, use DateTimeExtensions.ToDateTimeOffset.
GetStandardAbbreviation(DateTime utc) TzDataTimezone string The standard time abbreviation for the zone line and year in effect at the instant, for example EST or GMT.
GetStandardOffset(DateTime utc) TzDataTimezone TimeSpan The offset of standard time from universal time at the instant, excluding daylight saving.
GetTransitions(DateTime fromUtc, DateTime toUtc) TzDataTimezone IEnumerable<TzDataTransition> The changes of offset from fromUtc, inclusive, to toUtc, exclusive, in chronological order. A transition is reported where the offset, the standard offset, daylight saving time or the abbreviation changes. Throws ArgumentOutOfRangeException if toUtc precedes fromUtc. The arguments are checked when the method is called, not when the result is enumerated.
GetUtcOffset(DateTime utc) TzDataTimezone TimeSpan The total offset from universal time at the instant, including daylight saving.
GetZoneLine(DateTime utc) TzDataTimezone TzDataZoneLine The zone line in effect at the instant.
IsDaylightSavingTime(DateTime utc) TzDataTimezone bool true if daylight saving time is in effect at the instant; otherwise, false.

Standard and daylight abbreviations

GetStandardAbbreviation and GetDaylightAbbreviation format the FORMAT of the zone line in effect at the instant:

  • %s is replaced by the LETTER of the latest standard time rule, or the latest daylight saving time rule, in effect in the year on the local clock.
  • A FORMAT of the form A/B, such as GMT/BST, gives A for standard time and B for daylight saving time.
  • %z gives the standard offset, or the offset with daylight saving, as +hh, +hhmm or +hhmmss, using the shortest form that gives the offset exactly.
  • A zone line that saves a fixed amount observes daylight saving time where the amount is not zero.

Applies to

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

See also


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