Class: NSExpression

Inherits:
NSObject show all

Overview

NSExpression is used to represent expressions in a predicate.

Direct Known Subclasses

NSFetchRequestExpression

Class Method Summary (collapse)

Instance Method Summary (collapse)

Methods inherited from NSObject

#!, #!=, #!~, #, #==, #===, #=~, #Rational, #__callee__, #__method__, #__send__, #__type__, `, alloc, allocWithZone:, #autoContentAccessingProxy, autoload, autoload?, autorelease_pool, #awakeAfterUsingCoder:, binding, block_given?, caller, cancelPreviousPerformRequestsWithTarget:, cancelPreviousPerformRequestsWithTarget:selector:object:, catch, class, classFallbacksForKeyedArchiver, #classForCoder, #classForKeyedArchiver, classForKeyedUnarchiver, #clone, conformsToProtocol:, #copy, copyWithZone:, #dealloc, #define_singleton_method, description, display, #doesNotRecognizeSelector:, #dup, #enum_for, #eql?, #equal?, #extend, fail, #finalize, format, #forwardInvocation:, #forwardingTargetForSelector:, framework, #freeze, #frozen?, getpass, gets, global_variables, #init, initialize, #initialize_clone, #initialize_copy, #initialize_dup, #inspect, instanceMethodForSelector:, instanceMethodSignatureForSelector:, #instance_eval, #instance_exec, #instance_of?, #instance_variable_defined?, #instance_variable_get, #instance_variable_set, #instance_variables, instancesRespondToSelector:, isSubclassOfClass:, #is_a?, iterator?, #kind_of?, lambda, load, load_bridge_support_file, load_plist, local_variables, loop, #method, #methodForSelector:, #methodSignatureForSelector:, #methods, #mutableCopy, mutableCopyWithZone:, new, #nil?, open, p, #performSelector:onThread:withObject:waitUntilDone:, #performSelector:onThread:withObject:waitUntilDone:modes:, #performSelector:withObject:afterDelay:, #performSelector:withObject:afterDelay:inModes:, #performSelectorInBackground:withObject:, #performSelectorOnMainThread:withObject:waitUntilDone:, #performSelectorOnMainThread:withObject:waitUntilDone:modes:, print, printf, #private_methods, proc, #protected_methods, #public_method, #public_methods, #public_send, putc, puts, raise, rand, readline, readlines, #replacementObjectForCoder:, #replacementObjectForKeyedArchiver:, require, resolveClassMethod:, resolveInstanceMethod:, #respond_to?, #respond_to_missing?, select, #send, setVersion:, #singleton_methods, sprintf, srand, superclass, #taint, #tainted?, #tap, test, throw, #to_plist, #to_s, trace_var, trap, #trust, #untaint, untrace_var, #untrust, #untrusted?, version

Constructor Details

This class inherits a constructor from NSObject

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class NSObject

Class Method Details

+ (NSExpression) expressionForAggregate(collection)

Returns a new aggregate expression for a given collection.

Parameters:

Returns:

  • (NSExpression) —

    A new expression that contains the expressions in collection.

+ (NSExpression) expressionForBlock(block, arguments:arguments)

Creates an NSExpression object that will use the Block for evaluating objects.

Parameters:

  • block —

    The Block is applied to the object to be evaluated.The Block takes three arguments and returns a value:evaluatedObjectThe object to be evaluated.expressionsAn array of predicate expressions that evaluates to a collection.contextA dictionary that the expression can use to store temporary state for one predicate evaluation.Note that context is mutable, and that it can only be accessed during the evaluation of the expression. You must not attempt to retain it for use elsewhere. ]The Block returns the evaluatedObject.

  • evaluatedObject —

    The object to be evaluated.

  • expressions —

    An array of predicate expressions that evaluates to a collection.

  • context —

    A dictionary that the expression can use to store temporary state for one predicate evaluation.Note that context is mutable, and that it can only be accessed during the evaluation of the expression. You must not attempt to retain it for use elsewhere. ]

  • arguments —

    An array containing NSExpression objects that will be used as parameters during the invocation of selector.For a selector taking no parameters, the array should be empty. For a selector taking one or more parameters, the array should contain one NSExpression object which will evaluate to an instance of the appropriate type for each parameter.If there is a mismatch between the number of parameters expected and the number you provide during evaluation, an exception may be raised or missing parameters may simply be replaced by nil (which occurs depends on how many parameters are provided, and whether you have over- or underflow).See expressionForFunction:arguments: for a complete list of arguments.

Returns:

  • (NSExpression) —

    An expression that filters a collection using the specified Block.

