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
DateTimeargument is an instant in universal time. ADateTimeof kindUnspecifiedis treated as universal time, and one of kindLocalthrowsArgumentException. - A
DateTimeOffsetargument is converted to universal time through itsUtcDateTime. GetOffsetInfosForLocalis the exception: itsDateTimeargument is a time on the local clock of the time zone, and must be of kindUnspecified. One of kindUtcorLocalthrowsArgumentException.default(TzDataTimezone)isEtc/UTC: an offset of 0, no daylight saving time, the abbreviationUTCand 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:
%sis replaced by theLETTERof the latest standard time rule, or the latest daylight saving time rule, in effect in the year on the local clock.- A
FORMATof the formA/B, such asGMT/BST, givesAfor standard time andBfor daylight saving time. %zgives the standard offset, or the offset with daylight saving, as+hh,+hhmmor+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.