From 27eee6adf5bdc7a67204153e95f596f984fd0a42 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Minh=20Nguye=CC=82=CC=83n?= <mxn@1ec5.org>
Date: Fri, 1 May 2020 11:59:04 -0700
Subject: [PATCH] [ios, macos] Added distance expression function
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Installed an mgl_distanceFrom: aftermarket expression function that corresponds to the “distance” expression operator in style JSON.
---
 .../darwin/docs/guides/For Style Authors.md.ejs   |  1 +
 .../docs/guides/Predicates and Expressions.md     | 15 +++++++++++++++
 platform/darwin/src/NSExpression+MGLAdditions.mm  | 12 ++++++++++++
 platform/darwin/test/MGLExpressionTests.mm        | 12 ++++++++++++
 platform/ios/CHANGELOG.md                         |  4 ++--
 platform/ios/docs/guides/For Style Authors.md     |  1 +
 platform/macos/CHANGELOG.md                       |  2 +-
 platform/macos/docs/guides/For Style Authors.md   |  1 +
 8 files changed, 45 insertions(+), 3 deletions(-)

diff --git a/platform/darwin/docs/guides/For Style Authors.md.ejs b/platform/darwin/docs/guides/For Style Authors.md.ejs
index 120982a2a..bdaa89753 100644
--- a/platform/darwin/docs/guides/For Style Authors.md.ejs	
+++ b/platform/darwin/docs/guides/For Style Authors.md.ejs	
@@ -389,6 +389,7 @@ In style specification | Method, function, or predicate type | Format string syn
 `atan`                 | `mgl_atan:` | `mgl_atan(20)`
 `ceil`                 | `ceiling:` | `ceiling(0.99999)`
 `cos`                  | `mgl_cos:` | `mgl_cos(0)`
+`distance`             | | `mgl_distanceFrom(%@)` where `%@` is an `MGLShape`
 `e`                    | | `%@` representing `NSNumber` containing `M_E`
 `floor`                | `floor:` | `floor(-0.99999)`
 `ln`                   | `ln:` | `ln(2)`
diff --git a/platform/darwin/docs/guides/Predicates and Expressions.md b/platform/darwin/docs/guides/Predicates and Expressions.md
index 67d39d212..2cb493d75 100644
--- a/platform/darwin/docs/guides/Predicates and Expressions.md	
+++ b/platform/darwin/docs/guides/Predicates and Expressions.md	
@@ -540,6 +540,21 @@ This function corresponds to the
 [`tan`](https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions-tan)
 operator in the Mapbox Style Specification.
 
+### `mgl_distanceFrom:`
+
+<dl>
+<dt>Selector:</dt>
+<dd><code>mgl_distanceFrom:</code></dd>
+<dt>Format string syntax:</dt>
+<dd><code>mgl_distanceFrom(%@)</code> with an <code>MGLShape</code></dd>
+</dl>
+
+Returns the straight-line distance from the evaluated object to the given shape.
+
+This function corresponds to the
+[`distance`](https://docs.mapbox.com/mapbox-gl-js/style-spec/expressions/#distance)
+operator in the Mapbox Style Specification.
+
 ### `mgl_coalesce:`
 
 <dl>
diff --git a/platform/darwin/src/NSExpression+MGLAdditions.mm b/platform/darwin/src/NSExpression+MGLAdditions.mm
index 78a21152a..85dabfa2c 100644
--- a/platform/darwin/src/NSExpression+MGLAdditions.mm
+++ b/platform/darwin/src/NSExpression+MGLAdditions.mm
@@ -77,6 +77,7 @@ const MGLExpressionInterpolationMode MGLExpressionInterpolationModeCubicBezier =
     INSTALL_METHOD(mgl_atan:);
     INSTALL_METHOD(mgl_tan:);
     INSTALL_METHOD(mgl_log2:);
+    INSTALL_METHOD(mgl_distanceFrom:);
     INSTALL_METHOD(mgl_attributed:);
     
     // Install functions that resemble control structures, taking arbitrary
@@ -162,6 +163,15 @@ const MGLExpressionInterpolationMode MGLExpressionInterpolationModeCubicBezier =
     return @(log2(number.doubleValue));
 }
 
+/**
+ Returns a straight-line distance from the given shape to the evaluated feature.
+ */
+- (NSNumber *)mgl_distanceFrom:(id)object {
+    [NSException raise:NSInvalidArgumentException
+                format:@"Shape distance expressions lack underlying Objective-C implementations."];
+    return nil;
+}
+
 /**
  A placeholder for a method that evaluates an interpolation expression.
  */
