NSComparisonPredicate Class Reference

Inherits from	NSPredicate : NSObject
Conforms to	NSCoding (NSPredicate) NSCopying (NSPredicate) NSObject (NSObject)
Framework	/System/Library/Frameworks/Foundation.framework
Availability	Available in OS X v10.4 and later.
Companion guide	Predicate Programming Guide
Declared in	NSComparisonPredicate.h
Related sample code	Core Data Utility iSpend PhotoSearch Spotlighter

Overview

NSComparisonPredicate is a subclass of NSPredicate that you use to compare expressions.

You use comparison predicates to compare the results of two expressions. You create a comparison predicate with an operator, a left expression, and a right expression. You represent the expressions using instances of the NSExpression class. When you evaluate the predicate, it returns as a BOOL value the result of invoking the operator with the results of evaluating the expressions.

Tasks

Creating Comparison Predicates

Getting Information About a Comparison Predicate

Class Methods

predicateWithLeftExpression:rightExpression:customSelector:

Returns a new predicate formed by combining the left and right expressions using a given selector.

+ (NSPredicate *)predicateWithLeftExpression:(NSExpression *)lhs rightExpression:(NSExpression *)rhs customSelector:(SEL)selector

Parameters

lhs: The left hand side expression.
rhs: The right hand side expression.
selector: The selector to use for comparison. The method defined by the selector must take a single argument and return a BOOL value.

Return Value

A new predicate formed by combining the left and right expressions using selector.

Availability

Available in OS X v10.4 and later.

Declared In

NSComparisonPredicate.h

predicateWithLeftExpression:rightExpression:modifier:type:options:

Creates and returns a predicate of a given type formed by combining given left and right expressions using a given modifier and options.

+ (NSPredicate *)predicateWithLeftExpression:(NSExpression *)lhs rightExpression:(NSExpression *)rhs modifier:(NSComparisonPredicateModifier)modifier type:(NSPredicateOperatorType)type options:(NSUInteger)options

Parameters

lhs: The left hand expression.
rhs: The right hand expression.
modifier: The modifier to apply.
type: The predicate operator type.
options: The options to apply (see “NSComparisonPredicate Options”). For no options, pass 0.

Return Value

A new predicate of type type formed by combining the given left and right expressions using the modifier and options.

Availability

Available in OS X v10.4 and later.

Related Sample Code

Declared In

NSComparisonPredicate.h

Instance Methods

comparisonPredicateModifier

Returns the comparison predicate modifier for the receiver.

- (NSComparisonPredicateModifier)comparisonPredicateModifier

Return Value

The comparison predicate modifier for the receiver.

Discussion

The default value is NSDirectPredicateModifier.

Availability

Available in OS X v10.4 and later.

Related Sample Code

PhotoSearch

Declared In

NSComparisonPredicate.h

customSelector

Returns the selector for the receiver.

- (SEL)customSelector

Return Value

The selector for the receiver, or NULL if there is none.

Availability

Available in OS X v10.4 and later.

Declared In

NSComparisonPredicate.h

initWithLeftExpression:rightExpression:customSelector:

Initializes a predicate formed by combining given left and right expressions using a given selector.

- (id)initWithLeftExpression:(NSExpression *)lhs rightExpression:(NSExpression *)rhs customSelector:(SEL)selector

Parameters

lhs: The left hand expression.
rhs: The right hand expression.
selector: The selector to use. The method defined by the selector must take a single argument and return a BOOL value.

Return Value

The receiver, initialized by combining the left and right expressions using selector.

Availability

Available in OS X v10.4 and later.

Declared In

NSComparisonPredicate.h

initWithLeftExpression:rightExpression:modifier:type:options:

Initializes a predicate to a given type formed by combining given left and right expressions using a given modifier and options.

- (id)initWithLeftExpression:(NSExpression *)lhs rightExpression:(NSExpression *)rhs modifier:(NSComparisonPredicateModifier)modifier type:(NSPredicateOperatorType)type options:(NSUInteger)options

Parameters

lhs: The left hand expression.
rhs: The right hand expression.
modifier: The modifier to apply.
type: The predicate operator type.
options: The options to apply (see “NSComparisonPredicate Options”). For no options, pass 0.

