feat: deprecate GetAbbreviationsForTimeZone (#133)

Author: mattjohnsonpint

README.md

@@ -9,6 +9,9 @@ Read [this blog post](https://codeofmatt.com/localized-time-zone-names-in-net/)
 Note that if you are running .NET 6+ on Linux or macOS, the built-in names now stem from ICU and thus this library is no longer needed.
 See [the .NET blog post](https://devblogs.microsoft.com/dotnet/date-time-and-time-zone-enhancements-in-net-6/#time-zone-display-names-on-linux-and-macos) for more details.
 
+**NOTE**:
+Methods for retrieving localized time zone abbreviations have been deprecated, as the source data for abbreviations is generally unreliable.
+
 Nuget Installation
 =============================================================================
 ```powershell
@@ -62,29 +65,6 @@ names.Standard == "Central European Standard Time"
 names.Daylight == "Central European Summer Time"
 ```
 
-### GetAbbreviationsForTimeZone
-Look up the localized abbreviations for a specific time zone:
-```csharp
-var abbreviations = TZNames.GetAbbreviationsForTimeZone("America/Los_Angeles", "en-US");
-
-abbreviations.Generic == "PT"
-abbreviations.Standard == "PST"
-abbreviations.Daylight == "PDT"
-```
-
-You can pass a Windows time zone id instead, if you like:
-```csharp
-var abbreviations = TZNames.GetAbbreviationsForTimeZone("Romance Standard Time", "en-GB");
-
-names.Generic == "CET"
-abbreviations.Standard == "CET"
-abbreviations.Daylight == "CEST"
-```
-
-**Note:** Time zone abbreviations are sometimes inconsistent, and are not necessarily
-localized correctly for every time zone.  In most cases, you should use abbreviations
-for end-user display output only.  Do not attempt to use abbreviations when parsing input.
-
 ## Methods for listing time zones
 
 ### GetDisplayNames
@@ -246,7 +226,7 @@ TODO: Add examples for this method.
 
 ### GetFixedTimeZoneAbbreviations
 
-Gets the same list of zones as `GetFixedTimeZoneIds`, but includes localized abbreviations.
+Gets the same list of zones as `GetFixedTimeZoneIds`, but includes abbreviations.
 
 TODO: Add examples for this method.
 

src/TimeZoneNames/TZNames.cs

@@ -210,14 +210,15 @@ public static TimeZoneValues GetNamesForTimeZone(string timeZoneId, string langu
     /// <param name="timeZoneId">An IANA or Windows time zone identifier.</param>
     /// <param name="languageCode">The IETF language tag (culture code) to use when localizing the abbreviations.</param>
     /// <returns>A <see cref="TimeZoneValues"/> object containing the localized generic, standard, and daylight abbreviations.</returns>
+    [Obsolete("WARNING! Time zone abbreviations are inconsistent and not well-defined in the source data.  This method will be removed in a future release.")]
     public static TimeZoneValues GetAbbreviationsForTimeZone(string timeZoneId, string languageCode)
     {
         var langKey = GetLanguageKey(languageCode);
         if (langKey == null)
         {
             throw new ArgumentException("Invalid Language Code", nameof(languageCode));
         }
-        
+
         if (TZConvert.TryWindowsToIana(timeZoneId, out var ianaId))
         {
             timeZoneId = ianaId;
@@ -298,7 +299,7 @@ public static IDictionary<string, string> GetDisplayNames(string languageCode, b
         {
             throw new ArgumentException("Invalid Language Code", nameof(languageCode));
         }
-        
+
         var displayNames = Data.DisplayNames[langKey]
             .Where(x => !TimeZoneData.ObsoleteWindowsZones.Contains(x.Key))
             .ToList();
@@ -307,7 +308,7 @@ public static IDictionary<string, string> GetDisplayNames(string languageCode, b
         {
             return displayNames.ToOrderedDictionary(StringComparer.OrdinalIgnoreCase);
         }
-        
+
         var languageCodeParts = languageCode.Split('_', '-');
         var territoryCode = languageCodeParts.Length < 2 ? "001" : languageCodeParts[1];
         return displayNames.ToOrderedDictionary(
@@ -334,7 +335,7 @@ public static ICollection<string> GetLanguageCodes()
     public static ICollection<string> GetLanguageCodes(bool forDisplayNames)
     {
         var keys = forDisplayNames
-            ? (IEnumerable<string>) Data.DisplayNames.Keys
+            ? (IEnumerable<string>)Data.DisplayNames.Keys
             : Data.CldrLanguageData.Keys;
 
         return keys.OrderBy(x => x).ToList();
@@ -373,7 +374,7 @@ private static string GetLanguageKey(string languageCode, bool forDisplayNames =
 
             if (key == null)
             {
-                var keys = forDisplayNames ? (IEnumerable<string>) Data.DisplayNames.Keys : Data.CldrLanguageData.Keys;
+                var keys = forDisplayNames ? (IEnumerable<string>)Data.DisplayNames.Keys : Data.CldrLanguageData.Keys;
                 key = keys.FirstOrDefault(x =>
                     x.Split('_')[0].Equals(languageCode.Split('-', '_')[0], StringComparison.OrdinalIgnoreCase));
 
@@ -438,7 +439,7 @@ private static TimeZoneValues GetNames(string timeZoneId, string languageKey, bo
 
         if (abbreviations && (timeZoneId == "Etc/GMT" || timeZoneId == "Etc/UTC"))
         {
-            return new TimeZoneValues {Generic = "UTC", Standard = "UTC", Daylight = "UTC"};
+            return new TimeZoneValues { Generic = "UTC", Standard = "UTC", Daylight = "UTC" };
         }
 
         var metaZone = GetMetazone(timeZoneId);
@@ -626,7 +627,8 @@ private static TimeZoneValues GetNames(string timeZoneId, string languageKey, bo
         }
 
         // last chance to make a generic name if it's missing
-        if (values.Generic == null) {
+        if (values.Generic == null)
+        {
             values.Generic = values.Standard;
         }
 

test/TimeZoneNames.Tests/TimeZoneNamesTest.cs

@@ -22,16 +22,6 @@ public void Can_Get_Names_For_US_Pacific()
         Assert.Equal("Pacific Daylight Time", names.Daylight);
     }
 
-    [Fact]
-    public void Can_Get_Abbreviations_For_US_Pacific()
-    {
-        var abbreviations = TZNames.GetAbbreviationsForTimeZone("America/Los_Angeles", "en-US");
-
-        Assert.Equal("PT", abbreviations.Generic);
-        Assert.Equal("PST", abbreviations.Standard);
-        Assert.Equal("PDT", abbreviations.Daylight);
-    }
-
     [Fact]
     public void Can_Get_French_Names_For_US_Pacific()
     {
@@ -42,16 +32,6 @@ public void Can_Get_French_Names_For_US_Pacific()
         Assert.Equal("heure avancée du Pacifique", names.Daylight);
     }
 
-    [Fact]
-    public void Can_Get_French_Abbreviations_For_US_Pacific()
-    {
-        var abbreviations = TZNames.GetAbbreviationsForTimeZone("America/Los_Angeles", "fr-CA");
-
-        Assert.Equal("HP", abbreviations.Generic);
-        Assert.Equal("HNP", abbreviations.Standard);
-        Assert.Equal("HAP", abbreviations.Daylight);
-    }
-
     [Fact]
     public void Can_Get_Names_For_US_Arizona()
     {
@@ -73,26 +53,6 @@ public void Can_Get_Names_For_UK()
         Assert.Equal("British Summer Time", names.Daylight);
     }
 
-    [Fact]
-    public void Can_Get_Abbreviations_For_UK()
-    {
-        var abbreviations = TZNames.GetAbbreviationsForTimeZone("Europe/London", "en-US");
-
-        Assert.Null(abbreviations.Generic);
-        Assert.Equal("GMT", abbreviations.Standard);
-        Assert.Equal("BST", abbreviations.Daylight);
-    }
-
-    [Fact]
-    public void Can_Get_Abbreviations_For_Central_Europe()
-    {
-        var abbreviations = TZNames.GetAbbreviationsForTimeZone("Central European Standard Time", "en-US");
-
-        Assert.Equal("CET", abbreviations.Generic);
-        Assert.Equal("CET", abbreviations.Standard);
-        Assert.Equal("CEST", abbreviations.Daylight);
-    }
-
     [Fact]
     public void Can_Get_Names_For_IE()
     {
@@ -103,16 +63,6 @@ public void Can_Get_Names_For_IE()
         Assert.Equal("Irish Standard Time", names.Daylight);
     }
 
-    [Fact]
-    public void Can_Get_Abbreviations_For_IE()
-    {
-        var abbreviations = TZNames.GetAbbreviationsForTimeZone("Europe/Dublin", "en-US");
-
-        Assert.Null(abbreviations.Generic);
-        Assert.Equal("GMT", abbreviations.Standard);
-        Assert.Equal("IST", abbreviations.Daylight);
-    }
-
     [Fact]
     public void Can_Get_Names_For_IN1()
     {
@@ -123,16 +73,6 @@ public void Can_Get_Names_For_IN1()
         Assert.Equal("India Standard Time", names.Daylight);
     }
 
-    [Fact]
-    public void Can_Get_Abbreviations_For_IN1()
-    {
-        var abbreviations = TZNames.GetAbbreviationsForTimeZone("Asia/Calcutta", "en-US");
-
-        Assert.Equal("IST", abbreviations.Generic);
-        Assert.Equal("IST", abbreviations.Standard);
-        Assert.Equal("IST", abbreviations.Daylight);
-    }
-
     [Fact]
     public void Can_Get_Names_For_IN2()
     {
@@ -143,16 +83,6 @@ public void Can_Get_Names_For_IN2()
         Assert.Equal("India Standard Time", names.Daylight);
     }
 
-    [Fact]
-    public void Can_Get_Abbreviations_For_IN2()
-    {
-        var abbreviations = TZNames.GetAbbreviationsForTimeZone("Asia/Kolkata", "en-US");
-
-        Assert.Equal("IST", abbreviations.Generic);
-        Assert.Equal("IST", abbreviations.Standard);
-        Assert.Equal("IST", abbreviations.Daylight);
-    }
-
     [Fact]
     public void Can_Get_Names_For_CN()
     {
@@ -173,16 +103,6 @@ public void Can_Get_Names_For_CN()
     //    Assert.Equal("Urumqi Daylight Time", names.Daylight);
     //}
 
-    [Fact]
-    public void Can_Get_Abbreviations_For_Sao_Tome()
-    {
-        var abbreviations = TZNames.GetAbbreviationsForTimeZone("Sao Tome Standard Time", "en-GB");
-
-        Assert.Equal("GMT", abbreviations.Generic);
-        Assert.Equal("GMT", abbreviations.Standard);
-        Assert.Equal("GMT", abbreviations.Daylight);
-    }
-
     [Fact]
     public void Can_Get_Names_For_UTC()
     {
@@ -225,16 +145,6 @@ public void Can_Get_Names_For_Windows_Timezone()
         Assert.Equal("Eastern Daylight Time", names.Daylight);
     }
 
-    [Fact]
-    public void Can_Get_Abbreviations_For_Windows_Timezone()
-    {
-        var abbreviations = TZNames.GetAbbreviationsForTimeZone("AUS Eastern Standard Time", "en-US");
-
-        Assert.Equal("AET", abbreviations.Generic);
-        Assert.Equal("AEST", abbreviations.Standard);
-        Assert.Equal("AEDT", abbreviations.Daylight);
-    }
-
     //[Fact]
     //public void Can_Get_Names_For_CA_Pacific_From_MX()
     //{