+ (NSExpression) expressionForConstantValue(obj)

Returns a new expression that represents a given constant value.

Parameters:

  • obj (Object) —

    The constant value the new expression is to represent.

Returns:

  • (NSExpression) —

    A new expression that represents the constant value, obj.

+ (NSExpression) expressionForEvaluatedObject

Returns a new expression that represents the object being evaluated.

Returns:

  • (NSExpression) —

    A new expression that represents the object being evaluated.

+ (NSExpression) expressionForFunction(name, arguments:parameters)

Returns a new expression that will invoke one of the predefined functions. The name parameter can be one of the following predefined functions.Function Parameter ReturnsAvailability average: An NSArray object containing NSExpression objects representing numbers An NSNumber object (the average of values in the array)OS X v10.4 and later sum: An NSArray object containing NSExpression objects representing numbers An NSNumber object (the sum of values in the array)OS X v10.4 and later count: An NSArray object containing NSExpression objects representing numbers An NSNumber object (the number of elements in the array)OS X v10.4 and later min: An NSArray object containing NSExpression objects representing numbers An NSNumber object (the minimum of the values in the array)OS X v10.4 and later max: An NSArray object containing NSExpression objects representing numbersAn NSNumber object (the maximum of the values in the array)OS X v10.4 and latermedian:An NSArray object containing NSExpression objects representing numbersAn NSNumber object (the median of the values in the array)OS X v10.5 and latermode: An NSArray object containing NSExpression objects representing numbersAn NSArray object (the mode of the values in the array)OS X v10.5 and laterstddev:An NSArray object containing NSExpression objects representing numbersAn NSNumber object (the standard deviation of the values in the array)OS X v10.5 and lateradd:to: An NSArray object containing two NSExpression objects representing numbersAn NSNumber object (the sum of the values in the array)OS X v10.5 and laterfrom:subtract:An NSArray object containing two NSExpression objects representing numbersAn NSNumber object (the result of subtracting the second value in the array from the first value in the array)OS X v10.5 and latermultiply:by:An NSArray object containing two NSExpression objects representing numbersAn NSNumber object (the result of multiplying the values in the array)OS X v10.5 and laterdivide:by: An NSArray object containing two NSExpression objects representing numbersAn NSNumber object (the result of dividing the first value in the array by the second value in the array)OS X v10.5 and latermodulus:by:An NSArray object containing two NSExpression objects representing numbersAn NSNumber object (the remainder of dividing the first value in the array by the second value in the array)OS X v10.5 and latersqrt: An NSArray object containing one NSExpression object representing a numberAn NSNumber object (the square root of the value in the array)OS X v10.5 and laterlog:An NSArray object containing one NSExpression object representing a numberAn NSNumber object (the log of the value in the array)OS X v10.5 and laterln: An NSArray object containing one NSExpression object representing a numberAn NSNumber object (the natural log of the value in the array)OS X v10.5 and laterraise:toPower: An NSArray object containing two NSExpression objects representing numbersAn NSNumber object (the result of raising the first value in the array to the power of the second value in the array)OS X v10.5 and laterexp: An NSArray object containing one NSExpression object representing a numberAn NSNumber object (the base-e exponential of the value in the array)OS X v10.5 and laterceiling:An NSArray object containing one NSExpression object representing a numberAn NSNumber object (the smallest integral value not less than the value in the array)OS X v10.5 and laterabs:An NSArray object containing one NSExpression object representing a numberAn NSNumber object (the absolute value of the value in the array)OS X v10.5 and latertrunc:An NSArray object containing one NSExpression object representing a numberAn NSNumber object (the integral value nearest to but no greater than the value in the array)OS X v10.5 and laterrandomnilAn NSNumber object (a random integer value)OS X v10.5 and laterrandom:An NSArray object containing one NSExpression object representing a numberAn NSNumber object (a random integer value between 0 and the value in the array (exclusive))OS X v10.5 and laternow nilAn [NSDate] object (the current date and time)OS X v10.5 and laterfloor:An NSArray object containing one NSExpression object representing a numberAn NSNumber objectiOS 3.0 and lateruppercase:An NSArray object containing one NSExpression object representing a stringAn NSString objectiOS 3.0 and laterlowercase:An NSArray object containing one NSExpression object representing a stringAn NSString objectiOS 3.0 and laterbitwiseAnd:with:An NSArray object containing two NSExpression objects representing numbersAn NSNumber object (the number is treated as an NSInteger)iOS 3.0 and laterbitwiseOr:with:An NSArray object containing two NSExpression objects representing numbersAn NSNumber object (the number is treated as an NSInteger)iOS 3.0 and laterbitwiseXor:with:An NSArray object containing two NSExpression objects representing numbersAn NSNumber object (the number is treated as an NSInteger)iOS 3.0 and laterleftshift:by:An NSArray object containing two NSExpression objects representing numbersAn NSNumber object (the number is treated as an NSInteger)iOS 3.0 and laterrightshift:by:An NSArray object containing two NSExpression objects representing numbersAn NSNumber object (the number is treated as an NSInteger)iOS 3.0 and lateronesComplement:An NSArray object containing one NSExpression object representing a numberAn NSNumber object (the number is treated as an NSInteger)iOS 3.0 and laternoindex:An NSArray object containing an NSExpression objectThe result of evaluating the parameter as though the noindex: function expression didn’t exist.iOS 3.0 and laterThis method raises an exception immediately if the selector is invalid; it raises an exception at runtime if the parameters are incorrect.The parameters argument is a collection containing an expression which evaluates to a collection, as illustrated in the following examples:

