ABSearchElement Class Reference

Overview

TABSearchElement class is used to specify a search query for records in the Address Book database.

The ABSearchElement class is “toll-free bridged” with its procedural C opaque-type counterpart. This means that the ABSearchElementRef type is interchangeable in function or method calls with instances of the ABSearchElement class.

Tasks

Searching

• + searchElementForConjunction:children:

Matching

• – matchesRecord:

Class Methods

searchElementForConjunction:children:

Returns a compound search element, created by combining the search elements in an array with the given conjunction.

+ (ABSearchElement *)searchElementForConjunction:(ABSearchConjunction)conjunction children:(NSArray *)children

Parameters

conjunction

The logical operator with which to combine the search elements.

children

An array of search elements to be combined.

Return Value

A compound search element, created by combining the given search elements with the given conjunction

Discussion

The objects in the children array must be ABSearchElement objects. The conjunction can be kABSearchAnd or kABSearchOr. If children is nil or empty, this method raises an exception.

Availability

• Available in Mac OS X v10.2 and later.

See Also

• + searchElementForProperty:label:key:value:comparison: (ABPerson)
• + searchElementForProperty:label:key:value:comparison: (ABGroup)
• – recordsMatchingSearchElement: (ABAddressBook)

Declared In

ABSearchElement.h

Instance Methods

matchesRecord:

Tests whether or not a record matches a search element.

- (BOOL)matchesRecord:(ABRecord *)record

Parameters

record

The record to be tested against the search object.

Return Value

YES if the record argument satisfies the conditions in the search element; otherwise, NO.

Discussion

If record is nil, this method raises an exception.

Availability

• Available in Mac OS X v10.2 and later.

See Also

• + searchElementForProperty:label:key:value:comparison: (ABPerson)
• + searchElementForProperty:label:key:value:comparison: (ABGroup)
• + searchElementForConjunction:children:

Declared In

ABSearchElement.h

Constants

Search Conjunctions

Logical operators used to combine search elements.

enum _ABSearchConjunction {
   kABSearchAnd,
   kABSearchOr
};
typedef CFIndex ABSearchConjunction;

Constants

kABSearchAnd

Join the search elements together with the AND operand.

Available in Mac OS X v10.2 and later.

Declared in ABTypedefs.h.

kABSearchOr

Join the search elements together with the OR operand.

Available in Mac OS X v10.2 and later.

Declared in ABTypedefs.h.

Discussion

These constants are used by the searchElementForConjunction:children: method.

Search Comparisons

Comparisons used to construct search elements.

enum _ABSearchComparison {
   kABEqual,
   kABNotEqual,
   kABLessThan,
   kABLessThanOrEqual,
   kABGreaterThan,
   kABGreaterThanOrEqual,
   kABEqualCaseInsensitive,
   kABContainsSubString,
   kABContainsSubStringCaseInsensitive,
   kABPrefixMatch,
   kABPrefixMatchCaseInsensitive,
   kABBitsInBitFieldMatch,
   kABDoesNotContainSubString,
   kABDoesNotContainSubStringCaseInsensitive,
   kABNotEqualCaseInsensitive,
   kABSuffixMatch,
   kABSuffixMatchCaseInsensitive,
   kABWithinIntervalAroundToday,
   kABWithinIntervalAroundTodayYearless,
   kABNotWithinIntervalAroundToday,
   kABNotWithinIntervalAroundTodayYearless,
   kABWithinIntervalFromToday,
   kABWithinIntervalFromTodayYearless,
   kABNotWithinIntervalFromToday,
   kABNotWithinIntervalFromTodayYearless
};
typedef CFIndex ABSearchComparison;

Constants

kABEqual

Search for elements that are equal to the value.

Available in Mac OS X v10.2 and later.

Declared in ABTypedefs.h.

kABNotEqual

Search for elements that are not equal to the value.

Available in Mac OS X v10.2 and later.

Declared in ABTypedefs.h.

kABLessThan

Search for elements that are less than the value.

Available in Mac OS X v10.2 and later.

