Easier number to Expression (#72)

* Illustrate simple expression requires 2 type to be specified two times

* Add implicit casts for numbers

* Document how it behaves for null entries

* Update README.md

* Update README.md

Fix typo

Co-authored-by: mr.slow <no-reply@github.com>

Author: mitikov

docs/expressions/README.md

@@ -32,6 +32,44 @@ var layer = new AzureMapsControl.Components.Layers.PolygonExtrusionLayer
 };
 ```
 
+#### Checking if property exists
+
+A necessity to check if [property `has` value](https://docs.microsoft.com/en-us/azure/azure-maps/data-driven-style-expressions-web-sdk#data-expressions) to decide which value to pick during clustering (or data display): 
+
+```
+var expression = Expression.HasProperty("score");
+```
+
+#### Property value getter
+
+Similarly `get` [property value](https://docs.microsoft.com/en-us/azure/azure-maps/data-driven-style-expressions-web-sdk#data-expressions) can be fetched: 
+
+```
+var leafProp = Expression.GetProperty("leafValue");
+```
+
+#### Double is treated as `ExpressionOrNumber`
+
+A portion of APIs require an expression to be evaluated to number, like bubble radius. Since `ExpressionOrNumber` has `implicit` cast from `double?`, you can simply specify number:
+
+```
+ExpressionOrNumber smallRadius = 10;
+```
+
+
+#### Converting `Expression` to `ExpressionOrNumber`
+
+When `expression` evaluates to number, but is represented as general-purpose `Expression` type, call `.ToNumber() to apply `[to-number` cast expression](https://docs.microsoft.com/en-us/azure/azure-maps/data-driven-style-expressions-web-sdk#data-expressions):
+
+```
+Expression alreadyNumber = new ExpressionOrNumber(5); // expression variable is a number for sure
+ExpressionOrNumber expression = alreadyNumber.ToNumber(); 
+```
+
+#### More examples
+
+More API samples can be found in [Expressions Unit Test block](https://github.com/arnaudleclerc/AzureMapsControl.Components/tree/develop/tests/AzureMapsControl.Components.Tests/Atlas/Expression.cs). 
+
 ### Using expressions
 
 The following example would fill the layer with a color based on the `DENSITY` property of the layer source :
@@ -83,4 +121,4 @@ var layer = new AzureMapsControl.Components.Layers.PolygonExtrusionLayer
         FillColor = new Components.Atlas.ExpressionOrString(System.Text.Json.JsonDocument.Parse(fillColorExpressionJsonString))
     }
 };
-```
+```

src/AzureMapsControl.Components/Atlas/Expression.cs

@@ -94,6 +94,8 @@ private struct ClusterProperties
             /// </summary>
             public static readonly string PointCount = "point_count";
         }
+
+        public static implicit operator Expression(double? value) => new ExpressionOrNumber(value);
     }
 
     /// <summary>
@@ -123,6 +125,8 @@ public ExpressionOrNumber(JsonDocument json) : base(json) { }
         /// </summary>
         /// <param name="value">Value which will be used instead of the expression</param>
         public ExpressionOrNumber(double? value) => Value = value;
+
+        public static implicit operator ExpressionOrNumber(double? value) => new(value);
     }
 
     /// <summary>

tests/AzureMapsControl.Components.Tests/Atlas/Expression.cs

@@ -73,6 +73,35 @@ public void ToNumber_WhenNotYetNumber_Wraps()
 
     public class ExpressionOrNumberTests
     {
+        [Fact]
+        public void Number_WhenSupplied_IsExpressionWithoutBoilerplate()
+        {
+            ExpressionOrNumber smallRadius = 10;
+            Assert.IsType<ExpressionOrNumber>(smallRadius);
+        }
+
+        [Fact]
+        public void Cast_ForNull_IsNull()
+        {
+            ExpressionOrNumber expression = null;
+            Assert.Null(expression);
+        }
+
+        [Fact]
+        public void Cast_ForNullableDouble_IsExpression()
+        {
+            double? value = null;
+            ExpressionOrNumber expression = value;
+            Assert.NotNull(expression);
+        }
+
+        [Fact]
+        public void Number_WhenSupplied_CanBeExpressionWithoutBoilerplate()
+        {
+            var radius = Expression.Conditional(Expression.IsCluster, 10, 5);
+            Assert.IsType<Expression>(radius);
+        }
+
         [Fact]
         public void Type_Is_DebugFriendly()
         {
@@ -116,8 +145,8 @@ public void Should_WriteExpressions()
         [Fact]
         public void Should_WriteNumberValue()
         {
-            var value = 1;
-            var expression = new ExpressionOrNumber(value);
+            double value = 1;
+            ExpressionOrNumber expression = value;
 
             TestAndAssertWrite(expression, value.ToString());
         }