@@ -656,6 +666,7 @@ NSArray *MGLSubexpressionsWithJSONObjects(NSArray *objects) {
             @"floor": @"floor:",
             @"ceil": @"ceiling:",
             @"^": @"raise:toPower:",
+            @"distance": @"mgl_distanceFrom:",
             @"upcase": @"uppercase:",
             @"downcase": @"lowercase:",
             @"let": @"MGL_LET",
@@ -970,6 +981,7 @@ NSArray *MGLSubexpressionsWithJSONObjects(NSArray *objects) {
             @"mgl_atan:" : @"atan",
             @"mgl_tan:" : @"tan",
             @"mgl_log2:" : @"log2",
+            @"mgl_distanceFrom:": @"distance",
             // Vararg aftermarket expressions need to be declared with an explicit and implicit first argument.
             @"MGL_LET": @"let",
             @"MGL_LET:": @"let",
diff --git a/platform/darwin/test/MGLExpressionTests.mm b/platform/darwin/test/MGLExpressionTests.mm
index cc3c37b83..9a74d64e7 100644
--- a/platform/darwin/test/MGLExpressionTests.mm
+++ b/platform/darwin/test/MGLExpressionTests.mm
@@ -667,6 +667,18 @@ using namespace std::string_literals;
     }
 }
 