Return Value

The receiver, initialized to a predicate of type type formed by combining the left and right expressions using the modifier and options.

Availability

Available in OS X v10.4 and later.

Declared In

NSComparisonPredicate.h

leftExpression

Returns the left expression for the receiver.

- (NSExpression *)leftExpression

Return Value

The left expression for the receiver, or nil if there is none.

Availability

Available in OS X v10.4 and later.

Related Sample Code

PhotoSearch

Declared In

NSComparisonPredicate.h

options

Returns the options that are set for the receiver.

- (NSUInteger)options

Return Value

The options that are set for the receiver.

Availability

Available in OS X v10.4 and later.

Related Sample Code

PhotoSearch

Declared In

NSComparisonPredicate.h

predicateOperatorType

Returns the predicate type for the receiver.

- (NSPredicateOperatorType)predicateOperatorType

Return Value

The predicate type for the receiver.

Availability

Available in OS X v10.4 and later.

Related Sample Code

PhotoSearch

Declared In

NSComparisonPredicate.h

rightExpression

Returns the right expression for the receiver.

- (NSExpression *)rightExpression

Return Value

The right expression for the receiver, or nil if there is none.

Availability

Available in OS X v10.4 and later.

Related Sample Code

PhotoSearch

Declared In

NSComparisonPredicate.h

Constants

NSComparisonPredicateModifier

These constants describe the possible types of modifier for NSComparisonPredicate.

enum {
   NSDirectPredicateModifier = 0,
   NSAllPredicateModifier,
   NSAnyPredicateModifier,
};
typedef NSUInteger NSComparisonPredicateModifier;

Constants

NSDirectPredicateModifier

A predicate to compare directly the left and right hand sides.

Available in OS X v10.4 and later.

Declared in NSComparisonPredicate.h.

NSAllPredicateModifier

A predicate to compare all entries in the destination of a to-many relationship.

The left hand side must be a collection. The corresponding predicate compares each value in the left hand side with the right hand side, and returns NO when it finds the first mismatch—or YES if all match.

Available in OS X v10.4 and later.

Declared in NSComparisonPredicate.h.

NSAnyPredicateModifier

A predicate to match with any entry in the destination of a to-many relationship.

The left hand side must be a collection. The corresponding predicate compares each value in the left hand side against the right hand side and returns YES when it finds the first match—or NO if no match is found

Available in OS X v10.4 and later.

Declared in NSComparisonPredicate.h.

Availability

Available in OS X v10.4 and later.

Declared In

NSComparisonPredicate.h

NSComparisonPredicate Options

These constants describe the possible types of string comparison for NSComparisonPredicate. These options are supported for LIKE as well as all of the equality/comparison operators.

enum {
   NSCaseInsensitivePredicateOption = 0x01,
   NSDiacriticInsensitivePredicateOption = 0x02,
   NSNormalizedPredicateOption = 0x04,
   NSLocaleSensitivePredicateOption = 0x08
};
typedef NSUInteger NSComparisonPredicateOptions;

Constants

NSCaseInsensitivePredicateOption

A case-insensitive predicate.

You represent this option in a predicate format string using a [c] following a string operation (for example, "NeXT" like[c] "next").

Available in OS X v10.4 and later.

Declared in NSComparisonPredicate.h.

NSDiacriticInsensitivePredicateOption

A diacritic-insensitive predicate.

You represent this option in a predicate format string using a [d] following a string operation (for example, "naïve" like[d] "naive").

Available in OS X v10.4 and later.

Declared in NSComparisonPredicate.h.

NSNormalizedPredicateOption

Indicates that the strings to be compared have been preprocessed.

This option supersedes NSCaseInsensitivePredicateOption and NSDiacriticInsensitivePredicateOption, and is intended as a performance optimization option.

You represent this option in a predicate format string using a [n] following a string operation (for example, "WXYZlan" matches[n] ".lan").

Available in OS X v10.7 and later.

Declared in NSComparisonPredicate.h.

NSLocaleSensitivePredicateOption

