Calculate UTC offsets
Each time zone carries its full history from the TZ Database: the offsets from universal time it has observed, and the daylight saving rules that change them. The extension methods on TzDataExtensions use that history to tell you the offset in effect at any instant, whether daylight saving time applies, when the offset changes, and the abbreviation by which the local time is known.
The examples on this page use the following namespace:
using DataStandardizer.Chronology;
Pass instants in universal time
Every method takes the instant as a DateTime in universal time or as a DateTimeOffset:
- A
DateTimeof kindUtcis used as it is. - A
DateTimeof kindUnspecifiedis treated as universal time, so make sure that it is one. - A
DateTimeof kindLocalthrowsArgumentException. Convert it withToUniversalTime()first, or pass aDateTimeOffset. - A
DateTimeOffsetis converted to universal time through itsUtcDateTime.
These methods answer questions about an instant. To go the other way, from a local wall clock time in the time zone to an instant, see Convert a local time to an instant.
Get the offset at an instant
GetUtcOffset returns the total offset from universal time, including any daylight saving:
var newYork = TzDataTimezone.America.New_York;
var instant = new DateTime(2026, 7, 1, 12, 0, 0, DateTimeKind.Utc);
TimeSpan offset = newYork.GetUtcOffset(instant); // -04:00:00
Apply the offset to get the local time as a DateTimeOffset:
var local = new DateTimeOffset(instant).ToOffset(offset); // 2026-07-01 08:00:00 -04:00
ToOffset also takes the time zone itself, and looks up the offset for you:
var local = new DateTimeOffset(instant).ToOffset(newYork); // 2026-07-01 08:00:00 -04:00
The offset is split into the standard offset and the daylight saving added to it:
TimeSpan standard = newYork.GetStandardOffset(instant); // -05:00:00
TimeSpan savings = newYork.GetDaylightSavings(instant); // 01:00:00
Historical offsets are kept to the second. Before New York adopted standard time in 1883 it kept local mean time:
var earlier = new DateTime(1880, 1, 1, 0, 0, 0, DateTimeKind.Utc);
TimeSpan lmt = newYork.GetUtcOffset(earlier); // -04:56:02
Find out whether daylight saving time applies
bool isDaylight = newYork.IsDaylightSavingTime(instant); // true
The TZ Database decides which time is daylight saving time, and it is not always the summer time. Europe/Dublin observes Irish Standard Time (IST, +01:00) in summer and saves a negative hour in winter, so its winter time is daylight saving time:
var dublin = TzDataTimezone.Europe.Dublin;
var january = new DateTime(2026, 1, 15, 12, 0, 0, DateTimeKind.Utc);
var july = new DateTime(2026, 7, 15, 12, 0, 0, DateTimeKind.Utc);
dublin.IsDaylightSavingTime(january); // true
dublin.GetDaylightSavings(january); // -01:00:00
dublin.IsDaylightSavingTime(july); // false
dublin.GetUtcOffset(july); // 01:00:00
Check IsDaylightSavingTime rather than comparing the daylight saving amount with zero.
Get everything at once
GetOffsetInfo returns a TzDataOffsetInfo with the offset, its parts, the abbreviation, and the period over which they stay in effect:
TzDataOffsetInfo info = newYork.GetOffsetInfo(instant);
Console.WriteLine(info.UtcOffset); // -04:00:00
Console.WriteLine(info.StandardOffset); // -05:00:00
Console.WriteLine(info.DaylightSavings); // 01:00:00
Console.WriteLine(info.IsDaylightSavingTime); // True
Console.WriteLine(info.Abbreviation); // EDT
Console.WriteLine($"{info.ValidFromUtc:u}"); // 2026-03-08 07:00:00Z
Console.WriteLine($"{info.ValidUntilUtc:u}"); // 2026-11-01 06:00:00Z
ValidFromUtc is null where the offset has applied since the beginning of the zone’s history, and ValidUntilUtc is null where it applies indefinitely, as for a zone that no longer changes its clocks.
List the transitions over a period
GetTransitions returns each TzDataTransition from the start of a period, inclusive, to its end, exclusive, in chronological order. Each one gives the instant of the change and the offsets before and after it:
var from = new DateTime(2026, 1, 1, 0, 0, 0, DateTimeKind.Utc);
var to = new DateTime(2027, 1, 1, 0, 0, 0, DateTimeKind.Utc);
foreach (var transition in newYork.GetTransitions(from, to))
{
Console.WriteLine($"{transition.InstantUtc:u} {transition.Before.Abbreviation} -> {transition.After.Abbreviation}");
}
Output:
2026-03-08 07:00:00Z EST -> EDT
2026-11-01 06:00:00Z EDT -> EST
A transition is reported wherever the offset, the standard offset, daylight saving time or the abbreviation changes. The instant of a transition takes the new offset, and the instant before it the old one.
Rules that the TZ Database gives as continuing indefinitely are applied to any future year, so there is no fixed upper limit:
var london = TzDataTimezone.Europe.London;
var transitions = london.GetTransitions(
new DateTime(2100, 1, 1, 0, 0, 0, DateTimeKind.Utc),
new DateTime(2101, 1, 1, 0, 0, 0, DateTimeKind.Utc));
// 2100-03-28 01:00:00Z GMT -> BST
// 2100-10-31 01:00:00Z BST -> GMT
Future transitions are predictions. They change when a government changes its rules and the TZ Database, and then this package, are updated.
Format abbreviations
GetAbbreviation returns the abbreviation in effect at an instant. It is the same as TzDataOffsetInfo.Abbreviation:
newYork.GetAbbreviation(instant); // EDT
GetStandardAbbreviation and GetDaylightAbbreviation return the abbreviations for standard and daylight saving time in the zone line and year in effect at the instant, whichever of the two is in effect at that instant:
newYork.GetStandardAbbreviation(instant); // EST
newYork.GetDaylightAbbreviation(instant); // EDT
london.GetStandardAbbreviation(july); // GMT
london.GetDaylightAbbreviation(july); // BST
dublin.GetStandardAbbreviation(july); // IST
dublin.GetDaylightAbbreviation(july); // GMT
GetDaylightAbbreviation returns null where no daylight saving time is observed in the year:
var tokyo = TzDataTimezone.Asia.Tokyo;
tokyo.GetStandardAbbreviation(instant); // JST
tokyo.GetDaylightAbbreviation(instant); // null
These are the TZ Database’s own abbreviations. Many zones have no abbreviation in common use, and the TZ Database gives their offset as a number instead:
TzDataTimezone.Asia.Dubai.GetAbbreviation(instant); // +04
TzDataTimezone.Asia.Kathmandu.GetAbbreviation(instant); // +0545
TzDataTimezone.Asia.Kolkata.GetAbbreviation(instant); // IST
Abbreviations aren’t unique: IST is used in both India and Ireland. Don’t use them to identify a time zone.
Historical abbreviations are kept as well. New York observed War Time from 1942 to 1945:
newYork.GetAbbreviation(new DateTime(1943, 1, 1, 0, 0, 0, DateTimeKind.Utc)); // EWT
Look at the underlying zone lines
The calculations are based on the zone’s zone lines, which you can read directly. GetZoneLine returns the TzDataZoneLine in effect at an instant, and ZoneLines returns all of them:
TzDataZoneLine line = newYork.GetZoneLine(instant);
Console.WriteLine(line.StandardOffset); // -05:00:00
Console.WriteLine(line.RuleKind); // RuleSet
Console.WriteLine(line.Format); // E%sT
Console.WriteLine(line.Until is null); // True, as the line applies indefinitely
Console.WriteLine(newYork.ZoneLines.Count); // 6
The TzDataRule instances in Rules give the daylight saving rules. GetTransitionDate returns the local date of a rule’s transition in a given year. This example also needs using System.Linq;:
foreach (var rule in line.Rules.Where(r => r.ToYear == int.MaxValue))
{
Console.WriteLine($"{rule.GetTransitionDate(2026):yyyy-MM-dd} {rule.AtTime} save {rule.Save}");
}
Output:
2026-03-08 02:00:00 save 01:00:00
2026-11-01 02:00:00 save 00:00:00
Most callers don’t need the zone lines. Use the methods above for offsets and abbreviations.
Convert a local time to an instant
A local wall clock time, such as the start time of a meeting in a calendar, usually occurs at exactly one instant. Around a transition it may not:
- A gap. When the clocks go forward, the local times they skip never occur. In New York, 2:30 AM on 8 March 2026 doesn’t exist.
- An overlap. When the clocks go back, the local times they repeat occur twice. In New York, 1:30 AM on 1 November 2026 occurs first in EDT and then in EST.
Pass the local time as a DateTime of kind Unspecified. A DateTime of kind Utc or Local throws ArgumentException.
GetOffsetInfosForLocal returns every offset in effect at a local time, in chronological order: none in a gap, one normally, and two in an overlap:
var newYork = TzDataTimezone.America.New_York;
newYork.GetOffsetInfosForLocal(new DateTime(2026, 7, 1, 12, 0, 0)); // EDT
newYork.GetOffsetInfosForLocal(new DateTime(2026, 3, 8, 2, 30, 0)); // (none)
newYork.GetOffsetInfosForLocal(new DateTime(2026, 11, 1, 1, 30, 0)); // EDT, EST
ToDateTimeOffset places a local time in a time zone. It returns a DateTimeOffset that keeps the local time with the offset in effect, and its UtcDateTime gives the instant. A TzDataLocalTimeResolution decides what happens in a gap or an overlap:
Rfc5545follows RFC 5545, section 3.3.5, as calendar data requires. A time in a gap takes the offset in effect before the gap, which moves it forward by the length of the gap. A time in an overlap takes its first occurrence.StrictthrowsArgumentExceptionin either case.
var meeting = new DateTime(2026, 3, 8, 2, 30, 0);
var start = meeting.ToDateTimeOffset(newYork, TzDataLocalTimeResolution.Rfc5545);
// 2026-03-08 03:30:00 -04:00, which is 07:30 UTC
var repeated = new DateTime(2026, 11, 1, 1, 30, 0)
.ToDateTimeOffset(newYork, TzDataLocalTimeResolution.Rfc5545);
// 2026-11-01 01:30:00 -04:00 (EDT), the first occurrence
DateTimeOffset holds offsets only in whole minutes of at most 14 hours. ToDateTimeOffset and ToOffset throw ArgumentOutOfRangeException for an offset it can’t hold, such as New York’s local mean time of -04:56:02 before 1883.
Limitations
- History before 1970. The TZ Database records the history of each zone’s principal location, the place it is named after, and guarantees it only from
- Before then, other places in the same zone may have kept different time. A link, such as
Europe/Oslo, has the history of its canonical time zone,Europe/Berlin. See Work with links and deprecated names.
- Before then, other places in the same zone may have kept different time. A link, such as
- Abbreviations. Only the TZ Database’s abbreviations are available, and many of them are numeric, such as
+04. Long names such as “Eastern Standard Time”, and localized names, come from the Unicode CLDR and are out of scope. - Leap seconds. Leap seconds are ignored, as they are by
DateTime. - Universal time.
DateTimearguments must be in universal time, except for the local times passed toGetOffsetInfosForLocalandToDateTimeOffset. See Pass instants in universal time. - Default instance.
default(TzDataTimezone)isEtc/UTC, so the methods return an offset of 0, no daylight saving time, the abbreviationUTCand no transitions for it. Get other time zones from the predefined fields, withParseorTryParse, or by explicit cast from an identifier.