Merge pull request #389 from angularsen/angularsen/preserve-value-unit

### Motivation
Preserve the original value and unit and add getter properties `Value` and `Unit` to expose them.
Use `Unit` in `ToString()` instead of the base unit representation, to better match the units the user is working with.

This is a significant rewrite of how values are stored and how conversions are performed in quantity types. It is also the first baby steps of introducing some common values in base types #371 .

**There should be no breaking changes in neither main lib nor JSON serialization.**

### Changes
Using example of `Length`, but this applies to all quantities:
- Change private field `_meters` to `_value` (still `double` or `decimal`, as before)
- Add private field `LengthUnit? _unit`
- Add `Value` getter prop (`double` or `decimal`)
- Add `LengthUnit Unit` getter prop, with fallback to base unit `LengthUnit.Meter` (1)
- Ctors without unit param assumes `BaseUnit`, backwards compatible
- Change `ToString()` to use `Unit` instead of `DefaultToStringUnit`, new test cases
- Mark `DefaultToStringUnit` as obsolete
- Add support for preserving `decimal` precision in `QuantityValue` (2)
- Defer conversion to base unit until calling properties like `.Centimeters` (3)
- Serialize `Value`+`Unit` instead of base unit and base unit value, backwards compatible, update test cases
- Make internals of UnitsNet visible to Json to reuse reflection abstraction code
- Rename variables in JSON serialization lib (use "quantity" term instead of "unit")

1) Default ctor (`struct`) and ctors without unit param assumes base unit, to be backwards compatible. We might want to change this in the future to require explicitly specifying the unit.
2) Needed to avoid precision issues going via double to construct decimal values.
3) Getting the value of unit properties is now twice as slow, as it first converts from `Unit` to base unit, then to target unit. Before this change, the first conversion was initially made when constructing the quantity. However, there are optimizations in-place to avoid converting if `Unit` already matches either base unit or the target unit.

### Gotchas
- Serialization output changed (different value and unit for same quantity)
- In #389 (comment) I discuss the choice to not go with breaking change with regards to unspecified unit, but why we may want to do so later to require explicitly specifying the unit

Author: angularsen

UnitsNet.Serialization.JsonNet.Tests/UnitsNetJsonConverterTests.cs

@@ -51,24 +51,35 @@ public class Serialize : UnitsNetJsonConverterTests
             public void Information_CanSerializeVeryLargeValues()
             {
                 Information i = Information.FromExabytes(1E+9);
-                var expectedJson = "{\n  \"Unit\": \"InformationUnit.Bit\",\n  \"Value\": 8E+27\n}";
+                var expectedJson = "{\n  \"Unit\": \"InformationUnit.Exabyte\",\n  \"Value\": 1000000000.0\n}";
 
                 string json = SerializeObject(i);
 
                 Assert.Equal(expectedJson, json);
             }
 
             [Fact]
-            public void Mass_ExpectKilogramsUsedAsBaseValueAndUnit()
+            public void Mass_ExpectConstructedValueAndUnit()
             {
                 Mass mass = Mass.FromPounds(200);
-                var expectedJson = "{\n  \"Unit\": \"MassUnit.Kilogram\",\n  \"Value\": 90.718474\n}";
+                var expectedJson = "{\n  \"Unit\": \"MassUnit.Pound\",\n  \"Value\": 200.0\n}";
 
                 string json = SerializeObject(mass);
 
                 Assert.Equal(expectedJson, json);
             }
 
+            [Fact]
+            public void Information_ExpectConstructedValueAndUnit()
+            {
+                Information quantity = Information.FromKilobytes(54);
+                var expectedJson = "{\n  \"Unit\": \"InformationUnit.Kilobyte\",\n  \"Value\": 54.0\n}";
+
+                string json = SerializeObject(quantity);
+
+                Assert.Equal(expectedJson, json);
+            }
+
             [Fact]
             public void NonNullNullableValue_ExpectJsonUnaffected()
             {
@@ -122,7 +133,7 @@ public void NullValue_ExpectJsonContainsNullString()
             public void Ratio_ExpectDecimalFractionsUsedAsBaseValueAndUnit()
             {
                 Ratio ratio = Ratio.FromPartsPerThousand(250);
-                var expectedJson = "{\n  \"Unit\": \"RatioUnit.DecimalFraction\",\n  \"Value\": 0.25\n}";
+                var expectedJson = "{\n  \"Unit\": \"RatioUnit.PartPerThousand\",\n  \"Value\": 250.0\n}";
 
                 string json = SerializeObject(ratio);
 
@@ -376,4 +387,4 @@ private class TestObjWithThreeIComparable
             public IComparable Value3 { get; set; }
         }
     }
-}
+}

UnitsNet.Serialization.JsonNet/UnitsNet.Serialization.JsonNet.Signed.csproj