Declared in ABTypedefs.h.

kABLessThanOrEqual

Search for elements that are less than or equal to the value.

Available in Mac OS X v10.2 and later.

Declared in ABTypedefs.h.

kABGreaterThan

Search for elements that are greater than the value.

Available in Mac OS X v10.2 and later.

Declared in ABTypedefs.h.

kABGreaterThanOrEqual

Search for elements that are greater than or equal to the value.

Available in Mac OS X v10.2 and later.

Declared in ABTypedefs.h.

kABEqualCaseInsensitive

Search for elements that are equal to the value, ignoring case.

Available in Mac OS X v10.2 and later.

Declared in ABTypedefs.h.

kABContainsSubString

Search for elements that contain the value.

Available in Mac OS X v10.2 and later.

Declared in ABTypedefs.h.

kABContainsSubStringCaseInsensitive

Search for elements that contain the value, ignoring case.

Available in Mac OS X v10.2 and later.

Declared in ABTypedefs.h.

kABPrefixMatch

Search for elements that begin with the value.

Available in Mac OS X v10.2 and later.

Declared in ABTypedefs.h.

kABPrefixMatchCaseInsensitive

Search for elements that begin with the value, ignoring case.

Available in Mac OS X v10.2 and later.

Declared in ABTypedefs.h.

kABBitsInBitFieldMatch

Search for elements that match the bits in ABPersonFlags.

Available in Mac OS X v10.3 and later.

Declared in ABTypedefs.h.

kABDoesNotContainSubString

Search for elements that do not contain the value.

Available in Mac OS X v10.4 and later.

Declared in ABTypedefs.h.

kABDoesNotContainSubStringCaseInsensitive

Search for elements that do not contain the value, ignoring case.

Available in Mac OS X v10.4 and later.

Declared in ABTypedefs.h.

kABNotEqualCaseInsensitive

Search for elements that are not equal to the value, ignoring case.

Available in Mac OS X v10.4 and later.

Declared in ABTypedefs.h.

kABSuffixMatch

Search for elements that end with the value.

Available in Mac OS X v10.4 and later.

Declared in ABTypedefs.h.

kABSuffixMatchCaseInsensitive

Search for elements that end with the value, ignoring case.

Available in Mac OS X v10.4 and later.

Declared in ABTypedefs.h.

kABWithinIntervalAroundToday

Search for elements that are within a time interval (in seconds) forward or backward from today.

Available in Mac OS X v10.4 and later.

Declared in ABTypedefs.h.

kABWithinIntervalAroundTodayYearless

Search for elements that are within a time interval (in seconds) forward or backward from this day in any year.

Available in Mac OS X v10.4 and later.

Declared in ABTypedefs.h.

kABNotWithinIntervalAroundToday

Search for elements that are not within a time interval (in seconds) forward or backward from today.

Available in Mac OS X v10.4 and later.

Declared in ABTypedefs.h.

kABNotWithinIntervalAroundTodayYearless

Search for elements that are not within a time interval (in seconds) forward or backward from this day in any year.

Available in Mac OS X v10.4 and later.

Declared in ABTypedefs.h.

kABWithinIntervalFromToday

Search for elements that are within a time interval (in seconds) forward from today.

Available in Mac OS X v10.4 and later.

Declared in ABTypedefs.h.

kABWithinIntervalFromTodayYearless

Search for elements that are within a time interval (in seconds) forward from this day in any year.

Available in Mac OS X v10.4 and later.

Declared in ABTypedefs.h.

kABNotWithinIntervalFromToday

Search for elements that are not within a time interval (in seconds) forward from today.

Available in Mac OS X v10.4 and later.

Declared in ABTypedefs.h.

kABNotWithinIntervalFromTodayYearless

Search for elements that are not within a time interval (in seconds) forward from this day in any year.

Available in Mac OS X v10.4 and later.

Declared in ABTypedefs.h.

Discussion

These constants are used by the ABPerson method searchElementForProperty:label:key:value:comparison: and the ABGroup method searchElementForProperty:label:key:value:comparison:

---