DareDevels.TZConvertFast 6.2.0

.NET 6.0 .NET Standard 2.0 .NET Framework 4.6.2
dotnet add package DareDevels.TZConvertFast --version 6.2.0
NuGet\Install-Package DareDevels.TZConvertFast -Version 6.2.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="DareDevels.TZConvertFast" Version="6.2.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add DareDevels.TZConvertFast --version 6.2.0
#r "nuget: DareDevels.TZConvertFast, 6.2.0"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install DareDevels.TZConvertFast as a Cake Addin
#addin nuget:?package=DareDevels.TZConvertFast&version=6.2.0

// Install DareDevels.TZConvertFast as a Cake Tool
#tool nuget:?package=DareDevels.TZConvertFast&version=6.2.0

TZConvertFast NuGet Version


TZConvertFast is a lightweight library to convert quickly between IANA, Windows, and Rails time zone names. It's based off TimeZoneConverter, but tries to address some performance issues.

Note: A separate TimeZoneConverter.Posix package is also available if you need POSIX time zone support.

Installation

  • Add the TZConvertFast NuGet package to your project.
  • Import the TZConvertFast namespace where needed.

Compatibility

As of version 6.0.0, TZConvertFast works with all of the following:

  • .NET 5 or greater
  • .NET Core 2.0 or greater
  • .NET Framework 4.6.2 and greater

.NET Framework versions less than 4.6.2 are no longer supported.

Important note on .NET 6+

.NET 6 has built-in support for IANA and Windows time zones in a cross-platform manner, somewhat reducing the need for this library. It relies on .NET's ICU integration to perform this functionality. See the .NET blog for details.

Restated, if you are targeting only .NET 6 (or higher), and you have either platform-provided or App-local ICU enabled, you might not need to use this library. However, it is indeed still supported, and many have found it continues to be useful in certain environments or on specific platforms.

TimeZoneConverter has no external data dependencies at runtime. All of the data it needs is embedded in the library itself.

Note on OS Data Dependencies

Some functions in TimeZoneConverter, such as TZConvert.GetTimeZoneInfo rely on the underlying TimeZoneInfo object having access to time zone data of the operating system. On Windows, this data comes from the registry and is maintained via Windows Updates.

On OSX and Linux, this data comes from a distribution of the IANA time zone database, usually via the tzdata package. If your environment does not have the tzdata package installed, you will need to install it for TZConvert.GetTimeZoneInfo to work correctly.

For example, the Alpine Linux Docker images for .NET Core no longer ship with tzdata. See dotnet/dotnet-docker#1366 for instructions on how to add it to your Docker images.

Notes

This library uses a combination of data sources to achieve its goals:

Usually, the latter is reserved for edge cases, and for newly-introduced zones that may or may not have been published to official sources yet.

Important: Since this data can change whenever new time zones are introduced from any of these sources, it is recommended that you always use the most current revision, and check for updates regularly.

Additionally, this library does not attempt to determine if the time zone IDs provided are actually present on the computer where the code is running. It is assumed that the computer is kept current with time zone updates.

For example, if one attempts to convert Africa/Khartoum to a Windows time zone ID, they will get Sudan Standard Time. If it is then used on a Windows computer that does not yet have KB4051956 installed (which created this time zone), they will likely get a TimeZoneNotFoundException.

Unmappable Zones

It is possible for a zone to be unmappable - meaning that there is no logical equivalent from one type of time zone to another.

Currently there is only one IANA zone that is unmappable to Windows, which is Antarctica/Troll. In other words, there is no "correct" time zone for Windows users who may happen to be stationed in Troll Station, Antarctica. Therefore, if you try to convert Antarctica/Troll to Windows, you will get a TimeZoneNotFoundException.

There are many zones that are unmappable to Rails. The complete list is in the unit test code here.

Example Usage

Convert an IANA time zone name to the best fitting Windows time zone ID.

string tz = TZConvert.IanaToWindows("America/New_York");
// Result:  "Eastern Standard Time"

Convert a Windows time zone name to the best fitting IANA time zone name.

string tz = TZConvert.WindowsToIana("Eastern Standard Time");
// result:  "America/New_York"

Convert a Windows time zone name to the best fitting IANA time zone name, with regard to a specific country.

string tz = TZConvert.WindowsToIana("Eastern Standard Time", "CA");
// result:  "America/Toronto"

Get a TimeZoneInfo object from .NET Core, regardless of what OS you are running on:

// Either of these will work on any platform:
TimeZoneInfo tzi = TZConvert.GetTimeZoneInfo("Eastern Standard Time");
TimeZoneInfo tzi = TZConvert.GetTimeZoneInfo("America/New_York");

Convert a Rails time zone name to the best fitting IANA time zone name.

string tz = TZConvert.RailsToIana("Mexico City");
// result:  "America/Mexico_City"

Convert a Rails time zone name to the best fitting Windows time zone ID.

string tz = TZConvert.RailsToWindows("Mexico City");
// result:  "Central Standard Time (Mexico)"

Convert an IANA time zone name to one or more Rails time zone names.

IList<string> tz = TZConvert.IanaToRails("America/Mexico_City");
// Result:  { "Guadalajara", "Mexico City" }

Convert a Windows time zone ID to one or more Rails time zone names.

IList<string> tz = TZConvert.WindowsToRails("Central Standard Time (Mexico)");
// Result:  { "Guadalajara", "Mexico City" }

Extras

There are a few additional helpers you may find useful.

  • These properties provide lists of the various types of time zones known to this library:

    • TZConvert.KnownIanaTimeZoneNames
    • TZConvert.KnownWindowsTimeZoneIds
    • TZConvert.KnownRailsTimeZoneNames
  • If you need a list of time zones that are applicable in a given region, you can use:

    • TZConvert.GetIanaTimeZoneNamesByTerritory()

License

This library is provided free of charge, under the terms of the MIT license.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 is compatible.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Additional computed target framework(s)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories (1)

Showing the top 1 popular GitHub repositories that depend on DareDevels.TZConvertFast:

Repository Stars
christosk92/Wavee
Version Downloads Last updated
6.2.0 2,726 5/2/2023