iOS SDK

API Reference

On This Page

NSExpression(MGLAdditions)

@interface NSExpression (MGLAdditions)

Methods for creating expressions that use Mapbox-specific functionality and for converting to and from the JSON format defined in the Mapbox Style Specification.

Creating Variable Expressions

zoomLevelVariableExpression

NSExpression variable that corresponds to the zoom expression operator in the Mapbox Style Specification.

Declaration

Objective-C

@property (class, nonatomic, readonly)
NSExpression *_Nonnull zoomLevelVariableExpression;

Swift

class var zoomLevelVariable: NSExpression { get }

heatmapDensityVariableExpression

NSExpression variable that corresponds to the heatmap-density expression operator in the Mapbox Style Specification.

Declaration

Objective-C

@property (class, nonatomic, readonly)
NSExpression *_Nonnull heatmapDensityVariableExpression;

Swift

class var heatmapDensityVariable: NSExpression { get }

lineProgressVariableExpression

NSExpression variable that corresponds to the line-progress expression operator in the Mapbox Style Specification.

Declaration

Objective-C

@property (class, nonatomic, readonly)
NSExpression *_Nonnull lineProgressVariableExpression;

Swift

class var lineProgressVariable: NSExpression { get }

geometryTypeVariableExpression

NSExpression variable that corresponds to the geometry-type expression operator in the Mapbox Style Specification.

Declaration

Objective-C

@property (class, nonatomic, readonly)
NSExpression *_Nonnull geometryTypeVariableExpression;

Swift

class var geometryTypeVariable: NSExpression { get }

featureIdentifierVariableExpression

NSExpression variable that corresponds to the id expression operator in the Mapbox Style Specification.

Declaration

Objective-C

@property (class, nonatomic, readonly)
NSExpression *_Nonnull featureIdentifierVariableExpression;

Swift

class var featureIdentifierVariable: NSExpression { get }

featureAccumulatedVariableExpression

NSExpression variable that corresponds to the id expression operator in the Mapbox Style Specification.

Declaration

Objective-C

@property (class, nonatomic, readonly)
NSExpression *_Nonnull featureAccumulatedVariableExpression;

Swift

class var featureAccumulatedVariable: NSExpression { get }

featureAttributesVariableExpression

NSExpression variable that corresponds to the properties expression operator in the Mapbox Style Specification.

Declaration

Objective-C

@property (class, nonatomic, readonly)
NSExpression *_Nonnull featureAttributesVariableExpression;

Swift

class var featureAttributesVariable: NSExpression { get }

Creating Conditional Expressions

+mgl_expressionForConditional:trueExpression:falseExpresssion:

Returns a conditional function expression specifying the string predicate, and expressions for each condition.

Declaration

Objective-C

+ (nonnull instancetype)
mgl_expressionForConditional:(nonnull NSPredicate *)conditionPredicate
              trueExpression:(nonnull NSExpression *)trueExpression
            falseExpresssion:(nonnull NSExpression *)falseExpression;

Swift

convenience init(forMGLConditional conditionPredicate: NSPredicate, trueExpression: NSExpression, falseExpression: NSExpression)

Parameters

conditionPredicate

The predicate to get evaluated.

trueExpression

The expression for conditions equal to true.

falseExpression

The expression for conditions equal to false.

Creating Ramp, Scale, and Curve Expressions

+mgl_expressionForSteppingExpression:fromExpression:stops:

Returns a step function expression specifying the stepping, from expression and stops.

Declaration

Objective-C

+ (nonnull instancetype)
mgl_expressionForSteppingExpression:
    (nonnull NSExpression *)steppingExpression
                     fromExpression:
                         (nonnull NSExpression *)minimumExpression
                              stops:(nonnull NSExpression *)stops;

Swift

convenience init(forMGLStepping steppingExpression: NSExpression, from minimumExpression: NSExpression, stops: NSExpression)

Parameters

steppingExpression

The stepping expression.

minimumExpression

The expression which could be a constant or function expression.

stops

The stops must be an NSDictionary constant NSExpression.

+mgl_expressionForInterpolatingExpression:withCurveType:parameters:stops:

Returns an interpolated function expression specifying the function operator, curve type, parameters and steps.

Declaration

Objective-C

