MBExpression Class Reference

Inherits from NSObject
Declared in MBExpression.h

Overview

This class is responsible for evaluating Mockingbird expressions.

See the documentation for the Mockingbird Data Environment for information on how to construct valid expressions.

Evaluating expressions as strings

+ asString:

Evaluates the given expression in the string context.

+ (nullable NSString *)asString:(nonnull NSString *)expr

Parameters

expr

The expression to evaluate.

Return Value

The result of evaluating the expression expr as a string.

Declared In

MBExpression.h

+ asString:error:

Evaluates the given expression in the string context.

+ (nullable NSString *)asString:(nonnull NSString *)expr error:(MBExpressionErrorPtrPtr)errPtr

Parameters

expr

The expression to evaluate.
errPtr

An optional pointer to a memory location for storing an MBExpressionError instance. If this parameter is non-nil and an error occurs during evaluation, *errPtr will be updated to point to an MBExpressionError instance describing the error.

Return Value

The result of evaluating the expression expr as a string.

Declared In

MBExpression.h

+ asString:defaultValue:

Evaluates the given expression in the string context.

+ (nullable NSString *)asString:(nonnull NSString *)expr defaultValue:(nullable NSString *)def

Parameters

expr

The expression to evaluate.
def

A default return value to use if the method would otherwise return nil.

Return Value

The result of evaluating the expression expr as a string.

Declared In

MBExpression.h

+ asString:inVariableSpace:defaultValue:error:

Evaluates the given expression in the string context.

+ (nullable NSString *)asString:(nonnull NSString *)expr inVariableSpace:(nonnull MBVariableSpace *)space defaultValue:(nullable NSString *)def error:(MBExpressionErrorPtrPtr)errPtr

Parameters

expr

The expression to evaluate.
space

The MBVariableSpace instance to use for evaluating the expression. This allows the use of variable spaces other than the instance associated with the active MBEnvironment. Must not be nil.
def

A default return value to use if the method would otherwise return nil.
errPtr

An optional pointer to a memory location for storing an MBExpressionError instance. If this parameter is non-nil and an error occurs during evaluation, *errPtr will be updated to point to an MBExpressionError instance describing the error.

Return Value

The result of evaluating the expression expr as a string.

Declared In

MBExpression.h

Evaluating expressions as objects with string interpolation

+ asObject:

Evaluates the given expression in the object context. String interpolation may be used if the expression references more than one value.

+ (nullable id)asObject:(nonnull NSString *)expr

Parameters

expr

The expression to evaluate.

Return Value

The result of evaluating the expression expr as an object.

Discussion

If an expression contains a reference to only a single value (and does not also contain any text literals), the return value will be whatever NSObject instance is referenced by the expression.

String interpolation only applies when an expression references more than one value, eg. “Hello $firstName! I haven't seen you since $lastTime.”

With string interpolation, if an expression contains references to multiple discrete values or if it contains one or more text literals, those values are coerced into strings and concatenated before being returned as a single NSString instance.

If you know you’ll be using an object expression that will result in string interpolation being used, consider using the asString: method variants instead.

You can also use one of the asArray: method variants to retrieve multiple values from within an expression without them being concatenated into a single string.

Declared In

MBExpression.h

+ asObject:error:

Evaluates the given expression in the object context. String interpolation may be used if the expression references more than one value.

+ (nullable id)asObject:(nonnull NSString *)expr error:(MBExpressionErrorPtrPtr)errPtr

Parameters

expr

The expression to evaluate.
errPtr

An optional pointer to a memory location for storing an MBExpressionError instance. If this parameter is non-nil and an error occurs during evaluation, *errPtr will be updated to point to an MBExpressionError instance describing the error.

Return Value

The result of evaluating the expression expr as an object.

Discussion

If an expression contains a reference to only a single value (and does not also contain any text literals), the return value will be whatever NSObject instance is referenced by the expression.

String interpolation only applies when an expression references more than one value, eg. “Hello $firstName! I haven't seen you since $lastTime.”

