[ios, macos] Undeprecated unversioned style URL factory methods

Undeprecated the unversioned style URL factory methods in MGLStyle for consistency with the Android and Qt SDKs. Added warnings about using them with the runtime styling API.

Refactored mbgl::util::default_styles to track different versions for different styles.

7 files changed, 124 insertions, 59 deletions

diff --git a/platform/darwin/src/MGLStyle.h b/platform/darwin/src/MGLStyle.h
index ab5a20686a..49898a1863 100644
--- a/platform/darwin/src/MGLStyle.h
+++ b/platform/darwin/src/MGLStyle.h
@@ -52,15 +52,22 @@ MGL_EXPORT
 #pragma mark Accessing Default Styles
 
 /**
- Returns the URL to version 8 of the
- <a href="https://www.mapbox.com/maps/streets/">Mapbox Streets</a> style.
+ Returns the URL to the current version of the
+ <a href="https://www.mapbox.com/maps/streets/">Mapbox Streets</a> style as of
+ publication.
 
  Streets is a general-purpose style with detailed road and transit networks.
 
  `MGLMapView` and `MGLTilePyramidOfflineRegion` use Mapbox Streets when no style
  is specified explicitly.
+
+ @warning The return value may change in a future release of the SDK. If you use
+    any feature that depends on a specific aspect of a default style – for
+    instance, the minimum zoom level that includes roads – use the
+    `-streetsStyleURLWithVersion:` method instead. Such details may change
+    significantly from version to version.
  */
-+ (NSURL *)streetsStyleURL __attribute__((deprecated("Use -streetsStyleURLWithVersion:.")));
++ (NSURL *)streetsStyleURL;
 
 /**
  Returns the URL to the given version of the
@@ -71,8 +78,7 @@ MGL_EXPORT
  `MGLMapView` and `MGLTilePyramidOfflineRegion` use Mapbox Streets when no style
  is specified explicitly.
 
- @param version The style’s latest released version. As of publication, the
-    current version is `10`.
+ @param version A specific version of the style.
  */
 + (NSURL *)streetsStyleURLWithVersion:(NSInteger)version;
 
@@ -85,70 +91,102 @@ MGL_EXPORT
 + (NSURL *)emeraldStyleURL __attribute__((deprecated("Create an NSURL object with the string “mapbox://styles/mapbox/emerald-v8”.")));
 
 /**
+ Returns the URL to the current version of the
+ <a href="https://www.mapbox.com/maps/outdoors/">Mapbox Outdoors</a> style as of
+ publication.
+
+ Outdoors is a general-purpose style tailored to outdoor activities.
+
+ @warning The return value may change in a future release of the SDK. If you use
+    any feature that depends on a specific aspect of a default style – for
+    instance, the minimum zoom level that includes roads – use the
+    `-outdoorsStyleURLWithVersion:` method instead. Such details may change
+    significantly from version to version.
+ */
++ (NSURL *)outdoorsStyleURL;
+
+/**
  Returns the URL to the given version of the
  <a href="https://www.mapbox.com/maps/outdoors/">Mapbox Outdoors</a> style.
 
  Outdoors is a general-purpose style tailored to outdoor activities.
 
- @param version The style’s latest released version. As of publication, the
-    current version is `10`.
+ @param version A specific version of the style.
  */
 + (NSURL *)outdoorsStyleURLWithVersion:(NSInteger)version;
 
 /**
- Returns the URL to version 8 of the
+ Returns the URL to the current version of the
  <a href="https://www.mapbox.com/maps/light-dark/">Mapbox Light</a> style.
 
  Light is a subtle, light-colored backdrop for data visualizations.
+
+ @warning The return value may change in a future release of the SDK. If you use
+    any feature that depends on a specific aspect of a default style – for
+    instance, the minimum zoom level that includes roads – use the
+    `-lightStyleURLWithVersion:` method instead. Such details may change
+    significantly from version to version.
  */
