diff options
Diffstat (limited to 'platform/darwin/docs')
17 files changed, 995 insertions, 390 deletions
diff --git a/platform/darwin/docs/guides/For Style Authors.md.ejs b/platform/darwin/docs/guides/For Style Authors.md.ejs index 7648d6f7ac..2ae6602224 100644 --- a/platform/darwin/docs/guides/For Style Authors.md.ejs +++ b/platform/darwin/docs/guides/For Style Authors.md.ejs @@ -178,21 +178,22 @@ source object is a member of one of the following subclasses of `MGLSource`: In style JSON | In the SDK --------------|----------- +`vector` | `MGLVectorTileSource` +`raster` | `MGLRasterTileSource` +`raster-dem` | `MGLRasterDEMSource` `geojson` | `MGLShapeSource` -`raster` | `MGLRasterSource` -`vector` | `MGLVectorSource` `image` | `MGLImageSource` `canvas` and `video` sources are not supported. ### Tile sources -Raster and vector sources may be defined in TileJSON configuration files. This -SDK supports the properties defined in the style specification, which are a +Raster and vector tile sources may be defined in TileJSON configuration files. +This SDK supports the properties defined in the style specification, which are a subset of the keys defined in version 2.1.0 of the [TileJSON](https://github.com/mapbox/tilejson-spec/tree/master/2.1.0) specification. As an alternative to authoring a custom TileJSON file, you may -supply various tile source options when creating a raster or vector source. +supply various tile source options when creating a raster or vector tile source. These options are detailed in the `MGLTileSourceOption` documentation: In style JSON | In TileJSON | In the SDK @@ -321,6 +322,11 @@ iOS. <% } -%> ### Expression operators +Many expression operators defined in the style specification have corresponding +symbols to be used with the `+[NSExpression expressionWithFormat:]`, +`+[NSExpression expressionForFunction:arguments:]`, or +`+[NSExpression expressionForFunction:selectorName:arguments:]` method: + In style specification | Method, function, or predicate type | Format string syntax -----------------------|-------------------------------------|--------------------- `array` | | @@ -330,15 +336,15 @@ In style specification | Method, function, or predicate type | Format string syn `string` | | `to-boolean` | `boolValue` | `to-color` | | -`to-number` | `mgl_numberWithFallbackValues:` | -`to-string` | `stringValue` | +`to-number` | `mgl_numberWithFallbackValues:` | `CAST(zipCode, 'NSNumber')` +`to-string` | `stringValue` | `CAST(ele, 'NSString')` `typeof` | | -`geometry-type` | | -`id` | | -`properties` | | -`at` | | +`geometry-type` | `NSExpression.geometryTypeVariableExpression` | `$geometryType` +`id` | `NSExpression.featureIdentifierVariableExpression` | `$featureIdentifier` +`properties` | `NSExpression.featureAttributesVariableExpression` | `$featureAttributes` +`at` | `objectFrom:withIndex:` | `array[n]` `get` | `+[NSExpression expressionForKeyPath:]` | Key path -`has` | | +`has` | `mgl_does:have:` | `mgl_does:have:(self, 'key')` `length` | `count:` | `count({1, 2, 2, 3, 4, 7, 9})` `!` | `NSNotPredicateType` | `NOT (p0 OR … OR pn)` `!=` | `NSNotEqualToPredicateOperatorType` | `key != value` @@ -349,20 +355,20 @@ 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:]` | `TERNARY(condition, trueExpression, falseExpression)` -`coalesce` | | -`match` | | -`interpolate` | `mgl_interpolateWithCurveType:parameters:stops:` | -`step` | `mgl_stepWithMinimum:stops:` | -`let` | `mgl_expressionWithContext:` | +`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` 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` | `stringByAppendingString:` | +`concat` | `mgl_join:` or `-[NSExpression mgl_expressionByAppendingExpression:]` | `mgl_join({'Old', ' ', 'MacDonald'})` `downcase` | `lowercase:` | `lowercase('DOWNTOWN')` `upcase` | `uppercase:` | `uppercase('Elysian Fields')` <% if (macOS) { -%> `rgb` | `+[NSColor colorWithCalibratedRed:green:blue:alpha:]` | `rgba` | `+[NSColor colorWithCalibratedRed:green:blue:alpha:]` | -<% } else { %> +<% } else { -%> `rgb` | `+[UIColor colorWithRed:green:blue:alpha:]` | `rgba` | `+[UIColor colorWithRed:green:blue:alpha:]` | <% } -%> @@ -373,27 +379,34 @@ In style specification | Method, function, or predicate type | Format string syn `%` | `modulus:by:` | `^` | `raise:toPower:` | `2 ** 2` `+` | `add:to:` | `1 + 2` -`acos` | | -`asin` | | -`atan` | | -`cos` | | +`abs` | `abs:` | `abs(-1)` +`acos` | `mgl_acos:` | `mgl_acos(1)` +`asin` | `mgl_asin:` | `mgl_asin(0)` +`atan` | `mgl_atan:` | `mgl_atan(20)` +`ceil` | `ceiling:` | `ceiling(0.99999)` +`cos` | `mgl_cos:` | `mgl_cos(0)` `e` | | `%@` representing `NSNumber` containing `M_E` +`floor` | `floor:` | `floor(-0.99999)` `ln` | `ln:` | `ln(2)` `ln2` | | `%@` representing `NSNumber` containing `M_LN2` `log10` | `log:` | `log(1)` -`log2` | | +`log2` | `mgl_log2:` | `mgl_log2(1024)` `max` | `max:` | `max({1, 2, 2, 3, 4, 7, 9})` `min` | `min:` | `min({1, 2, 2, 3, 4, 7, 9})` `pi` | | `%@` representing `NSNumber` containing `M_PI` -`sin` | | +`round` | `mgl_round:` | `mgl_round(1.5)` +`sin` | `mgl_sin:` | `mgl_sin(0)` `sqrt` | `sqrt:` | `sqrt(2)` -`tan` | | -`zoom` | | `$zoom` -`heatmap-density` | | `$heatmapDensity` +`tan` | `mgl_tan:` | `mgl_tan(0)` +`zoom` | `NSExpression.zoomLevelVariableExpression` | `$zoom` +`heatmap-density` | `NSExpression.heatmapDensityVariableExpression` | `$heatmapDensity` + +For operators that have no corresponding `NSExpression` symbol, use the +`MGL_FUNCTION()` format string syntax. ## Filtering sources -You can filter a shape or vector source by setting the +You can filter a shape or vector tile source by setting the `MGLVectorStyleLayer.predicate` property to an `NSPredicate` object. Below is a table of style JSON operators and the corresponding operators used in the predicate format string: diff --git a/platform/darwin/docs/guides/Migrating to Expressions.md.ejs b/platform/darwin/docs/guides/Migrating to Expressions.md.ejs new file mode 100644 index 0000000000..addbf6940e --- /dev/null +++ b/platform/darwin/docs/guides/Migrating to Expressions.md.ejs @@ -0,0 +1,212 @@ +<% + const os = locals.os; + const iOS = os === 'iOS'; + const macOS = os === 'macOS'; + const cocoaPrefix = iOS ? 'UI' : 'NS'; + const guide = 'MigratingToExpressions'; +-%> +<!-- + This file is generated. + Edit platform/darwin/scripts/generate-style-code.js, then run `make darwin-style-code`. +--> + +# Migrating from Style Functions to Expressions + +[Runtime Styling](runtime-styling.html) enables you to modify every aspect of the map’s appearance dynamically as a user interacts with your application. Developers can specify in advance how a layout or paint attribute will vary as the zoom level changes or how the appearance of individual features vary based on metadata provided by a content source. + +With Mapbox Maps SDK for <%- iOS ? 'iOS v4.0.0' : 'macOS v0.7.0' %>, style functions have been replaced with expressions. These provide even more tools for developers who want to style their maps dynamically. This guide outlines some tips for migrating from style functions to expressions, and offers an overview of some things that developers can do with expressions. + +An expression is represented at runtime by the `NSExpression` class. Expressions can be used to style paint and layout properties based on zoom level, data attributes, or a combination of the two. + +A constant expression can also be assigned to a style property. For example, the opacity of a fill style layer can be set to a constant value between 0 and 1. + +The documentation for each individual style layer property notes which non-constant expressions are enabled for that property. Style functions supported four interpolation modes: exponential, interval, categorical, and identity. + +This guide uses earthquake data from the [U.S. Geological Survey](https://earthquake.usgs.gov/earthquakes/feed/v1.0/geojson.php). Under each interpolation mode, the style function implementation will be shown, followed by the current syntax. + +For more information about how to work with GeoJSON data in our <%- os %> SDK, please see our [working with GeoJSON data](working-with-geojson-data.html) guide. To learn more about supported expressions, see our ["Predicates and Expressions"](predicates-and-expressions.html) guide. The "Predicates and Expressions" guide also outlines Mapbox custom functions that can be used to dynamically style a map. + +## Stops +Stops are dictionary keys that are associated with layer attribute values. Constant values no longer need to be wrapped as style values when they are values in a stops dictionary. + + +Style function syntax: + +```swift +let stops = [ + 0: MGLStyleValue<UIColor>(rawValue: .yellow), + 2.5: MGLStyleValue(rawValue: .orange), + 5: MGLStyleValue(rawValue: .red), + 7.5: MGLStyleValue(rawValue: .blue), + 10: MGLStyleValue(rawValue: .white), +] +``` + +Current syntax: +<%- guideExample(guide, 'Stops', os) %> + + +## Interpolation mode + +Style functions supported four interpolation modes: exponential/linear, interval, categorical, and identity. For more information about supported custom expressions, please see the "Predicates and Expressions" guide. + +### Linear + +`+[NSExpression(MGLAdditions) mgl_expressionForInterpolatingExpression:withCurveType:parameters:stops:]` takes the interpolation type as a parameter. If you previously used the default interpolation base, use the curve type `MGLExpressionInterpolationMode.linear`. See the [`mgl_interpolate:withCurveType:parameters:stops:`](predicates-and-expressions.html#code-mgl_interpolate-withcurvetype-parameters-stops-code) documentation for more details. + +The stops dictionary below, shows colors that continuously shift from yellow to orange to red to blue to white based on the attribute value. + +Style function syntax: + +```swift +let url = URL(string: "https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_week.geojson")! +let symbolSource = MGLSource(identifier: "source") +let symbolLayer = MGLSymbolStyleLayer(identifier: "place-city-sm", source: symbolSource) + +let source = MGLShapeSource(identifier: "earthquakes", url: url, options: nil) +mapView.style?.addSource(source) + +let stops = [ + 0: MGLStyleValue<UIColor>(rawValue: .yellow), + 2.5: MGLStyleValue(rawValue: .orange), + 5: MGLStyleValue(rawValue: .red), + 7.5: MGLStyleValue(rawValue: .blue), + 10: MGLStyleValue(rawValue: .white), +] + +let layer = MGLCircleStyleLayer(identifier: "circles", source: source) +layer.circleColor = MGLStyleValue(interpolationMode: .exponential, + sourceStops: stops, + attributeName: "mag", + options: [.defaultValue: MGLStyleValue<UIColor>(rawValue: .green)]) +layer.circleRadius = MGLStyleValue(rawValue: 10) +mapView.style?.insertLayer(layer, below: symbolLayer) +``` + +Current syntax: + +<%- guideExample(guide, 'Linear', os) %> + +### Exponential + +If you previously used an interpolation base greater than `0` (other than `1`), you can use `MGLExpressionInterpolationMode.exponential` as the curve type for `+[NSExpression(MGLAdditions) mgl_expressionForInterpolatingExpression:withCurveType:parameters:stops:]` or `'exponential'` as the curve type for [`mgl_interpolate:withCurveType:parameters:stops:`](predicates-and-expressions.html#code-mgl_interpolate-withcurvetype-parameters-stops-code). The `parameters` argument takes that interpolation base. This interpolates between values exponentially, creating an accelerated ramp effect. + +Here’s a visualization from Mapbox Studio (see [Working with Mapbox Studio](working-with-mapbox-studio.html)) comparing interpolation base values of `1.5` and `0.5` based on zoom. In order to convert camera style functions, use `$zoomLevel` or `MGL_FUNCTION('zoomLevel')` as the attribute key. + +<img src="img/data-driven-styling/exponential-function.png" height=344/> +<img src="img/data-driven-styling/exponential-function-1.png" height=344/> + +The example below increases a layer’s `circleRadius` exponentially based on a map’s zoom level. The interpolation base is `1.5`. + +Style function syntax: + +```swift +let stops = [ + 12: MGLStyleValue<NSNumber>(rawValue: 0.5), + 14: MGLStyleValue(rawValue: 2), + 18: MGLStyleValue(rawValue: 18), +] + +layer.circleRadius = MGLStyleValue(interpolationMode: .exponential, + cameraStops: stops, + options: [.interpolationBase: 1.5]) +``` + +Current syntax: + +<%- guideExample(guide, 'Exponential', os) %> + +### Interval + +Steps, or intervals, create a range using the keys from the stops dictionary. The range is from the given key to just less than the next key. The attribute values that fall into that range are then styled using the layout or paint value assigned to that key. You can use the `+[NSExpression(MGLAdditions) mgl_expressionForSteppingExpression:fromExpression:stops:]` method or the custom function [`mgl_step:from:stops:`](predicates-and-expressions.html#code-mgl_step-from-stops-code) for cases where you previously used interval interpolation mode. The first parameter takes the feature attribute name and the second parameter (`from:`) optionally takes the default or fallback value for that function. The final parameter takes a stops dictionary as an argument. + +When we use the stops dictionary given above with an `'mgl_step:from:stops:'`, we create ranges where earthquakes with a magnitude of 0 to just less than 2.5 would be yellow, 2.5 to just less than 5 would be orange, and so on. + +Style function syntax: + +```swift +let stops = [ + 0: MGLStyleValue<UIColor>(rawValue: .yellow), + 2.5: MGLStyleValue(rawValue: .orange), + 5: MGLStyleValue(rawValue: .red), + 7.5: MGLStyleValue(rawValue: .blue), + 10: MGLStyleValue(rawValue: .white), +] + +layer.circleColor = MGLStyleValue(interpolationMode: .interval, + sourceStops: stops, + attributeName: "mag", + options: [.defaultValue: MGLStyleValue<UIColor>(rawValue: .green)]) +```` + +Current syntax: + +<%- guideExample(guide, 'Interval', os) %> + +### Categorical + +Categorical interpolation mode took a stops dictionary. If the value for a specified feature attribute name matched one in that stops dictionary, the style value for that attribute value would be used. Categorical style functions can now be replaced with `MGL_MATCH`. + +`MGL_MATCH` takes an initial condition, which in this case is an attribute key. This is followed by possible matches for that key and the value to assign to the layer property if there is a match. The final argument can be a default style value that is to be used if none of the specified values match. + +There are three main types of events in the USGS dataset: earthquakes, explosions, and quarry blasts. In this case, the color of the circle layer will be determined by the type of event, with a default value of blue to catch any events that do not fall into any of those categories. + +Style function syntax: + +```swift +let categoricalStops = [ + "earthquake": MGLStyleValue<UIColor>(rawValue: .orange), + "explosion": MGLStyleValue(rawValue: .red), + "quarry blast": MGLStyleValue(rawValue: .yellow), +] + +layer.circleColor = MGLStyleValue(interpolationMode: .categorical, + sourceStops: categoricalStops, + attributeName: "type", + options: [.defaultValue: MGLStyleValue<UIColor>(rawValue: .blue)]) +``` + +Current syntax: +<%- guideExample(guide, 'Categorical', os) %> + +If your use case does not require a default value, you can either apply a predicate to your layer prior to styling it, or use the format string `"valueForKeyPath:"`. + +### Identity + +Identity interpolation mode used the attribute’s value as the style layer property value. In this example, you might set the `circleRadius` to the earthquake’s magnitude. In order to use a feature attribute value to style a layer property, set the property value to `[NSExpression expressionForKeyPath:]`, which take the feature attribute name as an argument. + +Style function syntax: + +```swift +layer.circleRadius = MGLStyleValue(interpolationMode: .identity, + sourceStops: nil, + attributeName: "mag", + options: [.defaultValue: MGLStyleValue<NSNumber>(rawValue: 0)]) +``` + +Current syntax: +<%- guideExample(guide, 'Identity', os) %> + + + +Some built-in functions can be applied to attribute values to style layer property values. To set the circle radius to three times the earthquake’s magnitude, create a `multiply:by:` function that takes the attribute value and the multiplier as arguments, or use a format string. + +<%- guideExample(guide, 'Multiply', os) %> + + + +You can also cast attribute values in order to use them. One example is to cast an integer as an `NSString` and use it as a text value. + +<%- guideExample(guide, 'Cast', os) %> + + + +### Constant Values + +For constant values that do not necessarily change based on camera or attribute values, use `[NSExpression expressionForConstantValue:]` (previously `[MGLStyleValue valueWithRawValue:]`). + +## Resources + +* [USGS Earthquake Feed](https://earthquake.usgs.gov/earthquakes/feed/v1.0/geojson.php) +* [For Style Authors](for-style-authors.html) +* [Predicates and Expressions](predicates-and-expressions.html) diff --git a/platform/darwin/docs/guides/Predicates and Expressions.md b/platform/darwin/docs/guides/Predicates and Expressions.md index 19d98fd4c1..c3b3d39a52 100644 --- a/platform/darwin/docs/guides/Predicates and Expressions.md +++ b/platform/darwin/docs/guides/Predicates and Expressions.md @@ -19,6 +19,8 @@ based on the feature’s attributes. Use the `MGLVectorStyleLayer.predicate` property to include only the features in the source layer that satisfy a condition that you define. +### Operators + The following comparison operators are supported: `NSPredicateOperatorType` | Format string syntax @@ -31,12 +33,17 @@ The following comparison operators are supported: `NSNotEqualToPredicateOperatorType` | `key != value`<br />`key <> value` `NSBetweenPredicateOperatorType` | `key BETWEEN { 32, 212 }` +To test whether a feature has or lacks a specific attribute, compare the +attribute to `NULL` or `NIL`. Predicates created using the +`+[NSPredicate predicateWithValue:]` method are also supported. String +operators and custom operators are not supported. + The following compound operators are supported: `NSCompoundPredicateType` | Format string syntax --------------------------|--------------------- `NSAndPredicateType` | `predicate1 AND predicate2`<br />`predicate1 && predicate2` -`NSOrPredicateType` | `predicate1 OR predicate2`<br />`predicate1 || predicate2` +`NSOrPredicateType` | `predicate1 OR predicate2`<br /><code>predicate1 || predicate2</code> `NSNotPredicateType` | `NOT predicate`<br />`!predicate` The following aggregate operators are supported: @@ -46,97 +53,101 @@ The following aggregate operators are supported: `NSInPredicateOperatorType` | `key IN { 'iOS', 'macOS', 'tvOS', 'watchOS' }` `NSContainsPredicateOperatorType` | `{ 'iOS', 'macOS', 'tvOS', 'watchOS' } CONTAINS key` -To test whether a feature has or lacks a specific attribute, compare the -attribute to `NULL` or `NIL`. Predicates created using the -`+[NSPredicate predicateWithValue:]` method are also supported. String -operators and custom operators are not supported. +Operator modifiers such as `c` (for case insensitivity), `d` (for diacritic +insensitivity), and `l` (for locale sensitivity) are unsupported for comparison +and aggregate operators that are used in the predicate. + +### Operands + +Operands in predicates can be [variables](#variables), [key paths](#key-paths), +or almost anything else that can appear +[inside an expression](#using-expressions-to-configure-layout-and-paint-attributes). + +Automatic type casting is not performed. Therefore, a feature only matches a +predicate if its value for the attribute in question is of the same type as the +value specified in the predicate. Use the `CAST()` operator to convert a key +path or variable into a matching type: + +* To cast a value to a number, use `CAST(key, 'NSNumber')`. +* To cast a value to a string, use `CAST(key, 'NSString')`. For details about the predicate format string syntax, consult the “Predicate Format String Syntax” chapter of the _[Predicate Programming Guide](https://developer.apple.com/library/content/documentation/Cocoa/Conceptual/Predicates/AdditionalChapters/Introduction.html)_ in Apple developer documentation. -The predicate's left-hand expression must be a string that identifies a feature -attribute or, alternatively, one of the following special attributes: +## Using expressions to configure layout and paint attributes + +An expression can contain subexpressions of various types. Each of the supported +types of expressions is discussed below. + +### Constant values + +A constant value can be of any of the following types: + +In Objective-C | In Swift +----------------------|--------- +`NSColor` (macOS)<br>`UIColor` (iOS) | `NSColor` (macOS)<br>`UIColor` (iOS) +`NSString` | `String` +`NSString` | `String` +`NSNumber.boolValue` | `NSNumber.boolValue` +`NSNumber.doubleValue` | `NSNumber.doubleValue` +`NSArray<NSNumber>` | `[Float]` +`NSArray<NSString>` | `[String]` +`NSValue.CGVectorValue` (iOS)<br>`NSValue` containing `CGVector` (macOS) | `NSValue.cgVectorValue` (iOS)<br>`NSValue` containing `CGVector` (macOS) +`NSValue.UIEdgeInsetsValue` (iOS)<br>`NSValue.edgeInsetsValue` (macOS) | `NSValue.uiEdgeInsetsValue` (iOS)<br>`NSValue.edgeInsetsValue` (macOS) + +For literal floating-point values, use `-[NSNumber numberWithDouble:]` instead +of `-[NSNumber numberWithFloat:]` to avoid precision issues. + +### Key paths + +A key path expression refers to an attribute of the `MGLFeature` object being +evaluated for display. For example, if a polygon’s `MGLFeature.attributes` +dictionary contains the `floorCount` key, then the key path `floorCount` refers +to the value of the `floorCount` attribute when evaluating that particular +polygon. + +The following special attribute is also available on features that are produced +as a result of clustering multiple point features together in a shape source: <table> <thead> -<tr><th>Attribute</th><th>Meaning</th></tr> +<tr><th>Attribute</th><th>Type</th><th>Meaning</th></tr> </thead> <tbody> <tr> - <td><code>$id</code></td> - <td> - A value that uniquely identifies the feature in the containing source. - For details on the types of values that may be associated with this key, - consult the documentation for the <code>MGLFeature</code> protocol’s - <code>identifier</code> property. - </td> -</tr> -<tr> - <td><code>$type</code></td> - <td> - The type of geometry represented by the feature. A feature’s type is - guaranteed to be one of the following strings: - <ul> - <li> - <code>Point</code> for point features, corresponding to the - <code>MGLPointAnnotation</code> class - </li> - <li> - <code>LineString</code> for polyline features, corresponding to - the <code>MGLPolyline</code> class - </li> - <li> - <code>Polygon</code> for polygon features, corresponding to the - <code>MGLPolygon</code> class - </li> - </ul> - </td> -</tr> -<tr> <td><code>point_count</code></td> + <td>Number</td> <td>The number of point features in a given cluster.</td> </tr> </tbody> </table> -The predicate’s right-hand expression must be an `NSString` (to match strings) -or `NSNumber` (to match numbers, including Boolean values) or an array of -`NSString`s or `NSNumber`s, depending on the operator and the type of values -expected for the attribute being tested. For floating-point values, use -`-[NSNumber numberWithDouble:]` instead of `-[NSNumber numberWithFloat:]` -to avoid precision issues. +Some characters may not be used directly as part of a key path in a format +string. For example, if a feature’s attribute is named `ISO 3166-1:2006`, an +expression format string of `lowercase(ISO 3166-1:2006)` or a predicate format +string of `ISO 3166-1:2006 == 'US-OH'` would raise an exception. Instead, use a +`%K` placeholder or the `+[NSExpression expressionForKeyPath:]` initializer: -Automatic type casting is not performed. Therefore, a feature only matches this -predicate if its value for the attribute in question is of the same type as the -value specified in the predicate. Also, operator modifiers such as `c` (for -case insensitivity), `d` (for diacritic insensitivity), and `l` (for locale -sensitivity) are unsupported for comparison and aggregate operators that are -used in the predicate. - -It is possible to create expressions that contain special characters in the -predicate format syntax. This includes the `$` in the `$id` and `$type` special -style attributes and also `hyphen-minus` and `tag:subtag`. However, you must use -`%K` in the format string to represent these variables: -`@"%K == 'LineString'", @"$type"`. +```objc +[NSPredicate predicateWithFormat:@"%K == 'US-OH'", @"ISO 3166-1:2006"]; +[NSExpression expressionForFunction:@"lowercase:" + arguments:@[[NSExpression expressionForKeyPath:@"ISO 3166-1:2006"]]] +``` -## Using expressions to configure layout and paint attributes +```swift +NSPredicate(format: "%K == 'US-OH'", "ISO 3166-1:2006") +NSExpression(forFunction: "lowercase:", + arguments: [NSExpression(forKeyPath: "ISO 3166-1:2006")]) +``` ### Functions -#### Key paths - -A key path expression refers to an attribute of the `MGLFeature` object being -evaluated for display. For example, if a polygon’s `MGLFeature.attributes` -dictionary contains the `floorCount` key, then the key path `floorCount` refers -to the value of the `floorCount` attribute when evaluating that particular -polygon. - -#### Predefined functions - Of the -[functions predefined by the `+[NSExpression expressionForFunction:arguments:]` method](https://developer.apple.com/documentation/foundation/nsexpression/1413747-init#discussion), +[functions predefined](https://developer.apple.com/documentation/foundation/nsexpression/1413747-init#discussion) +by the +[`+[NSExpression expressionForFunction:arguments:]` method](https://developer.apple.com/documentation/foundation/nsexpression/1413747-init), the following subset is supported in layer attribute values: Initializer parameter | Format string syntax @@ -163,8 +174,13 @@ Initializer parameter | Format string syntax `uppercase:` | `uppercase('Elysian Fields')` `lowercase:` | `lowercase('DOWNTOWN')` `noindex:` | `noindex(0 + 2 + c)` +`length:` | `length('Wapakoneta')` +`castObject:toType:` | `CAST(ele, 'NSString')`<br>`CAST(ele, 'NSNumber')` -The following predefined functions are not supported: +A number of [Mapbox-specific functions](#mapbox-specific-functions) are also +available. + +The following predefined functions are **not** supported: Initializer parameter | Format string syntax ----------------------|--------------------- @@ -182,199 +198,65 @@ Initializer parameter | Format string syntax `onesComplement:` | `onesComplement(255)` `distanceToLocation:fromLocation:` | `distanceToLocation:fromLocation:(there, here)` -#### Mapbox-specific functions +### Conditionals -For compatibility with the Mapbox Style Specification, the following functions -are defined by this SDK for use with style layers. Because these functions are -not predefined by `NSExpression`, you must use the -`+[NSExpression expressionForFunction:selectorName:arguments:]` method or the -`FUNCTION()` format string syntax instead. +Conditionals are supported via the built-in +`+[NSExpression expressionForConditional:trueExpression:falseExpression:]` +method and `TERNARY()` operator. If you need to express multiple cases +(“else-if”), you can either nest a conditional within a conditional or use the +[`MGL_IF()`](#code-mgl_if-code) or [`MGL_MATCH()`](#code-mgl_match-code) function. + +### Aggregates + +Aggregate expressions can contain arrays of expressions. In some cases, it is +possible to use the array itself instead of wrapping the array in an aggregate +expression. + +### Variables + +The following variables are defined by this SDK for use with style layers: <table> <thead> -<tr><th>Selector name</th><th>Target</th><th>Arguments</th><th>Returns</th></tr> +<tr><th>Variable</th><th>Type</th><th>Meaning</th></tr> </thead> <tbody> <tr> - <td><code>boolValue</code></td> + <td><code>$featureIdentifier</code></td> <td> - An `NSExpression` that evaluates to a number or string. + Any + <a href="working-with-geojson-data.html#about-geojson-deserialization">GeoJSON data type</a> </td> - <td></td> <td> - A Boolean representation of the target: `FALSE` when then input is an - empty string, 0, `FALSE`, `NIL`, or NaN, otherwise `TRUE`. + A value that uniquely identifies the feature in the containing source. + This variable corresponds to the + <code>NSExpression.featureIdentifierVariableExpression</code> property. </td> </tr> <tr> - <td><code>mgl_expressionWithContext:</code></td> + <td><code>$geometryType</code></td> + <td>String</td> <td> - An `NSExpression` that may contain references to the variables defined in - the context dictionary. - </td> - <td> - An `NSDictionary` with `NSString`s as keys and `NSExpression`s as values. - Each key is a variable name and each value is the variable’s value within - the target expression. - </td> - <td> - The target expression with variable subexpressions replaced with the - values defined in the context dictionary. - </td> -</tr> -<tr> - <td><code>mgl_interpolateWithCurveType:parameters:stops:</code></td> - <td> - An `NSExpression` that evaluates to a number and contains a variable or - key path expression. - </td> - <td> - The first argument is one of the following strings denoting curve types: - `linear`, `exponential`, or `cubic-bezier`. - - The second argument is an expression providing parameters for the curve: - - <ul> - <li>If the curve type is `linear`, the argument is `NIL`.</li> - <li> - If the curve type is `exponential`, the argument is an expression - that evaluates to a number, specifying the base of the exponential - interpolation. - </li> - <li> - If the curve type is `cubic-bezier`, the argument is an array or - aggregate expression containing four expressions, each evaluating to - a number. The four numbers are control points for the cubic Bézier - curve. - </li> - </ul> - - The third argument is an `NSDictionary` object representing the - interpolation’s stops, with numeric zoom levels as keys and expressions as - values. - </td> - <td> - A value interpolated along the continuous mathematical function defined by - the arguments, with the target as the input to the function. - </td> -</tr> -<tr> - <td> - <code>mgl_numberWithFallbackValues:</code>, - <code>doubleValue</code>, - <code>floatValue</code>, - <code>decimalValue</code> - </td> - <td> - An `NSExpression` that evaluates to a Boolean value, number, or string. - </td> - <td> - Zero or more `NSExpression`s, each evaluating to a Boolean value or - string. - </td> - <td> - A numeric representation of the target: - <ul> - <li>If the target is `NIL` or `FALSE`, the result is 0.</li> - <li>If the target is true, the result is 1.</li> - <li> - If the target is a string, it is converted to a number as specified - by the - “<a href="https://tc39.github.io/ecma262/#sec-tonumber-applied-to-the-string-type">ToNumber Applied to the String Type</a>” - algorithm of the ECMAScript Language Specification. - </li> - <li> - If multiple values are provided, each one is evaluated in order - until the first successful conversion is obtained. - </li> - </ul> - </td> -</tr> -<tr> - <td><code>mgl_stepWithMinimum:stops:</code></td> - <td> - An `NSExpression` that evaluates to a number and contains a variable or - key path expression. - </td> - <td> - The first argument is an expression that evaluates to a number, specifying - the minimum value in case the target is less than any of the stops in the - second argument. - - The second argument is an `NSDictionary` object representing the - interpolation’s stops, with numeric zoom levels as keys and expressions as - values. - </td> - <td> - The output value of the stop whose key is just less than the evaluated - target, or the minimum value if the target is less than the least of the - stops’ keys. - </td> -</tr> -<tr> - <td><code>stringByAppendingString:</code></td> - <td> - An `NSExpression` that evaluates to a string. - </td> - <td> - One or more `NSExpression`s, each evaluating to a string. - </td> - <td> - The target string with each of the argument strings appended in order. - </td> -</tr> -<tr> - <td><code>stringValue</code></td> - <td> - An `NSExpression` that evaluates to a Boolean value, number, or string. - </td> - <td></td> - <td> - A string representation of the target: - <ul> - <li>If the target is `NIL`, the result is the string `null`.</li> - <li> - If the target is a Boolean value, the result is the string `true` or - `false`. - </li> - <li> - If the target is a number, it is converted to a string as specified - by the - “<a href="https://tc39.github.io/ecma262/#sec-tostring-applied-to-the-number-type">NumberToString</a>” - algorithm of the ECMAScript Language Specification. - </li> - <li> - If the target is a color, it is converted to a string of the form - `rgba(r,g,b,a)`, where <var>r</var>, <var>g</var>, and <var>b</var> - are numerals ranging from 0 to 255 and <var>a</var> ranges from 0 to - 1. - </li> - <li> - Otherwise, the target is converted to a string in the format - specified by the - [`JSON.stringify()`](https://tc39.github.io/ecma262/#sec-json.stringify) - function of the ECMAScript Language Specification. - </li> - </ul> + The type of geometry represented by the feature. A feature’s type is one + of the following strings: + <ul> + <li> + <code>Point</code> for point features, corresponding to the + <code>MGLPointAnnotation</code> class + </li> + <li> + <code>LineString</code> for polyline features, corresponding to + the <code>MGLPolyline</code> class + </li> + <li> + <code>Polygon</code> for polygon features, corresponding to the + <code>MGLPolygon</code> class + </li> + </ul> + This variable corresponds to the + <code>NSExpression.geometryTypeVariableExpression</code> property. </td> </tr> -</tbody> -</table> - -Some of these functions are defined as methods on their respective target -classes, but you should not call them directly outside the context of an -expression, because the result may differ from the evaluated expression’s result -or may result in undefined behavior. - -### Variables - -The following variables are defined by this SDK for use with style layers: - -<table> -<thead> -<tr><th>Variable</th><th>Type</th><th>Meaning</th></tr> -</thead> -<tbody> <tr> <td><code>$heatmapDensity</code></td> <td>Number</td> @@ -383,7 +265,9 @@ The following variables are defined by this SDK for use with style layers: <a href="https://en.wikipedia.org/wiki/Kernel_density_estimation">kernel density estimation</a> of a screen point in a heatmap layer; in other words, a relative measure of how many data points are crowded around a particular pixel. This - variable can only be used with the `heatmapColor` property. + variable can only be used with the <code>heatmapColor</code> property. + This variable corresponds to the + <code>NSExpression.heatmapDensityVariableExpression</code> property. </td> </tr> <tr> @@ -392,7 +276,8 @@ The following variables are defined by this SDK for use with style layers: <td> The current zoom level. In style layout and paint properties, this variable may only appear as the target of a top-level interpolation or - step expression. + step expression. This variable corresponds to the + <code>NSExpression.zoomLevelVariableExpression</code> property. </td> </tr> </tbody> @@ -404,11 +289,601 @@ of a [Mapbox-specific function](#mapbox-specific-functions) that takes an `NSDictionary` as an argument: ```objc -[NSExpression expressionWithFormat:@"FUNCTION($floorCount + 1, 'mgl_expressionWithContext:', %@)", - {@"floorCount": @2}]; +[NSExpression expressionWithFormat:@"MGL_LET('floorCount', 2, $floorCount + 1)"]; ``` ```swift -NSExpression(format: "FUNCTION($floorCount + 1, 'mgl_expressionWithContext:', %@)", - ["floorCount": 2]) +NSExpression(format: "MGL_LET(floorCount, 2, $floorCount + 1)") ``` + +## Mapbox-specific functions + +For compatibility with the Mapbox Style Specification, the following functions +are defined by this SDK. When setting a style layer property, you can call these +functions just like the predefined functions above, using either the +`+[NSExpression expressionForFunction:arguments:]` method or a convenient format +string syntax: + +### `mgl_does:have:` + +<dl> +<dt>Selector:</dt> +<dd><code>mgl_does:have:</code></dd> +<dt>Format string syntax:</dt> +<dd><code>mgl_does:have:(SELF, '🧀🍔')</code> or <code>mgl_does:have:(%@, '🧀🍔')</code></dd> +</dl> + +Returns a Boolean value indicating whether the dictionary has a value for the +key or whether the evaluated object (`SELF`) has a value for the feature +attribute. Compared to the [`mgl_has:`](#code-mgl_has-code) custom function, +that function’s target is instead passed in as the first argument to this +function. Both functions are equivalent to the syntax `key != NIL` or +`%@[key] != NIL` but can be used outside of a predicate. + +### `mgl_interpolate:withCurveType:parameters:stops:` + +<dl> +<dt>Selector:</dt> +<dd><code>mgl_interpolate:withCurveType:parameters:stops:</code></dd> +<dt>Format string syntax:</dt> +<dd><code>mgl_interpolate:withCurveType:parameters:stops:(x, 'linear', nil, %@)</code></dd> +</dl> + +Produces continuous, smooth results by interpolating between pairs of input and +output values (“stops”). Compared to the +[`mgl_interpolateWithCurveType:parameters:stops:`](#code-mgl_interpolatewithcurvetype-parameters-stops-code) +custom function, the input expression (that function’s target) is instead passed +in as the first argument to this function. + +### `mgl_step:from:stops:` + +<dl> +<dt>Selector:</dt> +<dd><code>mgl_step:from:stops:</code></dd> +<dt>Format string syntax:</dt> +<dd><code>mgl_step:from:stops:(x, 11, %@)</code></dd> +</dl> + +Produces discrete, stepped results by evaluating a piecewise-constant function +defined by pairs of input and output values ("stops"). Compared to the +[`mgl_stepWithMinimum:stops:`](#code-mgl_stepwithminimum-stops-code) custom +function, the input expression (that function’s target) is instead passed in as +the first argument to this function. + +### `mgl_join:` + +<dl> +<dt>Selector:</dt> +<dd><code>mgl_join:</code></dd> +<dt>Format string syntax:</dt> +<dd><code>mgl_join({'Old', 'MacDonald'})</code></dd> +</dl> + +Returns the result of concatenating together all the elements of an array in +order. Compared to the +[`stringByAppendingString:`](#code-stringbyappendingstring-code) custom +function, this function takes only one argument, which is an aggregate +expression containing the strings to concatenate. + +### `mgl_acos:` + +<dl> +<dt>Selector:</dt> +<dd><code>mgl_acos:</code></dd> +<dt>Format string syntax:</dt> +<dd><code>mgl_acos(1)</code></dd> +</dl> + +Returns the arccosine of the number. + +This function corresponds to the +[`acos`](https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions-acos) +operator in the Mapbox Style Specification. + +### `mgl_asin:` + +<dl> +<dt>Selector:</dt> +<dd><code>mgl_asin:</code></dd> +<dt>Format string syntax:</dt> +<dd><code>mgl_asin(0)</code></dd> +</dl> + +Returns the arcsine of the number. + +This function corresponds to the +[`asin`](https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions-asin) +operator in the Mapbox Style Specification. + +### `mgl_atan:` + +<dl> +<dt>Selector:</dt> +<dd><code>mgl_atan:</code></dd> +<dt>Format string syntax:</dt> +<dd><code>mgl_atan(20)</code></dd> +</dl> + +Returns the arctangent of the number. + +This function corresponds to the +[`atan`](https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions-atan) +operator in the Mapbox Style Specification. + +### `mgl_cos:` + +<dl> +<dt>Selector:</dt> +<dd><code>mgl_cos:</code></dd> +<dt>Format string syntax:</dt> +<dd><code>mgl_cos(0)</code></dd> +</dl> + +Returns the cosine of the number. + +This function corresponds to the +[`cos`](https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions-cos) +operator in the Mapbox Style Specification. + +### `mgl_log2:` + +<dl> +<dt>Selector:</dt> +<dd><code>mgl_log2:</code></dd> +<dt>Format string syntax:</dt> +<dd><code>mgl_log2(1024)</code></dd> +</dl> + +Returns the base-2 logarithm of the number. + +This function corresponds to the +[`log2`](https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions-log2) +operator in the Mapbox Style Specification. + +### `mgl_round:` + +<dl> +<dt>Selector:</dt> +<dd><code>mgl_round:</code></dd> +<dt>Format string syntax:</dt> +<dd><code>mgl_round(1.5)</code></dd> +</dl> + +Returns the number rounded to the nearest integer. If the number is halfway +between two integers, this function rounds it away from zero. + +This function corresponds to the +[`round`](https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions-round) +operator in the Mapbox Style Specification. + +### `mgl_sin:` + +<dl> +<dt>Selector:</dt> +<dd><code>mgl_sin:</code></dd> +<dt>Format string syntax:</dt> +<dd><code>mgl_sin(0)</code></dd> +</dl> + +Returns the sine of the number. + +This function corresponds to the +[`sin`](https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions-sin) +operator in the Mapbox Style Specification. + +### `mgl_tan:` + +<dl> +<dt>Selector:</dt> +<dd><code>mgl_tan:</code></dd> +<dt>Format string syntax:</dt> +<dd><code>mgl_tan(0)</code></dd> +</dl> + +Returns the tangent of the number. + +This function corresponds to the +[`tan`](https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions-tan) +operator in the Mapbox Style Specification. + +### `mgl_coalesce:` + +<dl> +<dt>Selector:</dt> +<dd><code>mgl_coalesce:</code></dd> +<dt>Format string syntax:</dt> +<dd><code>mgl_coalesce({x, y, z})</code></dd> +</dl> + +Returns the first non-`nil` value from an array of expressions. + +This function corresponds to the +[`coalesce`](https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions-coalesce) +operator in the Mapbox Style Specification. + +### `MGL_LET` + +<dl> +<dt>Selector:</dt> +<dd><code>MGL_LET:</code></dd> +<dt>Format string syntax:</dt> +<dd><code>MGL_LET('age', uppercase('old'), 'name', uppercase('MacDonald'), mgl_join({$age, $name}))</code></dd> +<dt>Arguments:</dt> +<dd> + Any number of variable names interspersed with their assigned + <code>NSExpression</code> values, followed by an <code>NSExpression</code> + that may contain references to those variables. +</dd> +</dl> + +Returns the result of evaluating an expression with the given variable values. +Compared to the +[`mgl_expressionWithContext:`](#code-mgl_expressionwithcontext-code) custom +function, this function takes the variable names and values inline before the +expression that contains references to those variables. + +### `MGL_MATCH` + +<dl> +<dt>Selector:</dt> +<dd><code>MGL_MATCH:</code></dd> +<dt>Format string syntax:</dt> +<dd><code>MGL_MATCH(x, 0, 'zero match', 1, 'one match', 'two match', 'default')</code></dd> +<dt>Arguments:</dt> +<dd> + An input expression, then any number of argument pairs, followed by a default + expression. Each argument pair consists of a constant value followed by an + expression to produce as a result of matching that constant value. +</dd> +</dl> + +Returns the result of matching the input expression against the given constant +values. + +This function corresponds to the +`+[NSExpression(MGLAdditions) mgl_expressionForMatchingExpression:inDictionary:defaultExpression:]` +method and the +[`match`](https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions-match) +operator in the Mapbox Style Specification. + +### `MGL_IF` + +<dl> +<dt>Selector:</dt> +<dd><code>MGL_IF:</code></dd> +<dt>Format string syntax:</dt> +<dd><code>MGL_IF(1 = 2, YES, 2 = 2, YES, NO)</code></dd> +<dt>Arguments:</dt> +<dd> + Alternating <code>NSPredicate</code> conditionals and resulting expressions, + followed by a default expression. +</dd> +</dl> + +Returns the first expression that meets the condition; otherwise, the default +value. Unlike +`+[NSExpression expressionForConditional:trueExpression:falseExpression:]` or +the `TERNARY()` syntax, this function can accept multiple “if else” conditions +and is supported on iOS 8._x_ and macOS 10.10._x_; however, each conditional +passed into this function must be wrapped in a constant expression. + +This function corresponds to the +`+[NSExpression(MGLAdditions) mgl_expressionForConditional:trueExpression:falseExpresssion:]` +method and the +[`case`](https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions-case) +operator in the Mapbox Style Specification. + +### `MGL_FUNCTION` + +<dl> +<dt>Selector:</dt> +<dd><code>MGL_FUNCTION:</code></dd> +<dt>Format string syntax:</dt> +<dd><code>MGL_FUNCTION('typeof', mystery)</code></dd> +<dt>Arguments:</dt> +<dd> + Any arguments required by the expression operator. +</dd> +</dl> + +An expression exactly as defined by the +[Mapbox Style Specification](https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions). + +## Custom functions + +The following custom functions are also available with the +`+[NSExpression expressionForFunction:selectorName:arguments:]` method or the +`FUNCTION()` format string syntax. + +Some of these functions are defined as methods on their respective target +classes, but you should not call them directly outside the context of an +expression, because the result may differ from the evaluated expression’s result +or may result in undefined behavior. + +The Mapbox Style Specification defines some operators for which no custom +function is available. To use these operators in an `NSExpression`, call the +[`MGL_FUNCTION()`](#code-mgl_function-code) function with the same arguments +that the operator expects. + +### `boolValue` + +<dl> +<dt>Selector:</dt> +<dd><code>boolValue</code></dd> +<dt>Format string syntax:</dt> +<dd><code>FUNCTION(1, 'boolValue')</code></dd> +<dt>Target:</dt> +<dd> + An <code>NSExpression</code> that evaluates to a number or string. +</dd> +<dt>Arguments:</dt> +<dd>None.</dd> +</dl> + +A Boolean representation of the target: <code>FALSE</code> when then input is an +empty string, 0, <code>FALSE</code>, <code>NIL</code>, or <code>NaN</code>, +otherwise <code>TRUE</code>. + +### `mgl_has:` + +<dl> +<dt>Selector:</dt> +<dd><code>mgl_has:</code></dd> +<dt>Format string syntax:</dt> +<dd><code>FUNCTION($featureAttributes, 'mgl_has:', '🧀🍔')</code></dd> +<dt>Target:</dt> +<dd> + An <code>NSExpression</code> that evaluates to an <code>NSDictionary</code> + or the evaluated object (<code>SELF</code>). +</dd> +<dt>Arguments:</dt> +<dd> + An <code>NSExpression</code> that evaluates to an <code>NSString</code> + representing the key to look up in the dictionary or the feature attribute to + look up in the evaluated object (see <code>MGLFeature.attributes</code>). +</dd> +</dl> + +<code>true</code> if the dictionary has a value for the key or if the evaluated +object has a value for the feature attribute. + +This function corresponds to the +[`has`](https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions-has) +operator in the Mapbox Style Specification. See also the +[`mgl_does:have:`](#code-mgl_does-have-code) function, which is used on its own +without the `FUNCTION()` operator. You can also check whether an object has an +attribute by comparing the key path to `NIL`, for example `cheeseburger != NIL` +or `burger.cheese != NIL` + +### `mgl_expressionWithContext:` + +<dl> +<dt>Selector:</dt> +<dd><code>mgl_expressionWithContext:</code></dd> +<dt>Format string syntax:</dt> +<dd> + <code>FUNCTION($ios + $macos, 'mgl_expressionWithContext:', %@)</code> with + a dictionary containing <code>ios</code> and <code>macos</code> keys +</dd> +<dt>Target:</dt> +<dd> + An <code>NSExpression</code> that may contain references to the variables + defined in the context dictionary. +</dd> +<dt>Arguments:</dt> +<dd> + An <code>NSDictionary</code> with <code>NSString</code>s as keys and + <code>NSExpression</code>s as values. Each key is a variable name and each + value is the variable’s value within the target expression. +</dd> +</dl> + +The target expression with variable subexpressions replaced with the values +defined in the context dictionary. + +This function corresponds to the +[`let`](https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions-let) +operator in the Mapbox Style Specification. See also the +[`MGL_LET`](#code-mgl_let-code) function, which is used on its own without the +`FUNCTION()` operator. + +### `mgl_interpolateWithCurveType:parameters:stops:` + +<dl> +<dt>Selector:</dt> +<dd><code>mgl_interpolateWithCurveType:parameters:stops:</code></dd> +<dt>Format string syntax:</dt> +<dd> + <code>FUNCTION($zoomLevel, 'mgl_interpolateWithCurveType:parameters:stops:', 'linear', NIL, %@)</code> + with a dictionary containing zoom levels or other constant values as keys +</dd> +<dt>Target:</dt> +<dd> + An <code>NSExpression</code> that evaluates to a number and contains a + variable or key path expression. +</dd> +<dt>Arguments:</dt> +<dd> + The first argument is one of the following strings denoting curve types: + <code>linear</code>, <code>exponential</code>, or <code>cubic-bezier</code>. + + The second argument is an expression providing parameters for the curve: + + <ul> + <li>If the curve type is <code>linear</code>, the argument is <code>NIL</code>.</li> + <li> + If the curve type is <code>exponential</code>, the argument is an + expression that evaluates to a number, specifying the base of the + exponential interpolation. + </li> + <li> + If the curve type is <code>cubic-bezier</code>, the argument is an + array or aggregate expression containing four expressions, each + evaluating to a number. The four numbers are control points for the + cubic Bézier curve. + </li> + </ul> + + The third argument is an <code>NSDictionary</code> object representing the + interpolation’s stops, with numeric zoom levels as keys and expressions as + values. +</dd> +</dl> + +A value interpolated along the continuous mathematical function defined by the +arguments, with the target as the input to the function. + +The input expression is matched against the keys in the stop dictionary. The +keys may be feature attribute values, zoom levels, or heatmap densities. The +values may be constant values or `NSExpression` objects. For example, you can +use a stop dictionary with the zoom levels 0, 10, and 20 as keys and the colors +yellow, orange, and red as the values. + +This function corresponds to the +`+[NSExpression(MGLAdditions) mgl_expressionForInterpolatingExpression:withCurveType:parameters:stops:]` +method and the +[`interpolate`](https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions-interpolate) +operator in the Mapbox Style Specification. See also the +[`mgl_interpolate:withCurveType:parameters:stops:`](#code-mgl_interpolate-withcurvetype-parameters-stops-code) +function, which is used on its own without the `FUNCTION()` operator. + +### `mgl_numberWithFallbackValues:` + +<dl> +<dt>Selector:</dt> +<dd> + <code>mgl_numberWithFallbackValues:</code>, + <code>doubleValue</code>, + <code>floatValue</code>, or + <code>decimalValue</code> +</dd> +<dt>Format string syntax:</dt> +<dd><code>FUNCTION(ele, 'mgl_numberWithFallbackValues:', 0)</code></dd> +<dt>Target:</dt> +<dd> + An <code>NSExpression</code> that evaluates to a Boolean value, number, or + string. +</dd> +<dt>Arguments:</dt> +<dd> + Zero or more <code>NSExpression</code>s, each evaluating to a Boolean value + or string. +</dd> +</dl> + +A numeric representation of the target: + +* If the target is <code>NIL</code> or <code>FALSE</code>, the result is 0. +* If the target is true, the result is 1. + * If the target is a string, it is converted to a number as specified by the + “[ToNumber Applied to the String Type](https://tc39.github.io/ecma262/#sec-tonumber-applied-to-the-string-type)” + algorithm of the ECMAScript Language Specification. + * If multiple values are provided, each one is evaluated in order until the + first successful conversion is obtained. + +This function corresponds to the +[`to-number`](https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions-types-to-number) +operator in the Mapbox Style Specification. You can also cast a value to a +number by passing the value and the string `NSNumber` into the `CAST()` +operator. + +### `mgl_stepWithMinimum:stops:` + +<dl> +<dt>Selector:</dt> +<dd><code>mgl_stepWithMinimum:stops:</code></dd> +<dt>Format string syntax:</dt> +<dd> + <code>FUNCTION($zoomLevel, 'mgl_stepWithMinimum:stops:', 0, %@)</code> with + a dictionary with zoom levels or other constant values as keys +</dd> +<dt>Target:</dt> +<dd> + An <code>NSExpression</code> that evaluates to a number and contains a + variable or key path expression. +</dd> +<dt>Arguments:</dt> +<dd> + The first argument is an expression that evaluates to a number, specifying + the minimum value in case the target is less than any of the stops in the + second argument. + + The second argument is an <code>NSDictionary</code> object representing the + interpolation’s stops, with numeric zoom levels as keys and expressions as + values. +</dd> +</dl> + +The output value of the stop whose key is just less than the evaluated target, +or the minimum value if the target is less than the least of the stops’ keys. + +The input expression is matched against the keys in the stop dictionary. The +keys may be feature attribute values, zoom levels, or heatmap densities. The +values may be constant values or `NSExpression` objects. For example, you can +use a stop dictionary with the zoom levels 0, 10, and 20 as keys and the colors +yellow, orange, and red as the values. + +This function corresponds to the +`+[NSExpression(MGLAdditions) mgl_expressionForSteppingExpression:fromExpression:stops:]` +method and the +[`step`](https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions-step) +operator in the Mapbox Style Specification. + +### `stringByAppendingString:` + +<dl> +<dt>Selector:</dt> +<dd><code>stringByAppendingString:</code></dd> +<dt>Format string syntax:</dt> +<dd><code>FUNCTION('Old', 'stringByAppendingString:', 'MacDonald')</code></dd> +<dt>Target:</dt> +<dd>An <code>NSExpression</code> that evaluates to a string.</dd> +<dt>Arguments:</dt> +<dd>One or more <code>NSExpression</code>s, each evaluating to a string.</dd> +</dl> + +The target string with each of the argument strings appended in order. + +This function corresponds to the +`-[NSExpression(MGLAdditions) mgl_expressionByAppendingExpression:]` +method and is similar to the +[`concat`](https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions-concat) +operator in the Mapbox Style Specification. See also the +[`mgl_join:`](#code-mgl_join-code) function, which concatenates multiple +expressions and is used on its own without the `FUNCTION()` operator. + +### `stringValue` + +<dl> +<dt>Selector:</dt> +<dd><code>stringValue</code></dd> +<dt>Format string syntax:</dt> +<dd><code>FUNCTION(ele, 'stringValue')</code></dd> +<dt>Target:</dt> +<dd> + An <code>NSExpression</code> that evaluates to a Boolean value, number, or + string. +</dd> +<dt>Arguments:</dt> +<dd>None.</dd> +</dl> + +A string representation of the target: + +* If the target is <code>NIL</code>, the result is the empty string. +* If the target is a Boolean value, the result is the string `true` or `false`. +* If the target is a number, it is converted to a string as specified by the + “[NumberToString](https://tc39.github.io/ecma262/#sec-tostring-applied-to-the-number-type)” + algorithm of the ECMAScript Language Specification. +* If the target is a color, it is converted to a string of the form + `rgba(r,g,b,a)`, where <var>r</var>, <var>g</var>, and <var>b</var> are + numerals ranging from 0 to 255 and <var>a</var> ranges from 0 to 1. +* Otherwise, the target is converted to a string in the format specified by the + [`JSON.stringify()`](https://tc39.github.io/ecma262/#sec-json.stringify) + function of the ECMAScript Language Specification. + +This function corresponds to the +[`to-string`](https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions-types-to-string) +operator in the Mapbox Style Specification. You can also cast a value to a +string by passing the value and the string `NSString` into the `CAST()` +operator. diff --git a/platform/darwin/docs/guides/Tile URL Templates.md.ejs b/platform/darwin/docs/guides/Tile URL Templates.md.ejs index 78fb297138..2b1de65b42 100644 --- a/platform/darwin/docs/guides/Tile URL Templates.md.ejs +++ b/platform/darwin/docs/guides/Tile URL Templates.md.ejs @@ -10,12 +10,12 @@ --> # Tile URL Templates -`MGLTileSource` objects, specifically `MGLRasterSource` and `MGLVectorSource` -objects, can be created using an initializer that accepts an array of tile URL -templates. Tile URL templates are strings that specify the URLs of the vector -tiles or raster tile images to load. A template resembles an absolute URL, but -with any number of placeholder strings that the source evaluates based on the -tile it needs to load. For example: +`MGLTileSource` objects, specifically `MGLRasterTileSource` and +`MGLVectorTileSource` objects, can be created using an initializer that accepts +an array of tile URL templates. Tile URL templates are strings that specify the +URLs of the vector tiles or raster tile images to load. A template resembles an +absolute URL, but with any number of placeholder strings that the source +evaluates based on the tile it needs to load. For example: * `http://www.example.com/tiles/{z}/{x}/{y}.pbf` could be evaluated as `http://www.example.com/tiles/14/6/9.pbf`. @@ -62,7 +62,7 @@ all of which are optional: <td>The tile’s zoom level. At zoom level 0, each tile covers the entire world map; at zoom level 1, it covers ¼ of the world; at zoom level 2, <sup>1</sup>⁄<sub>16</sub> of the world, and so on. For tiles loaded by - a <code>MGLRasterSource</code> object, whether the tile zoom level + a <code>MGLRasterTileSource</code> object, whether the tile zoom level matches the map’s current zoom level depends on the value of the source’s tile size as specified in the <code>MGLTileSourceOptionTileSize</code> key of the <code>options</code> diff --git a/platform/darwin/docs/guides/Using Style Functions at Runtime.md.ejs b/platform/darwin/docs/guides/Using Style Functions at Runtime.md.ejs deleted file mode 100644 index 61034a674f..0000000000 --- a/platform/darwin/docs/guides/Using Style Functions at Runtime.md.ejs +++ /dev/null @@ -1,99 +0,0 @@ -<% - const os = locals.os; - const iOS = os === 'iOS'; - const macOS = os === 'macOS'; - const cocoaPrefix = iOS ? 'UI' : 'NS'; - const guide = 'UsingStyleFunctionsAtRuntime'; --%> -<!-- - This file is generated. - Edit platform/darwin/scripts/generate-style-code.js, then run `make darwin-style-code`. ---> - -# Using Style Functions at Runtime - -[Runtime Styling](runtime-styling.html) enables you to modify every aspect of the map’s appearance dynamically as a user interacts with your application. Much of the runtime styling API allows you to specify _style functions_ instead of constant values. A style function allows you to specify in advance how a layout or paint attribute will vary as the zoom level changes or how the appearance of individual features vary based on metadata provided by a content source. - -Style functions spare you the inconvenience of manually calculating intermediate values between different zoom levels or creating a multitude of style layers to handle homogeneous features in the map content. For example, if your content source indicates the prices of hotels in an area, you can color-code the hotels by price, relying on a style function to smoothly interpolate among desired colors without having to specify the color for each exact price. - -_Data-driven styling_ specifically refers to the use of style functions to vary the map’s appearance based on data in a content source. - -You can also specify style functions in a style JSON file, to be applied automatically when the map loads. See the [Mapbox Style Specification](https://www.mapbox.com/mapbox-gl-js/style-spec/#types-function) for details. - -  - -This guide uses earthquake data from the [U.S. Geological Survey](https://earthquake.usgs.gov/earthquakes/feed/v1.0/geojson.php) and data-driven styling to style a map based on attributes. For more information about how to work with GeoJSON data in our iOS SDK, please see our [working with GeoJSON data](working-with-geojson-data.html) guide. - -A style function is represented at runtime by the `MGLStyleFunction` class. There are three subclasses of `MGLStyleFunction`: - -* `MGLCameraStyleFunction` is a style value that changes with zoom level. For example, you can make the radius of a circle increase according to zoom level. -* `MGLSourceStyleFunction` is a style value that changes with the attributes of a feature. For example, you can adjust the radius of a circle based on the magnitude of an earthquake. -* `MGLCompositeStyleFunction` is a style value that changes with both zoom level and attribute values. For example, you can add a circle layer where each circle has a radius based on both zoom level and the magnitude of an earthquake. - -The documentation for each individual style layer property notes which style functions are enabled for that property. - -## Stops - -Stops are dictionary keys that are associated with layer attribute values. With feature attribute values as stops, you can use a dictionary with a zoom level for a key and an expression or constant value for the value. For example, you can use a stop dictionary with the zoom levels 0, 10, and 20 as keys and the colors yellow, orange, and red as the values. Alternatively, attribute values can be the keys. - -<%- guideExample(guide, 'Stops', os) %> - -## Interpolation mode - -The effect a key has on the style value is determined by the interpolation mode. There are four interpolation modes that can be used with a source style function: exponential, interval, categorical, and identity. You can also use exponential and interval interpolation modes with a camera style function. - -### Linear - -`MGLInterpolationModeExponential` interpolates linearly or exponentially between style function stop values. By default, the `MGLStyleFunction` options parameter `MGLStyleFunctionOptionInterpolationBase` equals `1`, which represents linear interpolation and doesn’t need to be included in the options dictionary. - -The stops dictionary below, for example, shows colors that continuously shift from yellow to orange to red to blue to white based on the attribute value. - -<%- guideExample(guide, 'Linear', os) %> - - - -### Exponential - -By combining `MGLInterpolationModeExponential` with an `MGLStyleFunctionOptionInterpolationBase` greater than `0` (other than `1`), you can interpolate between values exponentially, create an accelerated ramp effect. - -Here’s a visualization from Mapbox Studio (see [Working with Mapbox Studio](working-with-mapbox-studio.html)) comparing interpolation base values of `1.5` and `0.5` based on zoom. - -<img src="img/data-driven-styling/exponential-function.png" height=344/> -<img src="img/data-driven-styling/exponential-function-1.png" height=344/> - -The example below increases a layer’s `circleRadius` exponentially based on a map’s zoom level. The `MGLStyleFunctionOptionInterpolationBase` is `1.5`. - -<%- guideExample(guide, 'Exponential', os) %> - -### Interval - -`MGLInterpolationModeInterval` creates a range using the keys from the stops dictionary. The range is from the given key to just less than the next key. The attribute values that fall into that range are then styled using the style value assigned to that key. - -When we use the stops dictionary given above with an interval interpolation mode, we create ranges where earthquakes with a magnitude of 0 to just less than 2.5 would be yellow, 2.5 to just less than 5 would be orange, and so on. - -<%- guideExample(guide, 'Interval', os) %> - - - -### Categorical - -At each stop, `MGLInterpolationModeCategorical` produces an output value equal to the function input. We’re going to use a different stops dictionary than we did for the previous two modes. - -There are three main types of events in the dataset: earthquakes, explosions, and quarry blasts. In this case, the color of the circle layer will be determined by the type of event, with a default value of blue to catch any events that do not fall into any of those categories. - -<%- guideExample(guide, 'Categorical', os) %> - -  - -### Identity - -`MGLInterpolationModeIdentity` uses the attribute’s value as the style value. For example, you can set the `circleRadius` to the earthquake’s magnitude. Since the attribute value itself will be used as the style value, `sourceStops` should be set to `nil`. - -<%- guideExample(guide, 'Identity', os) %> - - - -##Resources - -* [USGS](https://earthquake.usgs.gov/earthquakes/feed/v1.0/geojson.php) -* [For Style Authors](for-style-authors.html) diff --git a/platform/darwin/docs/img/data-driven-styling/cast.png b/platform/darwin/docs/img/data-driven-styling/cast.png Binary files differnew file mode 100644 index 0000000000..e5b40b4ffa --- /dev/null +++ b/platform/darwin/docs/img/data-driven-styling/cast.png diff --git a/platform/darwin/docs/img/data-driven-styling/categorical1.png b/platform/darwin/docs/img/data-driven-styling/categorical1.png Binary files differdeleted file mode 100644 index 969846b41b..0000000000 --- a/platform/darwin/docs/img/data-driven-styling/categorical1.png +++ /dev/null diff --git a/platform/darwin/docs/img/data-driven-styling/categorical2.png b/platform/darwin/docs/img/data-driven-styling/categorical2.png Binary files differdeleted file mode 100644 index 5008c522ed..0000000000 --- a/platform/darwin/docs/img/data-driven-styling/categorical2.png +++ /dev/null diff --git a/platform/darwin/docs/img/data-driven-styling/citibikes.png b/platform/darwin/docs/img/data-driven-styling/citibikes.png Binary files differdeleted file mode 100644 index a616672a32..0000000000 --- a/platform/darwin/docs/img/data-driven-styling/citibikes.png +++ /dev/null diff --git a/platform/darwin/docs/img/data-driven-styling/exponential-function-1.png b/platform/darwin/docs/img/data-driven-styling/exponential-function-1.png Binary files differindex 6aa129a305..39a8a2a1e4 100644 --- a/platform/darwin/docs/img/data-driven-styling/exponential-function-1.png +++ b/platform/darwin/docs/img/data-driven-styling/exponential-function-1.png diff --git a/platform/darwin/docs/img/data-driven-styling/exponential-function.png b/platform/darwin/docs/img/data-driven-styling/exponential-function.png Binary files differindex c14969f0a8..f9824fc5e4 100644 --- a/platform/darwin/docs/img/data-driven-styling/exponential-function.png +++ b/platform/darwin/docs/img/data-driven-styling/exponential-function.png diff --git a/platform/darwin/docs/img/data-driven-styling/exponential.png b/platform/darwin/docs/img/data-driven-styling/exponential.png Binary files differdeleted file mode 100644 index 87ddc1350e..0000000000 --- a/platform/darwin/docs/img/data-driven-styling/exponential.png +++ /dev/null diff --git a/platform/darwin/docs/img/data-driven-styling/identity.png b/platform/darwin/docs/img/data-driven-styling/identity.png Binary files differindex 632ccdf3d5..3355694ec9 100644 --- a/platform/darwin/docs/img/data-driven-styling/identity.png +++ b/platform/darwin/docs/img/data-driven-styling/identity.png diff --git a/platform/darwin/docs/img/data-driven-styling/interval.png b/platform/darwin/docs/img/data-driven-styling/interval.png Binary files differdeleted file mode 100644 index d15aff2025..0000000000 --- a/platform/darwin/docs/img/data-driven-styling/interval.png +++ /dev/null diff --git a/platform/darwin/docs/img/data-driven-styling/multiply.png b/platform/darwin/docs/img/data-driven-styling/multiply.png Binary files differnew file mode 100644 index 0000000000..df42f243e1 --- /dev/null +++ b/platform/darwin/docs/img/data-driven-styling/multiply.png diff --git a/platform/darwin/docs/img/data-driven-styling/polylineExample.png b/platform/darwin/docs/img/data-driven-styling/polylineExample.png Binary files differdeleted file mode 100644 index cd9b39bae4..0000000000 --- a/platform/darwin/docs/img/data-driven-styling/polylineExample.png +++ /dev/null diff --git a/platform/darwin/docs/theme/assets/css/jazzy.css.scss b/platform/darwin/docs/theme/assets/css/jazzy.css.scss index 103ba601dc..ff6d2a374c 100644 --- a/platform/darwin/docs/theme/assets/css/jazzy.css.scss +++ b/platform/darwin/docs/theme/assets/css/jazzy.css.scss @@ -113,7 +113,12 @@ h2 { } h3 { - @include heading(14px, 1em 0 0.3em); + @include heading(1.2rem, 1em 0 0.3em); +} + +h3 > code { + font-weight: bold; + font-size: 1.2rem; } h4 { @@ -386,7 +391,6 @@ pre code { .nav-group-task[data-name="MGLStyleFunction"], .nav-group-task[data-name="MGLStyleLayer"], .nav-group-task[data-name="MGLTileSource"], -.nav-group-task[data-name="MGLAbstractShapeSource"], .nav-group-task[data-name="MGLVectorStyleLayer"] { .nav-group-task-link::after { @extend %nav-group-task-gloss; |