With string interpolation, if an expression contains references to multiple discrete values or if it contains one or more text literals, those values are coerced into strings and concatenated before being returned as a single NSString instance.

If you know you’ll be using an object expression that will result in string interpolation being used, consider using the asString: method variants instead.

You can also use one of the asArray: method variants to retrieve multiple values from within an expression without them being concatenated into a single string.

Declared In

MBExpression.h

+ asObject:defaultValue:

Evaluates the given expression in the object context. String interpolation may be used if the expression references more than one value.

+ (nullable id)asObject:(nonnull NSString *)expr defaultValue:(nullable id)def

Parameters

expr

The expression to evaluate.
def

A default return value to use if the method would otherwise return nil.

Return Value

The result of evaluating the expression expr as an object.

Discussion

If an expression contains a reference to only a single value (and does not also contain any text literals), the return value will be whatever NSObject instance is referenced by the expression.

String interpolation only applies when an expression references more than one value, eg. “Hello $firstName! I haven't seen you since $lastTime.”

With string interpolation, if an expression contains references to multiple discrete values or if it contains one or more text literals, those values are coerced into strings and concatenated before being returned as a single NSString instance.

If you know you’ll be using an object expression that will result in string interpolation being used, consider using the asString: method variants instead.

You can also use one of the asArray: method variants to retrieve multiple values from within an expression without them being concatenated into a single string.

Declared In

MBExpression.h

+ asObject:inVariableSpace:defaultValue:error:

Evaluates the given expression in the object context. String interpolation may be used if the expression references more than one value.

+ (nullable id)asObject:(nonnull NSString *)expr inVariableSpace:(nonnull MBVariableSpace *)space defaultValue:(nullable id)def error:(MBExpressionErrorPtrPtr)errPtr

Parameters

expr

The expression to evaluate.
space

The MBVariableSpace instance to use for evaluating the expression. This allows the use of variable spaces other than the instance associated with the active MBEnvironment. Must not be nil.
def

A default return value to use if the method would otherwise return nil.
errPtr

An optional pointer to a memory location for storing an MBExpressionError instance. If this parameter is non-nil and an error occurs during evaluation, *errPtr will be updated to point to an MBExpressionError instance describing the error.

Return Value

The result of evaluating the expression expr as an object.

Discussion

If an expression contains a reference to only a single value (and does not also contain any text literals), the return value will be whatever NSObject instance is referenced by the expression.

String interpolation only applies when an expression references more than one value, eg. “Hello $firstName! I haven't seen you since $lastTime.”

With string interpolation, if an expression contains references to multiple discrete values or if it contains one or more text literals, those values are coerced into strings and concatenated before being returned as a single NSString instance.

If you know you’ll be using an object expression that will result in string interpolation being used, consider using the asString: method variants instead.

You can also use one of the asArray: method variants to retrieve multiple values from within an expression without them being concatenated into a single string.

Declared In

MBExpression.h

Evaluating expressions as objects without string interpolation

+ asArray:

Evaluates the given expression in the object context without using string interpolation. Discrete values within the expression are returned as items in an array.

+ (nullable NSArray *)asArray:(nonnull NSString *)expr

Parameters

expr

The expression to evaluate.

Return Value

The result of evaluating the expression expr as an array of objects.

Discussion

An expression may contain zero or more literal values and inner expressions; this method gathers any individual literals and inner expression values encountered while evaluating the passed-in expression, and returns an NSArray containing the results.

Declared In

MBExpression.h

+ asArray:error:

Evaluates the given expression in the object context without using string interpolation. Discrete values within the expression are returned as items in an array.

+ (nullable NSArray *)asArray:(nonnull NSString *)expr error:(MBExpressionErrorPtrPtr)errPtr

Parameters

expr

The expression to evaluate.
errPtr

An optional pointer to a memory location for storing an MBExpressionError instance. If this parameter is non-nil and an error occurs during evaluation, *errPtr will be updated to point to an MBExpressionError instance describing the error.

Return Value

The result of evaluating the expression expr as an array of objects.

Discussion

