GeoTime 1.0.0
dotnet add package GeoTime --version 1.0.0
NuGet\Install-Package GeoTime -Version 1.0.0
<PackageReference Include="GeoTime" Version="1.0.0" />
paket add GeoTime --version 1.0.0
#r "nuget: GeoTime, 1.0.0"
// Install GeoTime as a Cake Addin #addin nuget:?package=GeoTime&version=1.0.0 // Install GeoTime as a Cake Tool #tool nuget:?package=GeoTime&version=1.0.0
GeoTime
GeoTime aims to be a fast, lightweight, and memory-efficient C# library for querying timezone abbreviations.
Overview
Demo
Install
Package Manager Console:
PM> Install-Package GeoTime -Version 1.0.0
Nuget:
nuget install GeoTime -Version 1.0.0
.NET CLI:
dotnet add package GeoTime --version 1.0.0
System requirements
- .NET version: 5.x (C# language version: 9.0)
Architecture
- TZAbbr: An entity representing an abbreviated timezone, which holds: a unique ID, an abbreviation, a name, and an offset (in seconds).
- TZAbbrLookup: A high-level service that allows looking up information about abbreviated timezones
- TZAbbrLookupFactory: A factory for creating instances of a TZAbbrLookup service
- TZAbbrStore: A low-level service that holds a read-only dictionary, mapping unique primary keys/IDs to abbreviated timezone (
IReadOnlyDictionary<int, TZAbbr>
) - TZAmbiguityStore: A low level indexed service that holds a read-only dictionary, mapping timezone abbreviations to a set of timezone IDs (
IReadOnlyDictionary<string, HashSet<int>>
) - TZAScraper: A service that cleans and indexes the
timezones.json
into smaller and more usable data.
The concept of ambiguity
We say a timezone abbreviation is ambiguous, if it can possibly stand for multiple different timezones. For example, BST can mean:
- Bangladesh Standard Time (UTC -06)
- Bougainville Standard Time (UTC +11)
- British Summer Time (UTC +01)
Building the timezone data
The original timezone data is auto-extracted from an HTML table using a JS snippet, and then placed into data/timezones.json
.
To build the data and make it usable, you can run the GeoTime.Build
project, which will produce two files in the /artifacts
folder:
- List file - timezones.list.json: Holds a map which maps a unique primary key/ID to an abbreviated timezone.
- Ambiguity file - timezones.ambiguity.json: Holds a map which maps the timezone abbreviations (string keys) to the unique ID of a timezone it can stand for (array of integers).
Notes: The following issues are being worked on.
- The artifacts are not automatically placed into the
artifacts
folder, and will have to be manually moved fromsrc/GeoTime.Build/bin/Release/net5.0
toartifacts
.
Memory and performance
- The datasets combined (already minified), totals to 20 KB.
- Compressing into a ZIP will drop it to a total 6.17KB (3.24x smaller).
- gzipping both files will drop it to a total 5.2KB (3.85x smaller).
Constructing the lookup service will take the most time, as this requires indexing all the timezone data by deserializing two JSON files into C# read-only dictionaries. After creating a lookup, querying for info will generally run under much quicker times.
Usage
TZAbbrLookup lookup = new TZAbbrLookupFactory().GetLookup();
Check if an abbreviation is ambiguous
Checking if an abbreviation is ambiguous takes constant time (O(1) time).
lookup.IsAbbrAmbiguous( "CST" ); // true
lookup.IsAbbrAmbiguous( "ART" ); // false
Get an abbreviated timezone by ID or name
Querying an abbreviated timezone by their...
- ...unique integer ID takes O(1) time.
- ...unique full name will take linear time (O(n) time), where
n
represents the number of timezone abbreviations.
TZAbbr novosibirsk = lookup.GetTimeZone( 149 );
// new TZAbbr( 149, "NOVST", "Novosibirsk Summer Time", 25200 )
TZAbbr argentina = lookup.GetTimeZone( "Argentina Time" );
// new TZAbbr( 22, "ART", "Argentina Time", -10800 )
Console.WriteLine( argentina.Abbr ); // "ART"
Console.WriteLine( argentina.OffsetInSeconds ); // -10800
Console.WriteLine( argentina.GetOffset().ToString() ); // "-03"
TZAbbr someTZ = lookup.GetTimeZone( "Foo" );
// throws TimeZoneNotFoundException
Get possible timezones from an abbreviation
Querying a list of timezones by abbreviation will take O(1+n) time, where n represents the number of timezones an abbreviation can possibly stand for. The first operation will be a dictionary lookup, and the n operations after will be dictionary lookups of the timezones by ID.
- In average case and best case: O(2) (An abbreviation maps to 1 timezone)
- In worst case: O(4) (An abbreviation maps to 3 timezones)
lookup.GetTimeZonesByAbbr( "CST" );
/**
new HashSet<TZAbbr>() {
new TZAbbr( 61, "CST", "Central Standard Time", -21600 ),
new TZAbbr( 62, "CST", "China Standard Time", 28800 ),
new TZAbbr( 63, "CST", "Cuba Standard Time", -18000 )
}
**/
lookup.GetTimeZonesByAbbr( "PGT" );
/**
new HashSet<TZAbbr>() {
new TZAbbr( 166, "PGT", "Papua New Guinea Time", 36000 )
}
**/
License
GeoTime is licensed under the MIT license.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net5.0 is compatible. net5.0-windows was computed. net6.0 was computed. 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-browser 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. |
-
net5.0
- Newtonsoft.Json (>= 12.0.3)
- NodaTime (>= 3.0.5)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
Version | Downloads | Last updated |
---|---|---|
1.0.0 | 437 | 2/28/2021 |