✨ Add Quantity.From/TryFrom quantity name and unit name (#1258)

Make it easier to construct quantities from strings describing the
quantity name and unit name, if the unit enum value is not readily
available.

This is useful for custom serialization of quantities, such as mapping
to simple custom quantity DTO types instead of relying on JSON
serialization converters.

### Changes
- Add `Quantity.From` and `TryFrom`
- Refactor `UnitConverter` to reuse code for constructing quantity from
strings
- Add tests for `From` and `TryFrom`
- Add test `CustomSerializationTests.CanMapToJsonAndBackViaCustomDto` to
showcase serialization

### Example
```cs
public record QuantityDto(double Value, string QuantityName, string UnitName); 

// The original quantity.
IQuantity q = Length.FromCentimeters(5);

// Map to DTO.
QuantityDto dto = new(
    Value: (double)q.Value,
    QuantityName: q.QuantityInfo.Name,
    UnitName: q.Unit.ToString());

/* Serialize to JSON:
{
    "Value": 5,
    "QuantityName": "Length",
    "UnitName": "Centimeter"
}
*/
var json = System.Text.Json.JsonSerializer.Serialize(dto);

// Deserialize from JSON.
QuantityDto deserialized = System.Text.Json.JsonSerializer.Deserialize<QuantityDto>(json)!;

// Map to IQuantity.
Quantity.TryFrom(deserialized.Value, deserialized.QuantityName, deserialized.UnitName, out IQuantity? deserializedQuantity);

```

Author: angularsen

README.md

@@ -12,24 +12,23 @@ No more magic constants found on Stack Overflow, no more second-guessing the uni
 
 ### Overview
 
-* [How to install](#how-to-install)
-* [100+ quantities with 1400+ units](UnitsNet/GeneratedCode/Units) generated from [JSON](Common/UnitDefinitions/) by [C# CLI app](CodeGen)
-* [30k unit tests](https://dev.azure.com/unitsnet/Units.NET/_build?definitionId=1)
-* [Statically typed quantities and units](#static-typing) to avoid mistakes and communicate intent
-* Immutable structs
-* [Operator overloads](#operator-overloads) for arithmetic
-* [Parse and ToString()](#culture) supports localization
-* [Dynamically parse and convert](#dynamic-parsing) quantities and units
-* [Extensible with custom units](#custom-units)
-* [Example: Creating a unit converter app](#example-app)
-* [Example: WPF app using IValueConverter to parse quantities from input](#example-wpf-app-using-ivalueconverter-to-parse-quantities-from-input)
-* [Precision and accuracy](#precision)
-* [Serialize to JSON, XML and more](#serialization)
-* [Contribute](#contribute) if you are missing some units
-* [Continuous integration](#ci) posts status reports to pull requests and commits
-* [Who are using this?](#who-are-using)
-
-### <a name="how-to-install"></a>Installing via NuGet
+* [Overview](#overview)
+* [Installing via NuGet](#installing-via-nuget)
+* [Static Typing](#static-typing)
+* [Operator Overloads](#operator-overloads)
+* [Culture and Localization](#culture-and-localization)
+* [Dynamically Parse Quantities and Convert to Units](#dynamically-parse-quantities-and-convert-to-units)
+* [Custom units](#custom-units)
+* [Example: Unit converter app](#example-unit-converter-app)
+* [Example: WPF app using IValueConverter to parse input](#example-wpf-app-using-ivalueconverter-to-parse-input)
+* [Precision and Accuracy](#precision-and-accuracy)
+* [Serialize to JSON, XML and more](#serialize-to-json-xml-and-more)
+* [Want To Contribute?](#want-to-contribute)
+* [Continuous Integration](#continuous-integration)
+* [Who are Using This?](#who-are-using-this)
+* [Units.NET on other platforms](#unitsnet-on-other-platforms)
+
+### Installing via NuGet
 
 Add it via CLI
 
@@ -43,7 +42,7 @@ or go to [NuGet Gallery | UnitsNet](https://www.nuget.org/packages/UnitsNet) for
 * .NET Standard 2.0
 * [.NET nanoFramework](https://www.nanoframework.net/)
 
-### <a name="static-typing"></a>Static Typing
+### Static Typing
 
 ```C#
 // Construct
@@ -67,7 +66,7 @@ string PrintPersonWeight(Mass weight)
 }
 ```
 
-### <a name="operator-overloads"></a>Operator Overloads
+### Operator Overloads
 
 ```C#
 // Arithmetic
@@ -82,7 +81,7 @@ Acceleration a2 = Force.FromNewtons(100) / Mass.FromKilograms(20);
 RotationalSpeed r = Angle.FromDegrees(90) / TimeSpan.FromSeconds(2);
 ```
 
-### <a name="culture"></a>Culture and Localization
+### Culture and Localization
 
 The culture for abbreviations defaults to Thread.CurrentCulture and falls back to US English if not defined. Thread.CurrentCulture affects number formatting unless a custom culture is specified. The relevant methods are:
 
@@ -122,7 +121,7 @@ Unfortunately there is no built-in way to avoid this, either you need to ensure
 Example:
 `Length.Parse("1 pt")` throws `AmbiguousUnitParseException` with message `Cannot parse "pt" since it could be either of these: DtpPoint, PrinterPoint`.
 
-### <a name="dynamic-parsing"></a>Dynamically Parse Quantities and Convert to Units
+### Dynamically Parse Quantities and Convert to Units
 Sometimes you need to work with quantities and units at runtime, such as parsing user input.
 
 There are a handful of classes to help with this:
@@ -169,6 +168,16 @@ if (Quantity.TryFrom(3, LengthUnit.Centimeter, out IQuantity quantity2))
 {
 }
 ```
+
+You can also construct from strings, such as mapping between DTO types in an API:
+```c#
+IQuantity quantity = Quantity.From(value: 3, quantityName: "Length", unitName: "Centimeter");
+
+if (Quantity.TryFrom(value: 3, quantityName: "Length", unitName: "Centimeter", out IQuantity? quantity2))
+{
+}
+```
+
 #### Parse quantity
 Parse any string to a quantity instance of the given the quantity type.
 
@@ -222,7 +231,7 @@ UnitConverter.ConvertByName(1, "Length", "Centimeter", "Millimeter"); // 10 mm
 UnitConverter.ConvertByAbbreviation(1, "Length", "cm", "mm"); // 10 mm
 ```
 
-### <a name="custom-units"></a>Custom units
+### Custom units
 
 Units.NET allows you to add your own units and quantities at runtime, to represent as `IQuantity` and reusing Units.NET for parsing and converting between units.
 
@@ -252,7 +261,7 @@ Console.WriteLine(Convert(HowMuchUnit.Lots)); // 100 lts
 Console.WriteLine(Convert(HowMuchUnit.Tons)); // 10 tns
 ```
 
-### <a name="example-app"></a>Example: Unit converter app
+### Example: Unit converter app
 [Source code](https://github.com/angularsen/UnitsNet/tree/master/Samples/UnitConverter.Wpf) for `Samples/UnitConverter.Wpf`<br/>
 [Download](https://github.com/angularsen/UnitsNet/releases/tag/UnitConverterWpf%2F2018-11-09) (release 2018-11-09 for Windows)
 
@@ -291,15 +300,15 @@ double convertedValue = UnitConverter.Convert(
     SelectedToUnit.UnitEnumValue);  // Enum, such as LengthUnit.Centimeter
 ```
 
-### Example: WPF app using IValueConverter to parse quantities from input
+### Example: WPF app using IValueConverter to parse input
 
 Src: [Samples/WpfMVVMSample](https://github.com/angularsen/UnitsNet/tree/master/Samples/WpfMVVMSample)
 
 ![wpfmvvmsample_219w](https://user-images.githubusercontent.com/787816/34913417-094332e2-f8fd-11e7-9d8a-92db105fbbc9.png)
 
 The purpose of this app is to show how to create an `IValueConverter` in order to bind XAML to quantities.
 
-### <a name="precision"></a>Precision and Accuracy
+### Precision and Accuracy
 
 A base unit is chosen for each unit class, represented by a double value (64-bit), and all conversions go via this unit. This means that there will always be a small error in both representing other units than the base unit as well as converting between units.
 
@@ -309,28 +318,24 @@ The tests accept an error up to 1E-5 for most units added so far. Exceptions inc
 
 For more details, see [Precision](https://github.com/angularsen/UnitsNet/wiki/Precision).
 
-### <a name="serialization"></a>Serialize to JSON, XML and more
-
-* [UnitsNet.Serialization.JsonNet](https://www.nuget.org/packages/UnitsNet.Serialization.JsonNet) with Json.NET (Newtonsoft)
-* [DataContractSerializer](https://docs.microsoft.com/en-us/dotnet/api/system.runtime.serialization.datacontractserializer) XML
-* [DataContractJsonSerializer](https://docs.microsoft.com/en-us/dotnet/api/system.runtime.serialization.json.datacontractjsonserializer) JSON (not recommended*)
+### Serialize to JSON, XML and more
 
-Read more at [Serializing to JSON, XML and more](https://github.com/angularsen/UnitsNet/wiki/Serializing-to-JSON,-XML-and-more).
+Read the wiki on [Serializing to JSON, XML and more](https://github.com/angularsen/UnitsNet/wiki/Serializing-to-JSON,-XML-and-more).
 
 
-### <a name="contribute"></a>Want To Contribute?
+### Want To Contribute?
 
 - [Adding a New Unit](https://github.com/angularsen/UnitsNet/wiki/Adding-a-New-Unit) is fairly easy to do and we are happy to help.
 - Want a new feature or to report a bug? [Create an issue](https://github.com/angularsen/UnitsNet/issues/new/choose) or start a [discussion](https://github.com/angularsen/UnitsNet/discussions).
 
-### <a name="ci"></a>Continuous Integration
+### Continuous Integration
 
 [AppVeyor](https://ci.appveyor.com/project/angularsen/unitsnet) performs the following:
 * Build and test all branches
 * Build and test pull requests, notifies on success or error
 * Deploy nugets on master branch, if nuspec versions changed
 
-### <a name="who-are-using"></a>Who are Using This?
+### Who are Using This?
 
 It would be awesome to know who are using this library. If you would like your project listed here, [create an issue](https://github.com/angularsen/UnitsNet/issues) or edit the [README.md](https://github.com/angularsen/UnitsNet/edit/master/README.md) and send a pull request. Max logo size is `300x35 pixels` and should be in `.png`, `.gif` or `.jpg` formats.
 
@@ -411,7 +416,7 @@ https://github.com/StructuralAnalysisFormat/StructuralAnalysisFormat-SDK
 
 *- Dirk Schuermans, Software Engineer for [SCIA nv](https://www.scia.net)*
 
-## Units.NET on other platforms
+### Units.NET on other platforms
 
 Get the same strongly typed units on other platforms, based on the same [unit definitions](/Common/UnitDefinitions).
 

UnitsNet.Serialization.JsonNet/UnitsNetBaseJsonConverter.cs

@@ -21,7 +21,7 @@ public abstract class UnitsNetBaseJsonConverter<T> : JsonConverter<T>
 
         /// <summary>
         /// Register custom types so that the converter can instantiate these quantities.
-        /// Instead of calling <see cref="Quantity.From"/>, the <see cref="Activator"/> will be used to instantiate the object.
+        /// Instead of calling <see cref="Quantity.From(UnitsNet.QuantityValue,System.Enum)"/>, the <see cref="Activator"/> will be used to instantiate the object.
         /// It is therefore assumed that the constructor of <paramref name="quantity"/> is specified with <c>new T(double value, typeof(<paramref name="unit"/>) unit)</c>.
         /// Registering the same <paramref name="unit"/> multiple times, it will overwrite the one registered.
         /// </summary>

UnitsNet.Tests/QuantityTests.cs

@@ -93,6 +93,56 @@ public void Equals_GenericEquatableIQuantity_OtherIsNull_ReturnsFalse()
             Assert.False(q1.Equals(q2, tolerance));
         }
 
+        [Fact]
+        public void TryFrom_ValidQuantityNameAndUnitName_ReturnsTrueAndQuantity()
+        {
+            void AssertFrom(string quantityName, string unitName, Enum expectedUnit)
+            {
+                Assert.True(Quantity.TryFrom(5, quantityName, unitName, out IQuantity? quantity));
+                Assert.NotNull(quantity);
+                Assert.Equal(5, quantity!.Value);
+                Assert.Equal(expectedUnit, quantity.Unit);
+            }
+
+            AssertFrom("Length", "Centimeter", LengthUnit.Centimeter);
+            AssertFrom("Mass", "Kilogram", MassUnit.Kilogram);
+        }
+
+        [Fact]
+        public void TryFrom_InvalidQuantityNameAndUnitName_ReturnsFalseAndNull()
+        {
+            void AssertInvalid(string quantityName, string unitName)
+            {
+                Assert.False(Quantity.TryFrom(5, quantityName, unitName, out IQuantity? quantity));
+                Assert.Null(quantity);
+            }
+
+            AssertInvalid("Length", "InvalidUnit");
+            AssertInvalid("InvalidQuantity", "Kilogram");
+        }
+
+        [Fact]
+        public void From_ValidQuantityNameAndUnitName_ReturnsQuantity()
+        {
+            void AssertFrom(string quantityName, string unitName, Enum expectedUnit)
+            {
+                IQuantity quantity = Quantity.From(5, quantityName, unitName);
+                Assert.NotNull(quantity);
+                Assert.Equal(5, quantity.Value);
+                Assert.Equal(expectedUnit, quantity.Unit);
+            }
+
+            AssertFrom("Length", "Centimeter", LengthUnit.Centimeter);
+            AssertFrom("Mass", "Kilogram", MassUnit.Kilogram);
+        }
+
+        [Fact]
+        public void From_InvalidQuantityNameOrUnitName_ThrowsUnitNotFoundException()
+        {
+            Assert.Throws<UnitNotFoundException>(() => Quantity.From(5, "Length", "InvalidUnit"));
+            Assert.Throws<UnitNotFoundException>(() => Quantity.From(5, "InvalidQuantity", "Kilogram"));
+        }
+
         private static Length ParseLength(string str)
         {
             return Length.Parse(str, CultureInfo.InvariantCulture);

UnitsNet.Tests/Serialization/CustomSerializationTests.cs

@@ -0,0 +1,52 @@
+// Licensed under MIT No Attribution, see LICENSE file at the root.
+// Copyright 2013 Andreas Gullberg Larsen ([email protected]). Maintained at https://github.com/angularsen/UnitsNet.
+
+using UnitsNet.Units;
+using Xunit;
+
+namespace UnitsNet.Tests.Serialization;
+
+public class CustomSerializationTests
+{
+#if NET7_0_OR_GREATER
+    private record QuantityDto(double Value, string QuantityName, string UnitName);
+
+    /// <summary>
+    ///     This showcases how to serialize and deserialize a quantity to and from JSON using a custom DTO, as described in the wiki:<br />
+    ///     https://github.com/angularsen/UnitsNet/wiki/Serializing-to-JSON,-XML-and-more#-recommended-map-to-your-own-custom-dto-types
+    /// </summary>
+    [Fact]
+    public void CanMapToJsonAndBackViaCustomDto()
+    {
+        // The original quantity.
+        IQuantity q = Length.FromCentimeters(5);
+
+        // Map to DTO.
+        QuantityDto dto = new(
+            Value: (double)q.Value,
+            QuantityName: q.QuantityInfo.Name,
+            UnitName: q.Unit.ToString());
+
+        /* Serialize to JSON:
+        {
+            "Value": 5,
+            "QuantityName": "Length",
+            "UnitName": "Centimeter"
+        }
+        */
+        string json = System.Text.Json.JsonSerializer.Serialize(dto);
+
+        // Deserialize from JSON.
+        QuantityDto deserialized = System.Text.Json.JsonSerializer.Deserialize<QuantityDto>(json)!;
+
+        // Map to IQuantity.
+        bool tryFromResult = Quantity.TryFrom(deserialized.Value, deserialized.QuantityName, deserialized.UnitName, out IQuantity? deserializedQuantity);
+
+        // Assert
+        Assert.True(tryFromResult);
+        Assert.NotNull(deserializedQuantity);
+        Assert.Equal(5, deserializedQuantity!.Value);
+        Assert.Equal(LengthUnit.Centimeter, deserializedQuantity.Unit);
+    }
+#endif
+}

UnitsNet/CustomCode/Quantity.cs

@@ -61,25 +61,53 @@ public static bool TryGetUnitInfo(Enum unitEnum, [NotNullWhen(true)] out UnitInf
         /// <exception cref="ArgumentException">Unit value is not a know unit enum type.</exception>
         public static IQuantity From(QuantityValue value, Enum unit)
         {
-            if (TryFrom(value, unit, out IQuantity? quantity))
-                return quantity;
+            return TryFrom(value, unit, out IQuantity? quantity)
+                ? quantity
+                : throw new ArgumentException($"Unit value {unit} of type {unit.GetType()} is not a known unit enum type. Expected types like UnitsNet.Units.LengthUnit. Did you pass in a third-party enum type defined outside UnitsNet library?");
+        }
 
-            throw new ArgumentException(
-                $"Unit value {unit} of type {unit.GetType()} is not a known unit enum type. Expected types like UnitsNet.Units.LengthUnit. Did you pass in a third-party enum type defined outside UnitsNet library?");
+        /// <summary>
+        ///     Dynamically construct a quantity from a value, the quantity name and the unit name.
+        /// </summary>
+        /// <param name="value">Numeric value.</param>
+        /// <param name="quantityName">The invariant quantity name, such as "Length". Does not support localization.</param>
+        /// <param name="unitName">The invariant unit enum name, such as "Meter". Does not support localization.</param>
+        /// <returns>An <see cref="IQuantity"/> object.</returns>
+        /// <exception cref="ArgumentException">Unit value is not a know unit enum type.</exception>
+        public static IQuantity From(QuantityValue value, string quantityName, string unitName)
+        {
+            // Get enum value for this unit, f.ex. LengthUnit.Meter for unit name "Meter".
+            return UnitConverter.TryParseUnit(quantityName, unitName, out Enum? unitValue)
+                ? From(value, unitValue)
+                : throw new UnitNotFoundException($"Unit [{unitName}] not found for quantity [{quantityName}].");
         }
 
         /// <inheritdoc cref="TryFrom(QuantityValue,System.Enum,out UnitsNet.IQuantity)"/>
         public static bool TryFrom(double value, Enum unit, [NotNullWhen(true)] out IQuantity? quantity)
         {
+            quantity = default;
+
             // Implicit cast to QuantityValue would prevent TryFrom from being called,
             // so we need to explicitly check this here for double arguments.
-            if (double.IsNaN(value) || double.IsInfinity(value))
-            {
-                quantity = default(IQuantity);
-                return false;
-            }
+            return !double.IsNaN(value) &&
+                   !double.IsInfinity(value) &&
+                   TryFrom((QuantityValue)value, unit, out quantity);
+        }
+
+        /// <summary>
+        ///     Try to dynamically construct a quantity from a value, the quantity name and the unit name.
+        /// </summary>
+        /// <param name="value">Numeric value.</param>
+        /// <param name="unitName">The invariant unit enum name, such as "Meter". Does not support localization.</param>
+        /// <param name="quantityName">The invariant quantity name, such as "Length". Does not support localization.</param>
+        /// <param name="quantity">The constructed quantity, if successful, otherwise null.</param>
+        /// <returns><c>True</c> if successful with <paramref name="quantity"/> assigned the value, otherwise <c>false</c>.</returns>
+        public static bool TryFrom(double value, string quantityName, string unitName, [NotNullWhen(true)] out IQuantity? quantity)
+        {
+            quantity = default;
 
-            return TryFrom((QuantityValue)value, unit, out quantity);
+            return UnitConverter.TryParseUnit(quantityName, unitName, out Enum? unitValue) &&
+                   TryFrom(value, unitValue, out quantity);
         }
 
         /// <inheritdoc cref="Parse(IFormatProvider, System.Type,string)"/>