ABMutableMultiValue 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
Related sample code

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 ABMutableMultiValue are mutable, see ABMultiValue for additional methods that access 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

Adding a Value

Replacing Values and Labels

Removing Values

Setting the Primary Identifier

Instance Methods

addValue:withLabel:

Adds a value and its label to a multivalue list.

- (NSString *)addValue:(id)value withLabel:(NSString *)label
Parameters
value

The value to add.

label

The label to associate with the value.

Return Value

The new identifier if value is added successfully; otherwise, nil.

Discussion

The value argument must be of the correct type. For example, if the receiver is the value for a property of type kABMultiStringProperty, then value needs to be an NSString object. See “Property Types” in Address Book Objective-C Constants Reference for a list of supported types in a multivalue list (see descriptions of the kABMulti... constants). If either the value or the label argument is nil, this method raises an exception.

This method performs no type checking and will let you add a value whose type does not match the types of the other values in the list. However, if you try to use a multivalue list whose values are not all of the same type, other methods, such as the ABRecord setValue:forProperty: method, will return NO or kABErrorInProperty.

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

insertValue:withLabel:atIndex:

Inserts a value and its label at the given index in a multivalue list.

- (NSString *)insertValue:(id)value withLabel:(NSString *)label atIndex:(NSUInteger)index
Parameters
value

The value to add.

label

The label to associate with the value.

index

The index where the value will be inserted.

Return Value

The identifier of the inserted value and label if they are added successfully; otherwise, nil.

Discussion

If either the value or the label is nil or if the index is out of bounds, this method raises an exception

This method performs no type checking and will let you add a value whose type does not match the types of the other values in the list. However, if you try to use a multivalue list whose values are not all of the same type, other methods, such as the ABRecord setValue:forProperty: method, will return NO or kABErrorInProperty.

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

removeValueAndLabelAtIndex:

Removes the value and label at the given index.

- (BOOL)removeValueAndLabelAtIndex:(NSUInteger)index
Parameters
index

The index of the value-label pair that will be removed.

Return Value

YES if successful; otherwise NO.

Discussion

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

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

replaceLabelAtIndex:withLabel:

Replaces the label at the given index.

- (BOOL)replaceLabelAtIndex:(NSUInteger)index withLabel:(NSString *)label
Parameters
index

The index of the label that will be replaced.

label

The new label.

Return Value

YES if successful; otherwise, NO.

Discussion

If the label is nil or if the index is out of bounds, this method raises an exception.

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

replaceValueAtIndex:withValue:

Replaces the value at the given index.

- (BOOL)replaceValueAtIndex:(NSUInteger)index withValue:(id)value
Parameters
index

The index of the value that will be replaced.

value

The new value.

Return Value

YES if successful; otherwise NO.

Discussion

If the value is nil or if the index is out of bounds, this method raises an exception.

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

setPrimaryIdentifier:

Sets the primary value to be the value for the given identifier.

- (BOOL)setPrimaryIdentifier:(NSString *)identifier
Parameters
identifier

The identifier whose value will be used as the primary value for a multivalue property.

Return Value

YES if successful; otherwise NO.

Discussion

If the identifier is nil, this method raises an exception. Use the identifierAtIndex: method to get the identifier given the index.

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