An expression may contain zero or more literal values and inner expressions; this method gathers any individual literals and inner expression values encountered while evaluating the passed-in expression, and returns an NSArray containing the results.

Declared In

MBExpression.h

+ asArray:inVariableSpace:error:

Evaluates the given expression in the object context without using string interpolation. Discrete values within the expression are returned as items in an array.

+ (nullable NSArray *)asArray:(nonnull NSString *)expr inVariableSpace:(nonnull MBVariableSpace *)space error:(MBExpressionErrorPtrPtr)errPtr

Parameters

expr

The expression to evaluate.
space

The MBVariableSpace instance to use for evaluating the expression. This allows the use of variable spaces other than the instance associated with the active MBEnvironment. Must not be nil.
errPtr

An optional pointer to a memory location for storing an MBExpressionError instance. If this parameter is non-nil and an error occurs during evaluation, *errPtr will be updated to point to an MBExpressionError instance describing the error.

Return Value

The result of evaluating the expression expr as an array of objects.

Discussion

An expression may contain zero or more literal values and inner expressions; this method gathers any individual literals and inner expression values encountered while evaluating the passed-in expression, and returns an NSArray containing the results.

Declared In

MBExpression.h

Evaluating expressions as numeric values

+ asNumber:

Evaluates the given expression in the numeric context, coercing the result into a number if necessary (and possible).

+ (nullable NSDecimalNumber *)asNumber:(nonnull NSString *)expr

Parameters

expr

The expression to evaluate.

Return Value

The result of evaluating the expression expr as a numeric expression.

Discussion

Mathematical expressions may be used in the numeric context.

Declared In

MBExpression.h

+ asNumber:error:

Evaluates the given expression in the numeric context, coercing the result into a number if necessary (and possible).

+ (nullable NSDecimalNumber *)asNumber:(nonnull NSString *)expr error:(MBExpressionErrorPtrPtr)errPtr

Parameters

expr

The expression to evaluate.
errPtr

An optional pointer to a memory location for storing an MBExpressionError instance. If this parameter is non-nil and an error occurs during evaluation, *errPtr will be updated to point to an MBExpressionError instance describing the error.

Return Value

The result of evaluating the expression expr as a numeric expression.

Discussion

Mathematical expressions may be used in the numeric context.

Declared In

MBExpression.h

+ asNumber:defaultValue:

Evaluates the given expression in the numeric context, coercing the result into a number if necessary (and possible).

+ (nullable NSDecimalNumber *)asNumber:(nonnull NSString *)expr defaultValue:(nullable NSDecimalNumber *)def

Parameters

expr

The expression to evaluate.
def

A default return value to use if the method would otherwise return nil.

Return Value

The result of evaluating the expression expr as a numeric expression.

Discussion

Mathematical expressions may be used in the numeric context.

Declared In

MBExpression.h

+ asNumber:inVariableSpace:defaultValue:error:

Evaluates the given expression in the numeric context, coercing the result into a number if necessary (and possible).

+ (nullable NSDecimalNumber *)asNumber:(nonnull NSString *)expr inVariableSpace:(nonnull MBVariableSpace *)space defaultValue:(nullable NSDecimalNumber *)def error:(MBExpressionErrorPtrPtr)errPtr

Parameters

expr

The expression to evaluate.
space

The MBVariableSpace instance to use for evaluating the expression. This allows the use of variable spaces other than the instance associated with the active MBEnvironment. Must not be nil.
def

A default return value to use if the method would otherwise return nil.
errPtr

An optional pointer to a memory location for storing an MBExpressionError instance. If this parameter is non-nil and an error occurs during evaluation, *errPtr will be updated to point to an MBExpressionError instance describing the error.

Return Value

The result of evaluating the expression expr as a numeric expression.

Discussion

Mathematical expressions may be used in the numeric context.

Declared In

MBExpression.h

Evaluating expressions as boolean values

+ asBoolean:

Evaluates the given expression in the boolean context.

+ (BOOL)asBoolean:(nullable NSString *)expr

Parameters

expr

The expression to evaluate.

Return Value