+ (nonnull instancetype)
mgl_expressionForInterpolatingExpression:
    (nonnull NSExpression *)inputExpression
                           withCurveType:
                               (nonnull MGLExpressionInterpolationMode)
                                   curveType
                              parameters:(nullable NSExpression *)parameters
                                   stops:(nonnull NSExpression *)stops;

Swift

convenience init(forMGLInterpolating inputExpression: NSExpression, curveType: MGLExpressionInterpolationMode, parameters: NSExpression?, stops: NSExpression)

Parameters

inputExpression

The interpolating expression input.

curveType

The curve type could be MGLExpressionInterpolationModeLinear, MGLExpressionInterpolationModeExponential and MGLExpressionInterpolationModeCubicBezier.

parameters

The parameters expression.

stops

The stops expression.

+mgl_expressionForMatchingExpression:inDictionary:defaultExpression:

Returns a match function expression specifying the input, matching values, and default value.

Declaration

Objective-C

+ (nonnull instancetype)
mgl_expressionForMatchingExpression:(nonnull NSExpression *)inputExpression
                       inDictionary:(nonnull NSDictionary<NSExpression *,
                                                          NSExpression *> *)
                                        matchedExpressions
                  defaultExpression:
                      (nonnull NSExpression *)defaultExpression;

Swift

convenience init(forMGLMatchingKey inputExpression: NSExpression, in matchedExpressions: [NSExpression : NSExpression], default defaultExpression: NSExpression)

Parameters

inputExpression

The matching expression.

matchedExpressions

The matched values expression dictionary must be condition : value.

defaultExpression

The defaultValue expression to be used in case there is no match.

+mgl_expressionForAttributedExpressions:

Returns an attributed function expression specifying an MGLAttributedExpression constant expression array.

Declaration

Objective-C

+ (nonnull instancetype)mgl_expressionForAttributedExpressions:
(nonnull NSArray<NSExpression *> *)attributedExpressions;

Swift

convenience init(forAttributedExpressions attributedExpressions: [NSExpression])

Parameters

attributedExpressions

The MGLAttributedExpression constant expression array.

Concatenating String Expressions

-mgl_expressionByAppendingExpression:

Returns a constant expression appending the passed expression.

Note

Both the receiver and the given expression must be an NSString constant expression type; otherwise, an exception is rised.

Declaration

Objective-C

- (nonnull instancetype)mgl_expressionByAppendingExpression:
(nonnull NSExpression *)expression;

Swift

func mgl_appending(_ expression: NSExpression) -> Self

Parameters

expression

The expression to append to the receiver.

Converting JSON Expressions

+expressionWithMGLJSONObject:

Returns an expression equivalent to the given Foundation object deserialized from JSON data.

The Foundation object is interpreted according to the Mapbox Style Specification. See the “Information for Style Authors” guide for a correspondence of operators and types between the style specification and the NSExpression representation used by this SDK.

Declaration

Objective-C

+ (nonnull instancetype)expressionWithMGLJSONObject:(nonnull id)object;

Swift

convenience init(mglJSONObject object: Any)

Parameters

object

A Foundation object deserialized from JSON data, for example using NSJSONSerialization.

Return Value

An initialized expression equivalent to object, suitable for use as the value of a style layer attribute.

mgl_jsonExpressionObject

An equivalent Foundation object that can be serialized as JSON.

The Foundation object conforms to the Mapbox Style Specification. See the “Information for Style Authors” guide for a correspondence of operators and types between the style specification and the NSExpression representation used by this SDK.

You can use NSJSONSerialization to serialize the Foundation object as data to write to a file.

Declaration

Objective-C

@property (nonatomic, readonly) id _Nonnull mgl_jsonExpressionObject;

Swift

var mgl_jsonExpressionObject: Any { get }

Localizing the Expression

-mgl_expressionLocalizedIntoLocale:

Returns a copy of the receiver localized into the given locale.

This method assumes the receiver refers to the feature attributes that are available in vector tiles supplied by the Mapbox Streets source. On iOS, the user can set the system’s preferred language in Settings, General Settings, Language & Region. On macOS, the user can set the system’s preferred language in the Language & Region pane of System Preferences.

Declaration

Objective-C

- (nonnull NSExpression *)mgl_expressionLocalizedIntoLocale:
(nullable NSLocale *)locale;

Swift

func mgl_expressionLocalized(into locale: Locale?) -> NSExpression

Parameters

locale

The locale into which labels should be localized. To use the system’s preferred language, if supported, specify nil. To use the local language, specify a locale with the identifier mul.