Parameters:

  • name (String) —

    The name of the function to invoke.

  • parameters (Array) —

    An array containing NSExpression objects that will be used as parameters during the invocation of selector.For a selector taking no parameters, the array should be empty. For a selector taking one or more parameters, the array should contain one NSExpression object which will evaluate to an instance of the appropriate type for each parameter.If there is a mismatch between the number of parameters expected and the number you provide during evaluation, an exception may be raised or missing parameters may simply be replaced by nil (which occurs depends on how many parameters are provided, and whether you have over- or underflow).

Returns:

  • (NSExpression) —

    A new expression that invokes the function name using the parameters in parameters.

+ (NSExpression) expressionForFunction(target, selectorName:name, arguments:parameters)

Returns an expression which will return the result of invoking on a given target a selector with a given name using given arguments. See the description of expressionForFunction:arguments: for examples of how to construct the parameter array.

Parameters:

  • target (NSExpression) —

    An NSExpression object which will evaluate an object on which the selector identified by name may be invoked.

  • name (String) —

    The name of the method to be invoked.

  • parameters (Array) —

    An array containing NSExpression objects which can be evaluated to provide parameters for the method specified by name.

Returns:

  • (NSExpression) —

    An expression which will return the result of invoking the selector named name on the result of evaluating the target expression with the parameters specified by evaluating the elements of parameters.

+ (NSExpression) expressionForIntersectSet(left, with:right)

Returns a new NSExpression object that represent the intersection of a given set and collection.

Parameters:

Returns:

+ (NSExpression) expressionForKeyPath(keyPath)

Returns a new expression that invokes valueForKeyPath: with a given key path.

Parameters:

  • keyPath (String) —

    The key path that the new expression should evaluate.

Returns:

  • (NSExpression) —

    A new expression that invokes valueForKeyPath: with keyPath.

+ (NSExpression) expressionForMinusSet(left, with:right)

Returns a new NSExpression object that represent the subtraction of a given collection from a given set.

Parameters:

Returns:

+ (NSExpression) expressionForSubquery(expression, usingIteratorVariable:variable, predicate:predicate)

Returns an expression that filters a collection by storing elements in the collection in a given variable and keeping the elements for which qualifier returns true. This method creates a sub-expression, evaluation of which returns a subset of a collection of objects. It allows you to create sophisticated queries across relationships, such as a search for multiple correlated values on the destination object of a relationship.For example, suppose you have an Apartment entity that has a to-many relationship to a Resident entity, and that you want to create a query for all apartments inhabited by a resident whose first name is “Jane” and whose last name is “Doe”. Using only API available for OS X v 10.4, you could try the predicate:but this will always return false since resident.firstname and resident.lastname both return collections. You could also try:but this is also flawed—it returns true if there are two residents, one of whom is John Doe and one of whom is Jane Smith. The only way to find the desired apartments is to do two passes: one through residents to find “Jane Doe”, and one through apartments to find the ones where our Jane Does reside.Subquery expressions provide a way to encapsulate this type of qualification into a single query.The string format for a subquery expression is:where expression is a predicate expression that evaluates to a collection, variableExpression is an expression which will be used to contain each individual element of collection, and predicate is the predicate used to determine whether the element belongs in the result collection.Using subqueries, the apartment query could be reformulated as or

Parameters:

  • expression (NSExpression) —

    A predicate expression that evaluates to a collection.

  • variable (String) —

    Used as a local variable, and will shadow any instances of variable in the bindings dictionary. The variable is removed or the old value replaced once evaluation completes.

  • predicate (Object) —

    The predicate used to determine whether the element belongs in the result collection.

