ABMultiValue Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/AddressBook.framework
Availability
Available in OS X v10.2 and later.
Companion guide
Declared in
ABMultiValue.h

Overview

The ABMultiValue and ABMutableMultiValue classes are used to represent properties that might have multiple values. Each value in a multivalue list must be of the same type, and must have an associated predefined or user-defined label, and unique identifier. The labels, however, need not be unique. For example, you can have multiple Home phone numbers. Each multivalue object may have a primary identifier—used as a default value when a label is not provided. For example, a person record may have multiple addresses with the labels Home and Work, where Work is designated as the primary value. Instances of this class are immutable, see ABMutableMultiValue for methods that manipulate the content of a multivalue list.

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

Tasks

Accessing the Primary Identifier

Accessing Identifiers

Accessing Entries

Querying the List

Instance Methods

count

Returns the number of entries in a multivalue list.

- (NSUInteger)count
Availability
  • Available in OS X v10.2 and later.
Related Sample Code
Declared In
ABMultiValue.h

identifierAtIndex:

Returns the identifier for the given index.

- (NSString *)identifierAtIndex:(NSUInteger)index
Parameters
index

The index of the identifier to be returned.

Discussion

If the index argument is out of bounds, this method raises an exception.

Availability
  • Available in OS X v10.2 and later.
Declared In
ABMultiValue.h

indexForIdentifier:

Returns the index for the given identifier.

- (NSUInteger)indexForIdentifier:(NSString *)identifier
Parameters
identifier

The identifier whose index will be returned.

Discussion

If the identifier is not found, returns NSNotFound.

Availability
  • Available in OS X v10.2 and later.
Declared In
ABMultiValue.h

labelAtIndex:

Returns the label for the given index.

- (NSString *)labelAtIndex:(NSUInteger)index
Parameters
index

The index for the label to be returned.

Discussion

If the index argument is out of bounds, this method raises an exception.

Availability
  • Available in OS X v10.2 and later.
Related Sample Code
Declared In
ABMultiValue.h

labelForIdentifier:

Returns the label for the given identifier.

- (id)labelForIdentifier:(NSString *)identifier
Parameters
identifier

The identifier for the label to be returned.

Discussion

If the identifier is not found, this method returns nil.

Availability
  • Available in OS X v10.5 and later.
Declared In
ABMultiValue.h

primaryIdentifier

Returns the identifier for the primary value.

- (NSString *)primaryIdentifier
Availability
  • Available in OS X v10.2 and later.
Declared In
ABMultiValue.h

propertyType

Returns the type for the values in a multivalue list.

- (ABPropertyType)propertyType
Discussion

If the multivalue list is empty or its values are of different types, it returns kABErrorInProperty.

Availability
  • Available in OS X v10.2 and later.
Declared In
ABMultiValue.h

valueAtIndex:

Returns the value for the given index.

- (id)valueAtIndex:(NSUInteger)index
Parameters
index

The index for the value to be returned.

Discussion

If the index argument is out of bounds, this method raises an exception.

Availability
  • Available in OS X v10.2 and later.
Related Sample Code
Declared In
ABMultiValue.h

valueForIdentifier:

Returns the value for the given identifier.

- (id)valueForIdentifier:(NSString *)identifier
Parameters
identifier

The identifier for the value to be returned.

Discussion

If the identifier is not found, returns nil.

Availability
  • Available in OS X v10.5 and later.
Declared In
ABMultiValue.h