Indicates that strings to be compared using <, <=, =, =>, > should be handled in a locale-aware fashion.

You represent this option in a predicate format string using a [l] following one of the <, <=, =, =>, > operators (for example, "straße" >[l] "strasse").

Availability

Available in OS X v10.7 and later.

Declared In

NSComparisonPredicate.h

NSPredicateOperatorType

Defines the type of comparison for NSComparisonPredicate.

enum {
   NSLessThanPredicateOperatorType = 0,
   NSLessThanOrEqualToPredicateOperatorType,
   NSGreaterThanPredicateOperatorType,
   NSGreaterThanOrEqualToPredicateOperatorType,
   NSEqualToPredicateOperatorType,
   NSNotEqualToPredicateOperatorType,
   NSMatchesPredicateOperatorType,
   NSLikePredicateOperatorType,
   NSBeginsWithPredicateOperatorType,
   NSEndsWithPredicateOperatorType,
   NSInPredicateOperatorType,
   NSCustomSelectorPredicateOperatorType,
   NSContainsPredicateOperatorType,
   NSBetweenPredicateOperatorType
};
typedef NSUInteger NSPredicateOperatorType;

Constants

NSLessThanPredicateOperatorType

A less-than predicate.

Available in OS X v10.4 and later.

Declared in NSComparisonPredicate.h.

NSLessThanOrEqualToPredicateOperatorType

A less-than-or-equal-to predicate.

Available in OS X v10.4 and later.

Declared in NSComparisonPredicate.h.

NSGreaterThanPredicateOperatorType

A greater-than predicate.

Available in OS X v10.4 and later.

Declared in NSComparisonPredicate.h.

NSGreaterThanOrEqualToPredicateOperatorType

A greater-than-or-equal-to predicate.

Available in OS X v10.4 and later.

Declared in NSComparisonPredicate.h.

NSEqualToPredicateOperatorType

An equal-to predicate.

Available in OS X v10.4 and later.

Declared in NSComparisonPredicate.h.

NSNotEqualToPredicateOperatorType

A not-equal-to predicate.

Available in OS X v10.4 and later.

Declared in NSComparisonPredicate.h.

NSMatchesPredicateOperatorType

A full regular expression matching predicate.

Available in OS X v10.4 and later.

Declared in NSComparisonPredicate.h.

NSLikePredicateOperatorType

A simple subset of the MATCHES predicate, similar in behavior to SQL LIKE.

Available in OS X v10.4 and later.

Declared in NSComparisonPredicate.h.

NSBeginsWithPredicateOperatorType

A begins-with predicate.

Available in OS X v10.4 and later.

Declared in NSComparisonPredicate.h.

NSEndsWithPredicateOperatorType

An ends-with predicate.

Available in OS X v10.4 and later.

Declared in NSComparisonPredicate.h.

NSInPredicateOperatorType

A predicate to determine if the left hand side is in the right hand side.

For strings, returns YES if the left hand side is a substring of the right hand side . For collections, returns YES if the left hand side is in the right hand side .

Available in OS X v10.4 and later.

Declared in NSComparisonPredicate.h.

NSCustomSelectorPredicateOperatorType

A predicate that uses a custom selector that takes a single argument and returns a BOOL value.

The selector is invoked on the left hand side with the right hand side as the argument.

Available in OS X v10.4 and later.

Declared in NSComparisonPredicate.h.

NSContainsPredicateOperatorType

A predicate to determine if the left hand side contains the right hand side.

Returns YES if [lhs contains rhs]; the left hand side must be an NSExpression object that evaluates to a collection

Available in OS X v10.5 and later.

Declared in NSComparisonPredicate.h.

NSBetweenPredicateOperatorType

A predicate to determine if the right hand side lies at or between bounds specified by the left hand side.

Returns YES if [lhs between rhs]; the right hand side must be an array in which the first element sets the lower bound and the second element the upper, inclusive. Comparison is performed using compare: or the class-appropriate equivalent.

Available in OS X v10.5 and later.

Declared in NSComparisonPredicate.h.

Availability

Available in OS X v10.4 and later.

Declared In

NSComparisonPredicate.h

Did this document help you?

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.