+- (void)testShapeDistanceExpressionObject {
+    {
+        MGLPointAnnotation *point = [[MGLPointAnnotation alloc] init];
+        point.coordinate = CLLocationCoordinate2DMake(1, -1);
+        NSExpression *expression = [NSExpression expressionForFunction:@"mgl_distanceFrom:" arguments:@[MGLConstantExpression(point)]];
+        NSArray *jsonExpression = @[@"distance", @{@"type": @"Point", @"coordinates": @[@-1, @1]}];
+        XCTAssertEqualObjects(expression.mgl_jsonExpressionObject, jsonExpression);
+        XCTAssertThrowsSpecificNamed([expression expressionValueWithObject:nil context:nil], NSException, NSInvalidArgumentException);
+        XCTAssertEqualObjects([NSExpression expressionWithMGLJSONObject:jsonExpression], expression);
+    }
+}
+
 - (void)testStringFormattingExpressionObject {
     NSArray *arguments = @[MGLConstantExpression(@"MacDonald")];
     {
diff --git a/platform/ios/CHANGELOG.md b/platform/ios/CHANGELOG.md
index 48885958a..6a7d4d6fc 100644
--- a/platform/ios/CHANGELOG.md
+++ b/platform/ios/CHANGELOG.md
@@ -6,7 +6,7 @@ Mapbox welcomes participation and contributions from everyone. Please read [CONT
 
 ### Styles and rendering
 
-* Added the `distance` expression function for calculating the shortest distance between the evaluated feature and a GeoJSON `Point`, `MultiPoint`, `LineString`, or `MultiLineString` geometry that you specify. Use this function in expressions in style JSON or with the `MGL_FUNCTION()` syntax in an `NSExpression` format string. ([mapbox/mapbox-gl-native#16397](https://github.com/mapbox/mapbox-gl-native/pull/16397))
+* Added the `mgl_distanceFrom:` expression function for calculating the shortest distance between the evaluated feature and an `MGLPointAnnotation`, `MGLPointCollection`, `MGLPolyline`, or `MGLMultiPolyline` that you specify as part of an `NSExpression` format string. ([#295](https://github.com/mapbox/mapbox-gl-native-ios/pull/295))
 * Added the `MGLCircleStyleLayer.circleSortKey` property. ([mapbox/mapbox-gl-native#15875](https://github.com/mapbox/mapbox-gl-native/pull/15875))
 * Chinese, Japanese, and Korean characters are now set in the font specified in style JSON or by the `MGLSymbolLayer.textFontNames` property. If the named font is not installed on the device or bundled with the application, the characters are set in a fallback font listed in the `MGLIdeographicFontFamilyName` key in the Info.plist file. ([#189](https://github.com/mapbox/mapbox-gl-native-ios/pull/189))
 * The `MGLIdeographicFontFamilyName` key in the Info.plist file can now specify the fallback fonts for CJK characters by their PostScript names or display names in addition to font family names. For example, you can specify `NotoSansCJKjp-Bold` or `Noto Sans CJK JP Bold`, which ensures that the characters are set in bold. You can alternatively specify these font names in the `MGLIdeographicFontFamilyName` key of `NSUserDefaults.standardUserDefaults`. ([#189](https://github.com/mapbox/mapbox-gl-native-ios/pull/189))
@@ -28,7 +28,7 @@ Mapbox welcomes participation and contributions from everyone. Please read [CONT
 
 ### Styles and rendering
 
-* The `IN` and `CONTAINS` predicate operators can now test whether a string is a substring of another string or whether the evaluated feature (`SELF`) lies within a given `MGLShape` or `MGLFeature`. ([#183](https://github.com/mapbox/mapbox-gl-native-ios/pull/183), [#184](https://github.com/mapbox/mapbox-gl-native-ios/pull/184])
+* The `IN` and `CONTAINS` predicate operators can now test whether a string is a substring of another string or whether the evaluated feature (`SELF`) lies within a given `MGLShape` or `MGLFeature`. ([#183](https://github.com/mapbox/mapbox-gl-native-ios/pull/183), [#184](https://github.com/mapbox/mapbox-gl-native-ios/pull/184))
 * Added the `MGLLineStyleLayer.lineSortKey` and `MGLFillStyleLayer.fillSortKey` properties. ([#179](https://github.com/mapbox/mapbox-gl-native-ios/pull/179), [#16194](https://github.com/mapbox/mapbox-gl-native/pull/16194), [#16220](https://github.com/mapbox/mapbox-gl-native/pull/16220))
 * The `MGLSymbolStyleLayer.iconTextFit` property now respects the cap insets of any [nine-part stretchable image](https://developer.apple.com/documentation/uikit/uiimage#1658362) passed into the `-[MGLStyle setImage:forName:]` method. You can define the stretchable area in Xcode’s asset catalog or by calling the `-[UIImage resizableImageWithCapInsets:]` method. ([#182](https://github.com/mapbox/mapbox-gl-native-ios/pull/182))
 * Fixed an issue where an `MGLSymbolStyleLayer.lineDashPattern` value of `{1, 0}` resulted in hairline gaps. ([#16202](https://github.com/mapbox/mapbox-gl-native/pull/16202))
diff --git a/platform/ios/docs/guides/For Style Authors.md b/platform/ios/docs/guides/For Style Authors.md
index 99cd21d86..0b8dc2c98 100644
--- a/platform/ios/docs/guides/For Style Authors.md	
+++ b/platform/ios/docs/guides/For Style Authors.md	
@@ -377,6 +377,7 @@ In style specification | Method, function, or predicate type | Format string syn
 `atan`                 | `mgl_atan:` | `mgl_atan(20)`
 `ceil`                 | `ceiling:` | `ceiling(0.99999)`
 `cos`                  | `mgl_cos:` | `mgl_cos(0)`
+`distance`             | | `mgl_distanceFrom(%@)` where `%@` is an `MGLShape`
 `e`                    | | `%@` representing `NSNumber` containing `M_E`
 `floor`                | `floor:` | `floor(-0.99999)`
 `ln`                   | `ln:` | `ln(2)`
diff --git a/platform/macos/CHANGELOG.md b/platform/macos/CHANGELOG.md
index fad26a0e1..a1412af13 100644
--- a/platform/macos/CHANGELOG.md
+++ b/platform/macos/CHANGELOG.md
@@ -4,7 +4,7 @@
 
 ### Styles and rendering
 
-* Added the `distance` expression function for calculating the shortest distance between the evaluated feature and a GeoJSON `Point`, `MultiPoint`, `LineString`, or `MultiLineString` geometry that you specify. Use this function in expressions in style JSON or with the `MGL_FUNCTION()` syntax in an `NSExpression` format string. ([mapbox/mapbox-gl-native#16397](https://github.com/mapbox/mapbox-gl-native/pull/16397))
+* Added the `mgl_distanceFrom:` expression function for calculating the shortest distance between the evaluated feature and an `MGLPointAnnotation`, `MGLPointCollection`, `MGLPolyline`, or `MGLMultiPolyline` that you specify as part of an `NSExpression` format string. ([#295](https://github.com/mapbox/mapbox-gl-native-ios/pull/295))
 * Added the `MGLCircleStyleLayer.circleSortKey` property. ([mapbox/mapbox-gl-native#15875](https://github.com/mapbox/mapbox-gl-native/pull/15875))
 * Chinese, Japanese, and Korean characters are now set in the font specified in style JSON or by the `MGLSymbolLayer.textFontNames` property. If the named font is not installed on the device or bundled with the application, the characters are set in a fallback font listed in the `MGLIdeographicFontFamilyName` key in the Info.plist file. ([#189](https://github.com/mapbox/mapbox-gl-native-ios/pull/189))
 * The `MGLIdeographicFontFamilyName` key in the Info.plist file can now specify the fallback fonts for CJK characters by their PostScript names or display names in addition to font family names. For example, you can specify `NotoSansCJKjp-Bold` or `Noto Sans CJK JP Bold`, which ensures that the characters are set in bold. You can alternatively specify these font names in the `MGLIdeographicFontFamilyName` key of `NSUserDefaults.standardUserDefaults`. ([#189](https://github.com/mapbox/mapbox-gl-native-ios/pull/189))
diff --git a/platform/macos/docs/guides/For Style Authors.md b/platform/macos/docs/guides/For Style Authors.md
index c7bbc4fba..2d72fe0c6 100644
--- a/platform/macos/docs/guides/For Style Authors.md	
+++ b/platform/macos/docs/guides/For Style Authors.md	
@@ -370,6 +370,7 @@ In style specification | Method, function, or predicate type | Format string syn
 `atan`                 | `mgl_atan:` | `mgl_atan(20)`
 `ceil`                 | `ceiling:` | `ceiling(0.99999)`
 `cos`                  | `mgl_cos:` | `mgl_cos(0)`
+`distance`             | | `mgl_distanceFrom(%@)` where `%@` is an `MGLShape`
 `e`                    | | `%@` representing `NSNumber` containing `M_E`
 `floor`                | `floor:` | `floor(-0.99999)`
 `ln`                   | `ln:` | `ln(2)`