[ios, macos] Add NSExpression convenience constructors and helper methods. (#11278)

* [ios, macos] Refactor convinience expression initializers.

# Conflicts:
#	platform/darwin/src/NSExpression+MGLAdditions.h
#	platform/darwin/src/NSExpression+MGLAdditions.mm
#	platform/ios/app/MBXViewController.m

* [ios, macos] Add MGL_MATCH convenience method.

# Conflicts:
#	platform/darwin/src/NSExpression+MGLAdditions.h
#	platform/darwin/src/NSExpression+MGLAdditions.mm
#	platform/darwin/test/MGLExpressionTests.mm

* [ios, macos] Add Swift friendly convenience methods name syntax..

# Conflicts:
#	platform/darwin/src/NSExpression+MGLAdditions.h

* [ios, macos] Update runtime styling examples.

# Conflicts:
#	platform/ios/app/MBXViewController.m

* [ios, macos] Add NSExpression variable expressions properties.

* [ios, macos] Clarify convenience initializer names.

* [ios, macos] Update Style Authors guides.

* [ios, macos] Fix cherry-pick merge.

* [ios, macos] Update convenience initializers documentation.

2 files changed, 26 insertions, 18 deletions

diff --git a/platform/ios/app/MBXViewController.m b/platform/ios/app/MBXViewController.m
index 0a76f8c0c5..391af5ea05 100644
--- a/platform/ios/app/MBXViewController.m
+++ b/platform/ios/app/MBXViewController.m
@@ -967,18 +967,20 @@ typedef NS_ENUM(NSInteger, MBXSettingsMiscellaneousRows) {
                                       @10.0f: [UIColor redColor],
                                       @12.0f: [UIColor greenColor],
                                       @14.0f: [UIColor blueColor]};
-    waterLayer.fillColor = [NSExpression expressionWithFormat:
-                            @"mgl_interpolate:withCurveType:parameters:stops:($zoomLevel, 'linear', nil, %@)",
-                            waterColorStops];
+    NSExpression *fillColorExpression = [NSExpression mgl_expressionForInterpolatingExpression:NSExpression.zoomLevelVariableExpression
+                                                                                 withCurveType:MGLExpressionInterpolationModeLinear
+                                                                                    parameters:nil
+                                                                                         stops:[NSExpression expressionForConstantValue:waterColorStops]];
+    waterLayer.fillColor = fillColorExpression;
 
     NSDictionary *fillAntialiasedStops = @{@11: @YES,
                                            @12: @NO,
                                            @13: @YES,
                                            @14: @NO,
                                            @15: @YES};
-    waterLayer.fillAntialiased = [NSExpression expressionWithFormat:
-                                  @"mgl_step:from:stops:($zoomLevel, false, %@)",
-                                  fillAntialiasedStops];
+    waterLayer.fillAntialiased = [NSExpression mgl_expressionForSteppingExpression:NSExpression.zoomLevelVariableExpression
+                                                                    fromExpression:[NSExpression expressionForConstantValue:@NO]
+                                                                             stops:[NSExpression expressionForConstantValue:fillAntialiasedStops]];
 }
 
 - (void)styleRoadLayer
@@ -1467,10 +1469,16 @@ typedef NS_ENUM(NSInteger, MBXSettingsMiscellaneousRows) {
 
     // source, categorical function that sets any feature with a "fill" attribute value of true to red color and anything without to green
     MGLFillStyleLayer *fillStyleLayer = [[MGLFillStyleLayer alloc] initWithIdentifier:@"fill-layer" source:shapeSource];
-    fillStyleLayer.fillColor = [NSExpression expressionWithFormat:@"TERNARY(fill == YES, %@, %@)", [UIColor greenColor], [UIColor redColor]];
+    fillStyleLayer.fillColor = [NSExpression mgl_expressionForConditional:[NSPredicate predicateWithFormat:@"fill == YES"]
+                                                           trueExpression:[NSExpression expressionForConstantValue:[UIColor greenColor]]
+                                                         falseExpresssion:[NSExpression expressionForConstantValue:[UIColor redColor]]];
+                                                               
+    
 
     // source, identity function that sets any feature with an "opacity" attribute to use that value and anything without to 1.0
-    fillStyleLayer.fillOpacity = [NSExpression expressionWithFormat:@"TERNARY(opacity != nil, opacity, 1.0)"];
+    fillStyleLayer.fillOpacity = [NSExpression mgl_expressionForConditional:[NSPredicate predicateWithFormat:@"opacity != nil"]
+                                                             trueExpression:[NSExpression expressionForKeyPath:@"opacity"] 
+                                                           falseExpresssion:[NSExpression expressionForConstantValue:@1.0]];
     [self.mapView.style addLayer:fillStyleLayer];
 }
 
