🚸Describe why Parse fails due to case-insensitive ambiguity (angularsen#1484)

Fixes angularsen#1423

`UnitParser.Parse<LengthUnit>("MM")` fails due to matching both
`Megameter` and `Millimeter` in case-insensitive matching, but matches
neither of them in the case-sensitive fallback. It was confusing to get
`UnitsNotFoundException` in this case, since case-insensitive usually
works for most units.

### Changes
- Handle this case and throw `AmbiguousUnitParseException` instead of
`UnitNotFoundException`
- Describe the case-insensitive units that matched
- Fix existing test
`Parse_WithMultipleCaseInsensitiveMatchesButNoExactMatches_ThrowsUnitNotFoundException`
- Skip retrying with fallback culture if no specific `formatProvider`
was given

Author: angularsen

UnitsNet.Serialization.JsonNet/AbbreviatedUnitsConverter.cs

@@ -178,7 +178,7 @@ protected string GetQuantityType(IQuantity quantity)
         }
 
         /// <summary>
-        ///     Attempt to find an a unique (non-ambiguous) unit matching the provided abbreviation.
+        ///     Attempt to find a unique (non-ambiguous) unit matching the provided abbreviation.
         ///     <remarks>
         ///         An exhaustive search using all quantities is very likely to fail with an
         ///         <exception cref="AmbiguousUnitParseException" />, so make sure you're using the minimum set of supported quantities.

UnitsNet.Tests/QuantityParserTests.cs

@@ -42,7 +42,7 @@ public void Parse_WithOneCaseInsensitiveMatchAndOneExactMatch_ParsesWithTheExact
         }
 
         [Fact]
-        public void Parse_WithMultipleCaseInsensitiveMatchesButNoExactMatches_ThrowsUnitNotFoundException()
+        public void Parse_WithMultipleCaseInsensitiveMatchesButNoExactMatches_ThrowsAmbiguousUnitParseException()
         {
             var unitAbbreviationsCache = new UnitAbbreviationsCache();
             unitAbbreviationsCache.MapUnitToAbbreviation(HowMuchUnit.Some, "foo");
@@ -54,7 +54,8 @@ void Act()
                 quantityParser.Parse<HowMuch, HowMuchUnit>("1 Foo", null, (value, unit) => new HowMuch((double) value, unit));
             }
 
-            Assert.Throws<UnitNotFoundException>(Act);
+            var ex = Assert.Throws<AmbiguousUnitParseException>(Act);
+            Assert.Equal("""Cannot parse "Foo" since it matches multiple units: ATon ("FOO"), Some ("foo").""", ex.Message);
         }
 
         [Fact]

UnitsNet.Tests/UnitParserTests.cs

@@ -115,8 +115,8 @@ public void Parse_AmbiguousUnitsThrowsException()
             var exception2 = Assert.Throws<AmbiguousUnitParseException>(() => Length.Parse("1 pt", CultureInfo.InvariantCulture));
 
             // Assert
-            Assert.Equal("Cannot parse \"pt\" since it could be either of these: DtpPoint, PrinterPoint", exception1.Message);
-            Assert.Equal("Cannot parse \"pt\" since it could be either of these: DtpPoint, PrinterPoint", exception2.Message);
+            Assert.Equal("""Cannot parse "pt" since it matches multiple units: DtpPoint ("pt"), PrinterPoint ("pt").""", exception1.Message);
+            Assert.Equal("""Cannot parse "pt" since it matches multiple units: DtpPoint ("pt"), PrinterPoint ("pt").""", exception2.Message);
         }
 
         [Theory]
@@ -144,6 +144,13 @@ public void Parse_MappedCustomUnit()
             Assert.Equal(HowMuchUnit.Some, parsedUnit);
         }
 
+        [Fact]
+        public void Parse_LengthUnit_MM_ThrowsExceptionDescribingTheAmbiguity()
+        {
+            var ex = Assert.Throws<AmbiguousUnitParseException>(() => UnitsNetSetup.Default.UnitParser.Parse<LengthUnit>("MM"));
+            Assert.Equal("""Cannot parse "MM" since it matches multiple units: Megameter ("Mm"), Millimeter ("mm").""", ex.Message);
+        }
+        
         [Fact]
         public void TryParse_WithNullAbbreviation_ReturnsFalse()
         {

UnitsNet/CustomCode/UnitParser.cs

@@ -87,8 +87,8 @@ public Enum Parse(string unitAbbreviation, Type unitType, IFormatProvider? forma
                         formatProvider = UnitAbbreviationsCache.FallbackCulture;
                         continue;
                     default:
-                        var unitsCsv = string.Join(", ", matches.Select(x => Enum.GetName(unitType, x.Unit)).ToArray());
-                        throw new AmbiguousUnitParseException($"Cannot parse \"{unitAbbreviation}\" since it could be either of these: {unitsCsv}");
+                        var unitsCsv = string.Join(", ", matches.Select(x => $"{Enum.GetName(unitType, x.Unit)} (\"{x.Abbreviation}\")").OrderBy(x => x));
+                        throw new AmbiguousUnitParseException($"Cannot parse \"{unitAbbreviation}\" since it matches multiple units: {unitsCsv}.");
                 }
             }
         }
@@ -216,21 +216,26 @@ public bool TryParse([NotNullWhen(true)] string? unitAbbreviation, Type unitType
             // TODO see about optimizing this method: both Parse and TryParse only care about having one match (in case of a failure we could return the number of matches)
             List<(Enum Unit, string Abbreviation)> stringUnitPairs = _unitAbbreviationsCache.GetStringUnitPairs(enumValues, formatProvider);
             (Enum Unit, string Abbreviation)[] matches =
-                stringUnitPairs.Where(pair => pair.Item2.Equals(unitAbbreviation, StringComparison.OrdinalIgnoreCase)).ToArray();
+                stringUnitPairs.Where(pair => pair.Abbreviation.Equals(unitAbbreviation, StringComparison.OrdinalIgnoreCase)).ToArray();
 
             if (matches.Length == 0)
             {
-                unitAbbreviation = NormalizeUnitString(unitAbbreviation);
-                matches = stringUnitPairs.Where(pair => pair.Item2.Equals(unitAbbreviation, StringComparison.OrdinalIgnoreCase)).ToArray();
+                var normalizeUnitString = NormalizeUnitString(unitAbbreviation);
+                if (unitAbbreviation != normalizeUnitString)
+                {
+                    unitAbbreviation = normalizeUnitString;
+                    matches = stringUnitPairs.Where(pair => pair.Abbreviation.Equals(unitAbbreviation, StringComparison.OrdinalIgnoreCase)).ToArray();
+                }
             }
 
-            // Narrow the search if too many hits, for example Megabar "Mbar" and Millibar "mbar" need to be distinguished
-            if (matches.Length > 1)
+            if (matches.Length == 1)
             {
-                matches = stringUnitPairs.Where(pair => pair.Item2.Equals(unitAbbreviation)).ToArray();
+                return matches;
             }
-
-            return matches;
+            
+            // Narrow the search if too many hits, for example Megabar "Mbar" and Millibar "mbar" need to be distinguished
+            (Enum Unit, string Abbreviation)[] caseSensitiveMatches = stringUnitPairs.Where(pair => pair.Abbreviation.Equals(unitAbbreviation)).ToArray();
+            return caseSensitiveMatches.Length == 0 ? matches : caseSensitiveMatches;
         }
     }
 }