-+ (NSURL *)lightStyleURL __attribute__((deprecated("Use -lightStyleURLWithVersion:.")));
++ (NSURL *)lightStyleURL;
 
 /**
  Returns the URL to the given version of the
- <a href="https://www.mapbox.com/maps/light-dark/">Mapbox Light</a> style.
+ <a href="https://www.mapbox.com/maps/light-dark/">Mapbox Light</a> style as of
+ publication.
 
  Light is a subtle, light-colored backdrop for data visualizations.
 
- @param version The style’s latest released version. As of publication, the
-    current version is `9`.
+ @param version A specific version of the style.
  */
 + (NSURL *)lightStyleURLWithVersion:(NSInteger)version;
 
 /**
- Returns the URL to version 8 of the
+ Returns the URL to the current version of the
  <a href="https://www.mapbox.com/maps/light-dark/">Mapbox Dark</a> style.
 
  Dark is a subtle, dark-colored backdrop for data visualizations.
+
+ @warning The return value may change in a future release of the SDK. If you use
+    any feature that depends on a specific aspect of a default style – for
+    instance, the minimum zoom level that includes roads – use the
+    `-darkStyleURLWithVersion:` method instead. Such details may change
+    significantly from version to version.
  */
-+ (NSURL *)darkStyleURL __attribute__((deprecated("Use -darkStyleURLWithVersion:.")));
++ (NSURL *)darkStyleURL;
 
 /**
  Returns the URL to the given version of the
- <a href="https://www.mapbox.com/maps/light-dark/">Mapbox Dark</a> style.
+ <a href="https://www.mapbox.com/maps/light-dark/">Mapbox Dark</a> style as of
+ publication.
 
  Dark is a subtle, dark-colored backdrop for data visualizations.
 
- @param version The style’s latest released version. As of publication, the
-    current version is `9`.
+ @param version A specific version of the style.
  */
 + (NSURL *)darkStyleURLWithVersion:(NSInteger)version;
 
 /**
- Returns the URL to version 8 of the
+ Returns the URL to the current version of the
  <a href="https://www.mapbox.com/maps/satellite/">Mapbox Satellite</a> style.
 
  Satellite is high-resolution satellite and aerial imagery.
+
+ @warning The return value may change in a future release of the SDK. If you use
+    any feature that depends on a specific aspect of a default style – for
+    instance, the raster tile sets included in the style – use the
+    `-satelliteStyleURLWithVersion:` method instead. Such details may change
+    significantly from version to version.
  */
-+ (NSURL *)satelliteStyleURL __attribute__((deprecated("Use -satelliteStyleURLWithVersion:.")));
++ (NSURL *)satelliteStyleURL;
 
 /**
  Returns the URL to the given version of the
- <a href="https://www.mapbox.com/maps/satellite/">Mapbox Satellite</a> style.
+ <a href="https://www.mapbox.com/maps/satellite/">Mapbox Satellite</a> style as
+ of publication.
 
  Satellite is high-resolution satellite and aerial imagery.
 
- @param version The style’s latest released version. As of publication, the
-    current version is `9`.
+ @param version A specific version of the style.
  */
 + (NSURL *)satelliteStyleURLWithVersion:(NSInteger)version;
 
@@ -161,7 +199,24 @@ MGL_EXPORT
  Mapbox Satellite with unobtrusive labels and translucent roads from Mapbox
  Streets.
  */
-+ (NSURL *)hybridStyleURL __attribute__((deprecated("Use -satelliteStreetsStyleURLWithVersion:.")));
++ (NSURL *)hybridStyleURL __attribute__((deprecated("Use -satelliteStreetsStyleURL.")));
+
+/**
+ Returns the URL to the current version of the
+ <a href="https://www.mapbox.com/maps/satellite/">Mapbox Satellite Streets</a>
+ style as of publication.
+
+ Satellite Streets combines the high-resolution satellite and aerial imagery of
+ Mapbox Satellite with unobtrusive labels and translucent roads from Mapbox
+ Streets.
+
+ @warning The return value may change in a future release of the SDK. If you use
+    any feature that depends on a specific aspect of a default style – for
+    instance, the minimum zoom level that includes roads – use the
+    `-satelliteStreetsStyleURLWithVersion:` method instead. Such details may
+    change significantly from version to version.
+ */
++ (NSURL *)satelliteStreetsStyleURL;
 
 /**
  Returns the URL to the given version of the
@@ -172,8 +227,7 @@ MGL_EXPORT
  Mapbox Satellite with unobtrusive labels and translucent roads from Mapbox
  Streets.
 
- @param version The style’s latest released version. As of publication, the
-    current version is `10`.
+ @param version A specific version of the style.
  */
 + (NSURL *)satelliteStreetsStyleURLWithVersion:(NSInteger)version;
 