diff --git a/platform/ios/docs/guides/For Style Authors.md b/platform/ios/docs/guides/For Style Authors.md
index 852a9c2ef4..1ce0a4bf4f 100644
--- a/platform/ios/docs/guides/For Style Authors.md
+++ b/platform/ios/docs/guides/For Style Authors.md
@@ -329,9 +329,9 @@ In style specification | Method, function, or predicate type | Format string syn
 `to-number`            | `mgl_numberWithFallbackValues:` | `CAST(zipCode, 'NSNumber')`
 `to-string`            | `stringValue` | `CAST(ele, 'NSString')`
 `typeof`               | |
-`geometry-type`        | |`$geometryType`
-`id`                   | |`$featureIdentifier`
-`properties`           | |`$featureProperties`
+`geometry-type`        | `NSExpression.geometryTypeVariableExpression` | `$geometryType`
+`id`                   | `NSExpression.featureIdentifierVariableExpression` | `$featureIdentifier`
+`properties`           | `NSExpression.featurePropertiesVariableExpression` | `$featureProperties`
 `at`                   | `objectFrom:withIndex:` | `array[n]`
 `get`                  | `+[NSExpression expressionForKeyPath:]` | Key path
 `has`                  | `mgl_does:have:` | `mgl_does:have:(self, 'key')`
@@ -345,14 +345,14 @@ In style specification | Method, function, or predicate type | Format string syn
 `>=`                   | `NSGreaterThanOrEqualToPredicateOperatorType` | `key >= value`
 `all`                  | `NSAndPredicateType` | `p0 AND … AND pn`
 `any`                  | `NSOrPredicateType` | `p0 OR … OR pn`
-`case`                 | `+[NSExpression expressionForConditional:trueExpression:falseExpression:]` or `MGL_IF` | `TERNARY(1 = 2, YES, NO)` or `MGL_IF(1 = 2, YES, 2 = 2, YES, NO)`
+`case`                 | `+[NSExpression expressionForConditional:trueExpression:falseExpression:]` or `MGL_IF` or `+[NSExpression mgl_expressionForConditional:trueExpression:falseExpresssion:]` | `TERNARY(1 = 2, YES, NO)` or `MGL_IF(1 = 2, YES, 2 = 2, YES, NO)`
 `coalesce`             | `mgl_coalesce:` | `mgl_coalesce({x, y, z})`
-`match`                | `MGL_MATCH` | `MGL_MATCH(x, 0, 'zero match', 1, 'one match', 'two match', 'default')`
-`interpolate`          | `mgl_interpolate:withCurveType:parameters:stops:` |
-`step`                 | `mgl_step:withMinimum:stops:` |
+`match`                | `MGL_MATCH` or `+[NSExpression mgl_expressionForMatchingExpression:inDictionary:defaultExpression:]` | `MGL_MATCH(x, 0, 'zero match', 1, 'one match', 'two match', 'default')`
+`interpolate`          | `mgl_interpolate:withCurveType:parameters:stops:` or `+[NSExpression mgl_expressionForInterpolatingExpression:withCurveType:parameters:stops:]` |
+`step`                 | `mgl_step:withMinimum:stops:` or `+[NSExpression mgl_expressionForSteppingExpression:fromExpression:stops:]` |
 `let`                  | `mgl_expressionWithContext:` | `MGL_LET('ios', 11, 'macos', 10.13, $ios + $macos)`
 `var`                  | `+[NSExpression expressionForVariable:]` | `$variable`
-`concat`               | `mgl_join:` | `mgl_join({'Old', ' ', 'MacDonald'})`
+`concat`               | `mgl_join:` or `-[NSExpression mgl_expressionByAppendingExpression:]` | `mgl_join({'Old', ' ', 'MacDonald'})`
 `downcase`             | `lowercase:` | `lowercase('DOWNTOWN')`
 `upcase`               | `uppercase:` | `uppercase('Elysian Fields')`
 `rgb`                  | `+[UIColor colorWithRed:green:blue:alpha:]` |
@@ -383,8 +383,8 @@ In style specification | Method, function, or predicate type | Format string syn
 `sin`                  | |
 `sqrt`                 | `sqrt:` | `sqrt(2)`
 `tan`                  | |
-`zoom`                 | | `$zoom`
-`heatmap-density`      | | `$heatmapDensity`
+`zoom`                 | `NSExpression.zoomLevelVariableExpression` | `$zoom`
+`heatmap-density`      | `NSExpression.heatmapDensityVariableExpression` | `$heatmapDensity`
 
 For operators that have no corresponding `NSExpression` symbol, use the
 `MGL_FUNCTION()` format string syntax.