The result of evaluating the expression expr as a boolean expression.

Declared In

MBExpression.h

+ asBoolean:error:

Evaluates the given expression in the boolean context.

+ (BOOL)asBoolean:(nullable NSString *)expr error:(MBExpressionErrorPtrPtr)errPtr

Parameters

expr

The expression to evaluate.
errPtr

An optional pointer to a memory location for storing an MBExpressionError instance. If this parameter is non-nil and an error occurs during evaluation, *errPtr will be updated to point to an MBExpressionError instance describing the error.

Return Value

The result of evaluating the expression expr as a boolean expression.

Declared In

MBExpression.h

+ asBoolean:defaultValue:

Evaluates the given expression in the boolean context.

+ (BOOL)asBoolean:(nullable NSString *)expr defaultValue:(BOOL)def

Parameters

expr

The expression to evaluate.
def

A default return value to use if there was a problem evaluating expr.

Return Value

The result of evaluating the expression expr as a boolean expression.

Declared In

MBExpression.h

+ asBoolean:inVariableSpace:defaultValue:error:

Evaluates the given expression in the boolean context.

+ (BOOL)asBoolean:(nullable NSString *)expr inVariableSpace:(nonnull MBVariableSpace *)space defaultValue:(BOOL)def error:(MBExpressionErrorPtrPtr)errPtr

Parameters

expr

The expression to evaluate.
space

The MBVariableSpace instance to use for evaluating the expression. This allows the use of variable spaces other than the instance associated with the active MBEnvironment. Must not be nil.
def

A default return value to use if there was a problem evaluating expr.
errPtr

An optional pointer to a memory location for storing an MBExpressionError instance. If this parameter is non-nil and an error occurs during evaluation, *errPtr will be updated to point to an MBExpressionError instance describing the error.

Return Value

The result of evaluating the expression expr as a boolean expression.

Declared In

MBExpression.h

Value type coercion

+ booleanFromValue:

Exposes the mechanism the expression evaluator uses for coercing arbitrary object values into booleans.

+ (BOOL)booleanFromValue:(nullable id)val

Parameters

val

The object to interpret as a boolean

Return Value

The boolean representation of val

Declared In

MBExpression.h

+ stringFromBoolean:

Exposes the mechanism the expression evaluator uses for representing boolean values as strings.

+ (nonnull NSString *)stringFromBoolean:(BOOL)val

Parameters

val

The boolean value

Return Value

The string representation of val; either kMBMLBooleanStringTrue or kMBMLBooleanStringFalse.

Declared In

MBExpression.h

+ numberFromValue:

Exposes the mechanism the expression evaluator uses for coercing arbitrary object values into numbers.

+ (nullable NSDecimalNumber *)numberFromValue:(nullable id)val

Parameters

val

The object to interpret as a number

Return Value

If val can be interpreted as a number, the return value is an NSDecimalNumber containing that number. If val cannot be interpreted as a number, or if the resulting number is equal to [NSNumber notANumber], nil will be returned.

Declared In

MBExpression.h

Comparing values

+ value:isEqualTo:

Exposes the mechanism the expression evaluator uses for determining if two objects have equal values.

+ (BOOL)value:(nullable id)lValue isEqualTo:(nullable id)rValue

Parameters

lValue

The left value of the comparison
rValue

The right value of the comparison

Return Value

The return value of [lValue isEqual:rValue] if lValue and rValue are of the same type. Otherwise, falls back on [MBExpression compareLeftValue:lValue againstRightValue:rValue].

Declared In

MBExpression.h

+ compareLeftValue:againstRightValue:

Exposes the mechanism the expression evaluator uses to determine the relative order of two object values.

+ (NSComparisonResult)compareLeftValue:(nullable id)lValue againstRightValue:(nullable id)rValue

Parameters

lValue

The left value of the comparison
rValue

The right value of the comparison

Return Value

NSOrderedAscending if lValue is less than rValue; NSOrderedDescending if lValue is greater than rValue; NSOrderedSame if lValue is equal to rValue.

Declared In

MBExpression.h