[ios, macos] Add convenience initializers to shape source (#7665)

This adds two new convenience initializers to MGLShapeSource:

-initWithIdentifier:features:options: takes an array of shape objects
that conform to MGLFeature, inserts them in a shape collection feature
and creates a source with that shape. -initWithIdentifier:shapes:options
does the same but with concrete MGLShape objects that get added to
a shape collection.

Throw an exception if an shape source is created with the features
initializer but is sent an array of features that contains something
that is not actually an object that conforms to the feature protocol.

Updates to geojson data guide

Qualify APIs that take arrays of shapes that are features

1 files changed, 39 insertions, 0 deletions

diff --git a/platform/darwin/test/MGLShapeSourceTests.mm b/platform/darwin/test/MGLShapeSourceTests.mm
index 2662d4b6f0..cf32b5c821 100644
--- a/platform/darwin/test/MGLShapeSourceTests.mm
+++ b/platform/darwin/test/MGLShapeSourceTests.mm
@@ -278,4 +278,43 @@
     XCTAssert(shape.shapes.count == 6, @"Shape collection should contain 6 shapes");
 }
 
+- (void)testMGLShapeSourceWithFeaturesConvenienceInitializer {
+    CLLocationCoordinate2D coordinates[] = {
+        CLLocationCoordinate2DMake(100.0, 0.0),
+        CLLocationCoordinate2DMake(101.0, 0.0),
+        CLLocationCoordinate2DMake(101.0, 1.0),
+        CLLocationCoordinate2DMake(100.0, 1.0),
+        CLLocationCoordinate2DMake(100.0, 0.0)};
+
+    MGLPolygonFeature *polygonFeature = [MGLPolygonFeature polygonWithCoordinates:coordinates count:sizeof(coordinates)/sizeof(coordinates[0]) interiorPolygons:nil];
+
+    MGLShapeSource *source = [[MGLShapeSource alloc] initWithIdentifier:@"source-id" features:@[polygonFeature] options:nil];
+    MGLShapeCollectionFeature *shape = (MGLShapeCollectionFeature *)source.shape;
+
+    XCTAssertTrue([shape isKindOfClass:[MGLShapeCollectionFeature class]]);
+    XCTAssertEqual(shape.shapes.count, 1, @"Shape collection should contain 1 shape");
+
+    // when a shape is included in the features array
+    MGLPolygon *polygon = [MGLPolygon polygonWithCoordinates:coordinates count:sizeof(coordinates)/sizeof(coordinates[0]) interiorPolygons:nil];
+
+    XCTAssertThrowsSpecificNamed([[MGLShapeSource alloc] initWithIdentifier:@"source-id-invalid" features:@[polygon] options:nil], NSException, NSInvalidArgumentException, @"Shape source should raise an exception if a shape is sent to the features initializer");
+}
+
+- (void)testMGLShapeSourceWithShapesConvenienceInitializer {
+    CLLocationCoordinate2D coordinates[] = {
+        CLLocationCoordinate2DMake(100.0, 0.0),
+        CLLocationCoordinate2DMake(101.0, 0.0),
+        CLLocationCoordinate2DMake(101.0, 1.0),
+        CLLocationCoordinate2DMake(100.0, 1.0),
+        CLLocationCoordinate2DMake(100.0, 0.0)};
+
+    MGLPolygon *polygon = [MGLPolygon polygonWithCoordinates:coordinates count:sizeof(coordinates)/sizeof(coordinates[0]) interiorPolygons:nil];
+
+    MGLShapeSource *source = [[MGLShapeSource alloc] initWithIdentifier:@"source-id" shapes:@[polygon] options:nil];
+    MGLShapeCollectionFeature *shape = (MGLShapeCollectionFeature *)source.shape;
+
+    XCTAssertTrue([shape isKindOfClass:[MGLShapeCollection class]]);
+    XCTAssertEqual(shape.shapes.count, 1, @"Shape collection should contain 1 shape");
+}
+
 @end