diff --git a/platform/darwin/src/MGLStyle.mm b/platform/darwin/src/MGLStyle.mm
index 81b6446e7f..ce9e55bb99 100644
--- a/platform/darwin/src/MGLStyle.mm
+++ b/platform/darwin/src/MGLStyle.mm
@@ -58,8 +58,6 @@
 
 #pragma mark Default style URLs
 
-static_assert(mbgl::util::default_styles::currentVersion == MGLStyleDefaultVersion, "mbgl::util::default_styles::currentVersion and MGLStyleDefaultVersion disagree.");
-
 /// @param name The style’s marketing name, written in lower camelCase.
 /// @param fileName The last path component in the style’s URL, excluding the version suffix.
 #define MGL_DEFINE_STYLE(name, fileName) \
@@ -67,17 +65,13 @@ static_assert(mbgl::util::default_styles::currentVersion == MGLStyleDefaultVersi
     + (NSURL *)name##StyleURL { \
         static dispatch_once_t onceToken; \
         dispatch_once(&onceToken, ^{ \
-            MGLStyleURL_##name = [self name##StyleURLWithVersion:8]; \
+            MGLStyleURL_##name = [self name##StyleURLWithVersion:mbgl::util::default_styles::name.currentVersion]; \
         }); \
         return MGLStyleURL_##name; \
     } \
     \
     + (NSURL *)name##StyleURL##WithVersion:(NSInteger)version { \
