NSComparisonPredicate Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in iOS 3.0 and later.
Companion guide
Declared in
NSComparisonPredicate.h
Related sample code

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 iOS 3.0 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:(NSComparisonPredicateOptions)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 iOS 3.0 and later.
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 iOS 3.0 and later.
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 iOS 3.0 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 iOS 3.0 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:(NSComparisonPredicateOptions)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 iOS 3.0 and later.
Related Sample Code
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 iOS 3.0 and later.
Declared In
NSComparisonPredicate.h

options

Returns the options that are set for the receiver.

Return Value

The options that are set for the receiver.

Availability
  • Available in iOS 3.0 and later.
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 iOS 3.0 and later.
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 iOS 3.0 and later.
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 iOS 3.0 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 iOS 3.0 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 iOS 3.0 and later.

Declared in NSComparisonPredicate.h.

Availability
  • Available in iOS 3.0 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 iOS 3.0 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 iOS 3.0 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 iOS 4.0 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 iOS 5.0 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 iOS 3.0 and later.

Declared in NSComparisonPredicate.h.

NSLessThanOrEqualToPredicateOperatorType

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

Available in iOS 3.0 and later.

Declared in NSComparisonPredicate.h.

NSGreaterThanPredicateOperatorType

A greater-than predicate.

Available in iOS 3.0 and later.

Declared in NSComparisonPredicate.h.

NSGreaterThanOrEqualToPredicateOperatorType

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

Available in iOS 3.0 and later.

Declared in NSComparisonPredicate.h.

NSEqualToPredicateOperatorType

An equal-to predicate.

Available in iOS 3.0 and later.

Declared in NSComparisonPredicate.h.

NSNotEqualToPredicateOperatorType

A not-equal-to predicate.

Available in iOS 3.0 and later.

Declared in NSComparisonPredicate.h.

NSMatchesPredicateOperatorType

A full regular expression matching predicate.

Available in iOS 3.0 and later.

Declared in NSComparisonPredicate.h.

NSLikePredicateOperatorType

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

Available in iOS 3.0 and later.

Declared in NSComparisonPredicate.h.

NSBeginsWithPredicateOperatorType

A begins-with predicate.

Available in iOS 3.0 and later.

Declared in NSComparisonPredicate.h.

NSEndsWithPredicateOperatorType

An ends-with predicate.

Available in iOS 3.0 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 iOS 3.0 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 iOS 3.0 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 iOS 3.0 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 iOS 3.0 and later.

Declared in NSComparisonPredicate.h.

Availability
  • Available in iOS 3.0 and later.
Declared In
NSComparisonPredicate.h