Returns:

  • (NSExpression) —

    An expression that filters a collection by storing elements in the collection in the variable variable and keeping the elements for which qualifier returns true

+ (NSExpression) expressionForUnionSet(left, with:right)

Returns a new NSExpression object that represent the union of a given set and collection.

Parameters:

Returns:

+ (NSExpression) expressionForVariable(string)

Returns a new expression that extracts a value from the variable bindings dictionary for a given key.

Parameters:

  • string (String) —

    The key for the variable to extract from the variable bindings dictionary.

Returns:

  • (NSExpression) —

    A new expression that extracts from the variable bindings dictionary the value for the key string.

+ (NSExpression) expressionWithFormat(expressionFormat, ...)

Initializes the receiver with the specified expression arguments.

Parameters:

  • expressionFormat, —

    The expression format.

  • ... —

    A comma-separated list of arguments to substitute into format. The list is terminated by nil.

Returns:

+ (NSExpression) expressionWithFormat(expressionFormat, argumentArray:arguments)

Initializes the receiver with the specified expression format and array of arguments.

Parameters:

  • expressionFormat (String) —

    The expression format.

  • arguments (Array) —

    An array of arguments to be used with the expressionFormat string.

Returns:

+ (NSExpression) expressionWithFormat(expressionFormat, arguments:argList)

Initializes the receiver with the specified expression format and arguments list.

Parameters:

  • expressionFormat (String) —

    The expression format.

  • argList (va_list) —

    A list of arguments to be inserted into the expressionFormat string. The argument list is terminated by nil.

Returns:

Instance Method Details

- (Array) arguments

Returns the arguments for the receiver. This method raises an exception if it is not applicable to the receiver.

Returns:

  • (Array) —

    The arguments for the receiver—that is, the array of expressions that will be passed as parameters during invocation of the selector on the operand of a function expression.

- (Object) collection

Returns the collection of expressions in an aggregate expression, or the collection element of a subquery expression. This method raises an exception if it is not applicable to the receiver.

Returns:

  • (Object) —

    Returns the collection of expressions in an aggregate expression, or the collection element of a subquery expression.

- (Object) constantValue

Returns the constant value of the receiver. This method raises an exception if it is not applicable to the receiver.

Returns:

  • (Object) —

    The constant value of the receiver.

- (Object) expressionBlock

Returns the expression’s expression Block.

Returns:

  • (Object) —

    The expression’s expression Block as created in expressionForBlock:arguments:.

- (NSExpressionType) expressionType

Returns the expression type for the receiver. This method raises an exception if it is not applicable to the receiver.

Returns:

  • (NSExpressionType) —

    The expression type for the receiver.

- (Object) expressionValueWithObject(object, context:context)

Evaluates an expression using a given object and context.

Parameters:

  • object (Object) —

    The object against which the receiver is evaluated.

  • context (Hash) —

    A dictionary that the expression can use to store temporary state for one predicate evaluation. Can be nil.Note that context is mutable, and that it can only be accessed during the evaluation of the expression. You must not attempt to retain it for use elsewhere. ]

Returns:

  • (Object) —

    The evaluated object.

- (String) function

Returns the function for the receiver. This method raises an exception if it is not applicable to the receiver.

Returns:

  • (String) —

    The function for the receiver.

- (Object) initWithExpressionType(type)

Initializes the receiver with the specified expression type.

Parameters:

  • type (NSExpressionType) —

    The type of the new expression, as defined by NSExpressionType.

Returns:

- (String) keyPath

Returns the key path for the receiver. This method raises an exception if it is not applicable to the receiver.

Returns:

  • (String) —

    The key path for the receiver.

- (NSExpression) leftExpression

Returns the left expression of an aggregate expression. This method raises an exception if it is not applicable to the receiver.

Returns:

  • (NSExpression) —

    The left expression of a set expression.

- (NSExpression) operand

Returns the operand for the receiver. The object is the result of evaluating a key path or one of the defined functions. This method raises an exception if it is not applicable to the receiver.

Returns:

  • (NSExpression) —

    The operand for the receiver—that is, the object on which the selector will be invoked.

- (NSPredicate) predicate

Return the predicate of a subquery expression. This method raises an exception if it is not applicable to the receiver.

Returns:

  • (NSPredicate) —

    The predicate of a subquery expression.

- (NSExpression) rightExpression

Returns the right expression of an aggregate expression. This method raises an exception if it is not applicable to the receiver.

Returns:

  • (NSExpression) —

    The right expression of a set expression.

- (String) variable

Returns the variable for the receiver. This method raises an exception if it is not applicable to the receiver.

Returns:

  • (String) —

    The variable for the receiver.