@@ -9,6 +9,7 @@
 
   <!-- Enable strong name signing -->
   <PropertyGroup>
+    <DefineConstants>SIGNED</DefineConstants>
     <SignAssembly>true</SignAssembly>
     <AssemblyOriginatorKeyFile>$(MSBuildProjectDirectory)\..\UnitsNet.snk</AssemblyOriginatorKeyFile>
   </PropertyGroup>

UnitsNet.Serialization.JsonNet/UnitsNetJsonConverter.cs

@@ -20,18 +20,19 @@
 // THE SOFTWARE.
 
 using System;
-using System.Globalization;
 using System.Linq;
 using System.Reflection;
 using JetBrains.Annotations;
 using Newtonsoft.Json;
 using Newtonsoft.Json.Linq;
+using UnitsNet.InternalHelpers;
 
 namespace UnitsNet.Serialization.JsonNet
 {
+    /// <inheritdoc />
     /// <summary>
-    ///     A JSON.net <see cref="JsonConverter" /> for converting to/from JSON and Units.NET
-    ///     units like <see cref="Length" /> and <see cref="Mass" />.
+    ///     A JSON.net <see cref="T:Newtonsoft.Json.JsonConverter" /> for converting to/from JSON and Units.NET
+    ///     units like <see cref="T:UnitsNet.Length" /> and <see cref="T:UnitsNet.Mass" />.
     /// </summary>
     /// <remarks>
     ///     Relies on reflection and the type names and namespaces as of 3.x.x of Units.NET.
@@ -42,6 +43,11 @@ namespace UnitsNet.Serialization.JsonNet
     /// </remarks>
     public class UnitsNetJsonConverter : JsonConverter
     {
+        /// <summary>
+        /// Numeric value field of a quantity, typically of type double or decimal.
+        /// </summary>
+        private const string ValueFieldName = "_value";
+
         /// <summary>
         ///     Reads the JSON representation of the object.
         /// </summary>
@@ -61,9 +67,8 @@ public override object ReadJson(JsonReader reader, Type objectType, object exist
                 return reader.Value;
             }
             object obj = TryDeserializeIComparable(reader, serializer);
-            var vu = obj as ValueUnit;
             // A null System.Nullable value or a comparable type was deserialized so return this
-            if (vu == null)
+            if (!(obj is ValueUnit vu))
             {
                 return obj;
             }
@@ -73,53 +78,82 @@ public override object ReadJson(JsonReader reader, Type objectType, object exist
             string unitEnumValue = vu.Unit.Split('.')[1];
 
             // "MassUnit" => "Mass"
-            string unitTypeName = unitEnumTypeName.Substring(0, unitEnumTypeName.Length - "Unit".Length);
+            string quantityTypeName = unitEnumTypeName.Substring(0, unitEnumTypeName.Length - "Unit".Length);
 
             // "UnitsNet.Units.MassUnit,UnitsNet"
             string unitEnumTypeAssemblyQualifiedName = "UnitsNet.Units." + unitEnumTypeName + ",UnitsNet";
 
             // "UnitsNet.Mass,UnitsNet"
-            string unitTypeAssemblyQualifiedName = "UnitsNet." + unitTypeName + ",UnitsNet";
+            string quantityTypeAssemblyQualifiedName = "UnitsNet." + quantityTypeName + ",UnitsNet";
 
             // -- see http://stackoverflow.com/a/6465096/1256096 for details
-            Type reflectedUnitEnumType = Type.GetType(unitEnumTypeAssemblyQualifiedName);
-            if (reflectedUnitEnumType == null)
+            Type unitEnumType = Type.GetType(unitEnumTypeAssemblyQualifiedName);
+            if (unitEnumType == null)
             {
                 var ex = new UnitsNetException("Unable to find enum type.");
                 ex.Data["type"] = unitEnumTypeAssemblyQualifiedName;
                 throw ex;
             }
 
-            Type reflectedUnitType = Type.GetType(unitTypeAssemblyQualifiedName);
-            if (reflectedUnitType == null)
+            Type quantityType = Type.GetType(quantityTypeAssemblyQualifiedName);
+            if (quantityType == null)
             {
                 var ex = new UnitsNetException("Unable to find unit type.");
-                ex.Data["type"] = unitTypeAssemblyQualifiedName;
+                ex.Data["type"] = quantityTypeAssemblyQualifiedName;
                 throw ex;
             }
 
-            object unit = Enum.Parse(reflectedUnitEnumType, unitEnumValue);
+            double value = vu.Value;
+            object unitValue = Enum.Parse(unitEnumType, unitEnumValue); // Ex: MassUnit.Kilogram
 
-            // Mass.From() method, assume no overloads exist
-            var fromMethod = reflectedUnitType
-#if (NETSTANDARD1_0)
-                    .GetTypeInfo()
-                .GetDeclaredMethods("From")
-                .Single(m => !m.ReturnType.IsConstructedGenericType);
-#else
-                .GetMethods()
-                .Single(m => m.Name.Equals("From", StringComparison.InvariantCulture) &&
-                    !m.ReturnType.IsGenericType);
-#endif
+            return CreateQuantity(quantityType, value, unitValue);
+        }
 
-            // Implicit cast: we use this type to avoid explosion of method overloads to handle multiple number types
-            QuantityValue quantityValue = vu.Value;
+        /// <summary>
+        /// Creates a quantity (ex: Mass) based on the reflected quantity type, a numeric value and a unit value (ex: MassUnit.Kilogram).
+        /// </summary>
+        /// <param name="quantityType">Type of quantity, such as <see cref="Mass"/>.</param>
+        /// <param name="value">Numeric value.</param>
+        /// <param name="unitValue">The unit, such as <see cref="MassUnit.Kilogram"/>.</param>
+        /// <returns>The constructed quantity, such as <see cref="Mass"/>.</returns>
+        private static object CreateQuantity(Type quantityType, double value, object unitValue)
+        {
+            // We want the non-nullable return type, example candidates if quantity type is Mass:
+            // double Mass.From(double, MassUnit)
+            // double? Mass.From(double?, MassUnit)
+            MethodInfo notNullableFromMethod = quantityType
+                .GetDeclaredMethods()
+                .Single(m => m.Name == "From" && Nullable.GetUnderlyingType(m.ReturnType) == null);
+
+            // Of type QuantityValue
+            object quantityValue = GetFromMethodValueArgument(notNullableFromMethod, value);
 
             // Ex: Mass.From(55, MassUnit.Gram)
             // TODO: there is a possible loss of precision if base value requires higher precision than double can represent.
             // Example: Serializing Information.FromExabytes(100) then deserializing to Information 
             // will likely return a very different result. Not sure how we can handle this?
-            return fromMethod.Invoke(null, new[] {quantityValue, unit});
+            return notNullableFromMethod.Invoke(null, new[] {quantityValue, unitValue});
+        }
+
+        /// <summary>
+        /// Returns numeric value wrapped as <see cref="QuantityValue"/>, based on the type of argument
+        /// of <paramref name="fromMethod"/>. Today this is always <see cref="QuantityValue"/>, but
+        /// we may extend to other types later such as QuantityValueDecimal.
+        /// </summary>
+        /// <param name="fromMethod">The reflected From(value, unit) method.</param>
+        /// <param name="value">The value to convert to the correct wrapper type.</param>
+        /// <returns></returns>
+        private static object GetFromMethodValueArgument(MethodInfo fromMethod, double value)
+        {
+            Type valueParameterType = fromMethod.GetParameters()[0].ParameterType;
+            if (valueParameterType == typeof(QuantityValue))
+            {
+                // We use this type that takes implicit cast from all number types to avoid explosion of method overloads that take a numeric value.
+                return (QuantityValue) value;
+            }
+
+            throw new Exception(
+                $"The first parameter of the reflected quantity From() method was expected to be either UnitsNet.QuantityValue, but was instead {valueParameterType}.");
         }
 
         private static object TryDeserializeIComparable(JsonReader reader, JsonSerializer serializer)
@@ -147,77 +181,96 @@ private static object TryDeserializeIComparable(JsonReader reader, JsonSerialize
         ///     Writes the JSON representation of the object.
         /// </summary>
         /// <param name="writer">The <see cref="T:Newtonsoft.Json.JsonWriter" /> to write to.</param>
-        /// <param name="value">The value to write.</param>
+        /// <param name="obj">The value to write.</param>
         /// <param name="serializer">The calling serializer.</param>
         /// <exception cref="UnitsNetException">Can't serialize 'null' value.</exception>
-        public override void WriteJson(JsonWriter writer, object value, JsonSerializer serializer)
+        public override void WriteJson(JsonWriter writer, object obj, JsonSerializer serializer)
         {
-            Type unitType = value.GetType();
+            Type quantityType = obj.GetType();
 
             // ValueUnit should be written as usual (but read in a custom way)
-            if(unitType == typeof(ValueUnit))
+            if(quantityType == typeof(ValueUnit))
             {
                 JsonSerializer localSerializer = new JsonSerializer()
                 {
                     TypeNameHandling = serializer.TypeNameHandling,
                 };
-                JToken t = JToken.FromObject(value, localSerializer);
+                JToken t = JToken.FromObject(obj, localSerializer);
 
                 t.WriteTo(writer);
                 return;
             }
+
+            object quantityValue = GetValueOfQuantity(obj, quantityType); // double or decimal value
+            string quantityUnitName = GetUnitFullNameOfQuantity(obj, quantityType); // Example: "MassUnit.Kilogram"
+
+            serializer.Serialize(writer, new ValueUnit
+            {
+                // TODO Should we serialize long, decimal and long differently?
+                Value = Convert.ToDouble(quantityValue),
+                Unit = quantityUnitName
+            });
+        }
+
+        /// <summary>
+        /// Given quantity (ex: <see cref="Mass"/>), returns the full name (ex: "MassUnit.Kilogram") of the constructed unit given by the <see cref="Mass.Unit"/> property.
+        /// </summary>
+        /// <param name="obj">Quantity, such as <see cref="Mass"/>.</param>
+        /// <param name="quantityType">The type of <paramref name="obj"/>, passed in here to reuse a previous lookup.</param>
+        /// <returns>"MassUnit.Kilogram" for a mass quantity whose Unit property is MassUnit.Kilogram.</returns>
+        private static string GetUnitFullNameOfQuantity(object obj, Type quantityType)
+        {
+            // Get value of Unit property
+            PropertyInfo unitProperty = quantityType.GetPropety("Unit");
+            Enum quantityUnit = (Enum) unitProperty.GetValue(obj, null); // MassUnit.Kilogram
+
+            Type unitType = quantityUnit.GetType(); // MassUnit
+            return $"{unitType.Name}.{quantityUnit}"; // "MassUnit.Kilogram"
+        }
+
+        private static object GetValueOfQuantity(object value, Type quantityType)
+        {
+            FieldInfo valueField = GetPrivateInstanceField(quantityType, ValueFieldName);
+
+            // Unit base type can be double, long or decimal,
+            // so make sure we serialize the real type to avoid
+            // loss of precision
+            object quantityValue = valueField.GetValue(value);
+            return quantityValue;
+        }
+
+        private static FieldInfo GetPrivateInstanceField(Type quantityType, string fieldName)
+        {
             FieldInfo baseValueField;
             try
             {
-                baseValueField = unitType
+                baseValueField = quantityType
 #if (NETSTANDARD1_0)
                     .GetTypeInfo()
-
                     .DeclaredFields
-                    .SingleOrDefault(f => !f.IsPublic && !f.IsStatic);
+                    .Where(f => !f.IsPublic && !f.IsStatic)
 #else
                     .GetFields(BindingFlags.NonPublic | BindingFlags.Instance | BindingFlags.DeclaredOnly)
-                    .SingleOrDefault();
 #endif
+                    .SingleOrDefault(f => f.Name == fieldName);
             }
             catch (InvalidOperationException)
             {
-                var ex = new UnitsNetException("Expected exactly 1 private field, but found multiple.");
-                ex.Data["type"] = unitType;
+                var ex = new UnitsNetException($"Expected exactly one private field named [{fieldName}], but found multiple.");
+                ex.Data["type"] = quantityType;
+                ex.Data["fieldName"] = fieldName;
                 throw ex;
             }
+
             if (baseValueField == null)
             {
                 var ex = new UnitsNetException("No private fields found in type.");
-                ex.Data["type"] = unitType;
+                ex.Data["type"] = quantityType;
+                ex.Data["fieldName"] = fieldName;
                 throw ex;
             }
-            // Unit base type can be double, long or decimal,
-            // so make sure we serialize the real type to avoid
-            // loss of precision
-            object baseValue = baseValueField.GetValue(value);
-
-            // Mass => "MassUnit.Kilogram"
-            PropertyInfo baseUnitPropInfo = unitType
-#if (NETSTANDARD1_0)
-                    .GetTypeInfo()
-                    .GetDeclaredProperty("BaseUnit");
-#else
-                .GetProperty("BaseUnit");
-#endif
 
-            // Read static BaseUnit property value
-            var baseUnitEnumValue = (Enum) baseUnitPropInfo.GetValue(null, null);
-            Type baseUnitType = baseUnitEnumValue.GetType();
-            string baseUnit = $"{baseUnitType.Name}.{baseUnitEnumValue}";
-
-            serializer.Serialize(writer, new ValueUnit
-            {
-                // This might throw OverflowException for very large values?
-                // TODO Should we serialize long, decimal and long differently?
-                Value = Convert.ToDouble(baseValue),
-                Unit = baseUnit
-            });
+            return baseValueField;
         }
 
         /// <summary>
@@ -261,7 +314,7 @@ public override bool CanConvert(Type objectType)
         /// </summary>
         /// <param name="objectType">Type of the object.</param>
         /// <returns><c>true</c> if the object type is nullable; otherwise <c>false</c>.</returns>
-        protected bool IsNullable(Type objectType)
+        private static bool IsNullable(Type objectType)
         {
             return Nullable.GetUnderlyingType(objectType) != null;
         }
@@ -280,4 +333,4 @@ protected virtual bool CanConvertNullable(Type objectType)
 
 #endregion
     }
-}
+}