-        if (mbgl::util::default_styles::currentVersion == version) { \
-            return [NSURL URLWithString:@(mbgl::util::default_styles::name.url)]; \
-        } else { \
-            return [NSURL URLWithString:[@"mapbox://styles/mapbox/" #fileName "-v" stringByAppendingFormat:@"%li", (long)version]]; \
-        } \
+        return [NSURL URLWithString:[@"mapbox://styles/mapbox/" #fileName "-v" stringByAppendingFormat:@"%li", (long)version]]; \
     }
 
 MGL_DEFINE_STYLE(streets, streets)
diff --git a/platform/darwin/test/MGLStyleTests.mm b/platform/darwin/test/MGLStyleTests.mm
index 8681bddc46..a2ad1cbb3f 100644
--- a/platform/darwin/test/MGLStyleTests.mm
+++ b/platform/darwin/test/MGLStyleTests.mm
@@ -55,13 +55,19 @@
 }
 
 - (void)testUnversionedStyleURLs {
+    XCTAssertEqual(mbgl::util::default_styles::streets.currentVersion, MGLStyleDefaultVersion,
+                   "mbgl::util::default_styles::streets.currentVersion and MGLStyleDefaultVersion disagree.");
+    
+    XCTAssertEqualObjects([MGLStyle streetsStyleURL].absoluteString, @(mbgl::util::default_styles::streets.url));
+    XCTAssertEqualObjects([MGLStyle outdoorsStyleURL].absoluteString, @(mbgl::util::default_styles::outdoors.url));
+    XCTAssertEqualObjects([MGLStyle lightStyleURL].absoluteString, @(mbgl::util::default_styles::light.url));
+    XCTAssertEqualObjects([MGLStyle darkStyleURL].absoluteString, @(mbgl::util::default_styles::dark.url));
+    XCTAssertEqualObjects([MGLStyle satelliteStyleURL].absoluteString, @(mbgl::util::default_styles::satellite.url));
+    XCTAssertEqualObjects([MGLStyle satelliteStreetsStyleURL].absoluteString, @(mbgl::util::default_styles::satelliteStreets.url));
+    
 #pragma clang diagnostic push
 #pragma clang diagnostic ignored "-Wdeprecated-declarations"
-    XCTAssertEqualObjects([MGLStyle streetsStyleURL].absoluteString, @"mapbox://styles/mapbox/streets-v8");
     XCTAssertEqualObjects([MGLStyle emeraldStyleURL].absoluteString, @"mapbox://styles/mapbox/emerald-v8");
-    XCTAssertEqualObjects([MGLStyle lightStyleURL].absoluteString, @"mapbox://styles/mapbox/light-v8");
-    XCTAssertEqualObjects([MGLStyle darkStyleURL].absoluteString, @"mapbox://styles/mapbox/dark-v8");
-    XCTAssertEqualObjects([MGLStyle satelliteStyleURL].absoluteString, @"mapbox://styles/mapbox/satellite-v8");
     XCTAssertEqualObjects([MGLStyle hybridStyleURL].absoluteString, @"mapbox://styles/mapbox/satellite-hybrid-v8");
 #pragma clang diagnostic pop
 }
@@ -69,18 +75,30 @@
 - (void)testVersionedStyleURLs {
     // Test that all the default styles have publicly-declared MGLStyle class
     // methods and that the URLs all have the right values.
-    XCTAssertEqualObjects([MGLStyle streetsStyleURLWithVersion:MGLStyleDefaultVersion].absoluteString, @(mbgl::util::default_styles::streets.url));
-    XCTAssertEqualObjects([MGLStyle streetsStyleURLWithVersion:99].absoluteString, @"mapbox://styles/mapbox/streets-v99");
-    XCTAssertEqualObjects([MGLStyle outdoorsStyleURLWithVersion:MGLStyleDefaultVersion].absoluteString, @(mbgl::util::default_styles::outdoors.url));
-    XCTAssertEqualObjects([MGLStyle outdoorsStyleURLWithVersion:99].absoluteString, @"mapbox://styles/mapbox/outdoors-v99");
-    XCTAssertEqualObjects([MGLStyle lightStyleURLWithVersion:MGLStyleDefaultVersion].absoluteString, @(mbgl::util::default_styles::light.url));
-    XCTAssertEqualObjects([MGLStyle lightStyleURLWithVersion:99].absoluteString, @"mapbox://styles/mapbox/light-v99");
-    XCTAssertEqualObjects([MGLStyle darkStyleURLWithVersion:MGLStyleDefaultVersion].absoluteString, @(mbgl::util::default_styles::dark.url));
-    XCTAssertEqualObjects([MGLStyle darkStyleURLWithVersion:99].absoluteString, @"mapbox://styles/mapbox/dark-v99");
-    XCTAssertEqualObjects([MGLStyle satelliteStyleURLWithVersion:MGLStyleDefaultVersion].absoluteString, @(mbgl::util::default_styles::satellite.url));
-    XCTAssertEqualObjects([MGLStyle satelliteStyleURLWithVersion:99].absoluteString, @"mapbox://styles/mapbox/satellite-v99");
-    XCTAssertEqualObjects([MGLStyle satelliteStreetsStyleURLWithVersion:MGLStyleDefaultVersion].absoluteString, @(mbgl::util::default_styles::satelliteStreets.url));
-    XCTAssertEqualObjects([MGLStyle satelliteStreetsStyleURLWithVersion:99].absoluteString, @"mapbox://styles/mapbox/satellite-streets-v99");
+    XCTAssertEqualObjects([MGLStyle streetsStyleURLWithVersion:mbgl::util::default_styles::streets.currentVersion].absoluteString,
+                          @(mbgl::util::default_styles::streets.url));
+    XCTAssertEqualObjects([MGLStyle streetsStyleURLWithVersion:99].absoluteString,
+                          @"mapbox://styles/mapbox/streets-v99");
+    XCTAssertEqualObjects([MGLStyle outdoorsStyleURLWithVersion:mbgl::util::default_styles::outdoors.currentVersion].absoluteString,
+                          @(mbgl::util::default_styles::outdoors.url));
+    XCTAssertEqualObjects([MGLStyle outdoorsStyleURLWithVersion:99].absoluteString,
+                          @"mapbox://styles/mapbox/outdoors-v99");
+    XCTAssertEqualObjects([MGLStyle lightStyleURLWithVersion:mbgl::util::default_styles::light.currentVersion].absoluteString,
+                          @(mbgl::util::default_styles::light.url));
+    XCTAssertEqualObjects([MGLStyle lightStyleURLWithVersion:99].absoluteString,
+                          @"mapbox://styles/mapbox/light-v99");
+    XCTAssertEqualObjects([MGLStyle darkStyleURLWithVersion:mbgl::util::default_styles::dark.currentVersion].absoluteString,
+                          @(mbgl::util::default_styles::dark.url));
+    XCTAssertEqualObjects([MGLStyle darkStyleURLWithVersion:99].absoluteString,
+                          @"mapbox://styles/mapbox/dark-v99");
+    XCTAssertEqualObjects([MGLStyle satelliteStyleURLWithVersion:mbgl::util::default_styles::satellite.currentVersion].absoluteString,
+                          @(mbgl::util::default_styles::satellite.url));
+    XCTAssertEqualObjects([MGLStyle satelliteStyleURLWithVersion:99].absoluteString,
+                          @"mapbox://styles/mapbox/satellite-v99");
+    XCTAssertEqualObjects([MGLStyle satelliteStreetsStyleURLWithVersion:mbgl::util::default_styles::satelliteStreets.currentVersion].absoluteString,
+                          @(mbgl::util::default_styles::satelliteStreets.url));
+    XCTAssertEqualObjects([MGLStyle satelliteStreetsStyleURLWithVersion:99].absoluteString,
+                          @"mapbox://styles/mapbox/satellite-streets-v99");
 
     static_assert(6 == mbgl::util::default_styles::numOrderedStyles,
                   "MGLStyleTests isn’t testing all the styles in mbgl::util::default_styles.");
diff --git a/platform/default/mbgl/util/default_styles.cpp b/platform/default/mbgl/util/default_styles.cpp
index 5457d0f0a2..e051817ada 100644
--- a/platform/default/mbgl/util/default_styles.cpp
+++ b/platform/default/mbgl/util/default_styles.cpp
@@ -4,12 +4,12 @@ namespace mbgl {
 namespace util {
 namespace default_styles {
 
-const DefaultStyle streets          = { "mapbox://styles/mapbox/streets-v10",           "Streets" };
-const DefaultStyle outdoors         = { "mapbox://styles/mapbox/outdoors-v10",          "Outdoors" };
-const DefaultStyle light            = { "mapbox://styles/mapbox/light-v9",              "Light" };
-const DefaultStyle dark             = { "mapbox://styles/mapbox/dark-v9",               "Dark" };
-const DefaultStyle satellite        = { "mapbox://styles/mapbox/satellite-v9",          "Satellite" };
-const DefaultStyle satelliteStreets = { "mapbox://styles/mapbox/satellite-streets-v10", "Satellite Streets" };
+const DefaultStyle streets          = { "mapbox://styles/mapbox/streets-v10",           "Streets",           10 };
+const DefaultStyle outdoors         = { "mapbox://styles/mapbox/outdoors-v10",          "Outdoors",          10 };
+const DefaultStyle light            = { "mapbox://styles/mapbox/light-v9",              "Light",              9 };
+const DefaultStyle dark             = { "mapbox://styles/mapbox/dark-v9",               "Dark",               9 };
+const DefaultStyle satellite        = { "mapbox://styles/mapbox/satellite-v9",          "Satellite",          9 };
+const DefaultStyle satelliteStreets = { "mapbox://styles/mapbox/satellite-streets-v10", "Satellite Streets", 10 };
 
 } // namespace default_styles
 } // end namespace util
diff --git a/platform/default/mbgl/util/default_styles.hpp b/platform/default/mbgl/util/default_styles.hpp
index 32944394aa..5e0d083d82 100644
--- a/platform/default/mbgl/util/default_styles.hpp
+++ b/platform/default/mbgl/util/default_styles.hpp
@@ -10,6 +10,7 @@ namespace default_styles {
 struct DefaultStyle {
     const char* url;
     const char* name;
+    const unsigned currentVersion;
 };
 
 extern const DefaultStyle streets;
@@ -24,8 +25,6 @@ const DefaultStyle orderedStyles[] = {
 };
 const size_t numOrderedStyles = sizeof(orderedStyles) / sizeof(DefaultStyle);
 
-static const unsigned currentVersion = 10;
-
 } // end namespace default_styles
 } // end namespace util
 } // end namespace mbgl
diff --git a/platform/ios/CHANGELOG.md b/platform/ios/CHANGELOG.md
index e877613f1c..b975030b1b 100644
--- a/platform/ios/CHANGELOG.md
+++ b/platform/ios/CHANGELOG.md
@@ -7,7 +7,7 @@ Mapbox welcomes participation and contributions from everyone. Please read [CONT
 ### Styles
 
 * Added support for 3D extrusion of buildings and other polygonal features via the `MGLFillExtrusionStyleLayer` class and the `fill-extrusion` layer type in style JSON. ([#8431](https://github.com/mapbox/mapbox-gl-native/pull/8431))
-* MGLMapView and MGLTilePyramidOfflineRegion now default to version 10 of the Mapbox Streets style. Similarly, several style URL class methods of MGLStyle return URLs to version 10 styles. ([#6301](https://github.com/mapbox/mapbox-gl-native/pull/6301))
+* MGLMapView and MGLTilePyramidOfflineRegion now default to version 10 of the Mapbox Streets style. Similarly, several style URL class methods of MGLStyle return URLs to version 10 styles. Unversioned variations of these methods are no longer deprecated. `MGLStyleDefaultVersion` should no longer be used with any style other than Streets. ([#6301](https://github.com/mapbox/mapbox-gl-native/pull/6301))
 * MGLSymbolStyleLayer’s `iconImageName`, `iconScale`, `textFontSize`, `textOffset`, and `textRotation` properties can now be set to a source or composite function. ([#8544](https://github.com/mapbox/mapbox-gl-native/pull/8544), [#8590](https://github.com/mapbox/mapbox-gl-native/pull/8590), [#8592](https://github.com/mapbox/mapbox-gl-native/pull/8592), [#8593](https://github.com/mapbox/mapbox-gl-native/pull/8593))
 * Fixed an issue where setting the `MGLVectorStyleLayer.predicate` property failed to take effect if the relevant source was not in use by a visible layer at the time. ([#8653](https://github.com/mapbox/mapbox-gl-native/pull/8653))
 * Fixed an issue causing a composite function’s highest zoom level stop to be misinterpreted. ([#8613](https://github.com/mapbox/mapbox-gl-native/pull/8613), [#8790](https://github.com/mapbox/mapbox-gl-native/pull/8790))
diff --git a/platform/macos/CHANGELOG.md b/platform/macos/CHANGELOG.md
index 31315541a8..298cc8ecfc 100644
--- a/platform/macos/CHANGELOG.md
+++ b/platform/macos/CHANGELOG.md
@@ -5,7 +5,7 @@
 ### Styles
 
 * Added support for 3D extrusion of buildings and other polygonal features via the `MGLFillExtrusionStyleLayer` class and the `fill-extrusion` layer type in style JSON. ([#8431](https://github.com/mapbox/mapbox-gl-native/pull/8431))
-* MGLMapView and MGLTilePyramidOfflineRegion now default to version 10 of the Mapbox Streets style. Similarly, several style URL class methods of MGLStyle return URLs to version 10 styles. ([#6301](https://github.com/mapbox/mapbox-gl-native/pull/6301))
+* MGLMapView and MGLTilePyramidOfflineRegion now default to version 10 of the Mapbox Streets style. Similarly, several style URL class methods of MGLStyle return URLs to version 10 styles. Unversioned variations of these methods are no longer deprecated. `MGLStyleDefaultVersion` should no longer be used with any style other than Streets. ([#6301](https://github.com/mapbox/mapbox-gl-native/pull/6301))
 * MGLSymbolStyleLayer’s `iconImageName`, `iconScale`, `textFontSize`, `textOffset`, and `textRotation` properties can now be set to a source or composite function. ([#8544](https://github.com/mapbox/mapbox-gl-native/pull/8544), [#8590](https://github.com/mapbox/mapbox-gl-native/pull/8590), [#8592](https://github.com/mapbox/mapbox-gl-native/pull/8592), [#8593](https://github.com/mapbox/mapbox-gl-native/pull/8593))
 * Fixed an issue where setting the `MGLVectorStyleLayer.predicate` property failed to take effect if the relevant source was not in use by a visible layer at the time. ([#8653](https://github.com/mapbox/mapbox-gl-native/pull/8653))
 * Fixed an issue causing a composite function’s highest zoom level stop to be misinterpreted. ([#8613](https://github.com/mapbox/mapbox-gl-native/pull/8613), [#8790](https://github.com/mapbox/mapbox-gl-native/pull/8790))