---

ABMutableMultiValue Class Objective-C Reference

Overview

The ABMultiValue and ABMutableMultiValue classes are used to represent properties that might have multiple values. Each value in a multi-value list must be the same type, and has an associated pre-defined or user-defined label, and unique identifier. The labels, however, need not be unique. For example, you can have multiple “Home” phone numbers. Each multi-value 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 multi-value list.

You can use either the addValue:withLabel: or insertValue:withLabel:atIndex: methods to add value/label pairs to a multi-value list. You can remove an entry in a multi-value list using the removeValueAndLabelAtIndex: method. You can also replace values and labels using the replaceLabelAtIndex:withLabel:and replaceValueAtIndex:withValue: methods.

Use the setPrimaryIdentifier: method to set the primary identifier—that is, designate the corresponding value as the default value for a multi-value list. Use the identifierAtIndex: method to get the unique identifier for a value/label pair.

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

Tasks

Adding a Value

• – addValue:withLabel:
• – insertValue:withLabel:atIndex:

Replacing Values and Labels

• – replaceLabelAtIndex:withLabel:
• – replaceValueAtIndex:withValue:

Removing Values

• – removeValueAndLabelAtIndex:

Primary Identifier

• – setPrimaryIdentifier:

Instance Methods

addValue:withLabel:

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

Discussion

Adds a value and its label to a multi-value list. 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 “Constants” for a list of supported types in a multi-value list (see descriptions of the kABMulti... constants). If value is added successfully, this method returns the new identifier, nil otherwise. If either the value or the label arguments are 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 multi-value 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 Mac OS X v10.2 and later.

See Also

• – insertValue:withLabel:atIndex:

Declared In

ABMultiValue.h

insertValue:withLabel:atIndex:

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

Discussion

Inserts a value and its label at the given index in a multi-value list. If successful, this method returns the identifier, nil otherwise. 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 multi-value 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 Mac OS X v10.2 and later.

See Also

• – addValue:withLabel:

Declared In

ABMultiValue.h

removeValueAndLabelAtIndex:

- (BOOL)removeValueAndLabelAtIndex:(NSUInteger)index

Discussion

Removes the value and label at the given index. Returns YES if successful, NO otherwise. If the index is out of bounds, this method raises an exception.

Availability

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

Declared In

ABMultiValue.h

replaceLabelAtIndex:withLabel:

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

Discussion

Replaces the label at the given index. Returns YES if successful, NO otherwise. If the label is nil or if the index is out of bounds, this method raises an exception.

Availability

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

See Also

• – replaceValueAtIndex:withValue:

Declared In

ABMultiValue.h

replaceValueAtIndex:withValue:

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

Discussion

Replaces the value at the given index. Returns YES if successful, NO otherwise. If the value is nil or if the index is out of bounds, this method raises an exception.

Availability

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

See Also

• – replaceLabelAtIndex:withLabel:

Declared In

ABMultiValue.h

setPrimaryIdentifier:

- (BOOL)setPrimaryIdentifier:(NSString *)identifier

Discussion

Sets the primary value to be the value for the given identifier. Use the identifierAtIndex: method to get the identifier given the index. Returns YES if successful, NO otherwise. If the identifier is nil, this method raises an exception.

Availability

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

See Also

• – primaryIdentifier (ABMultiValue)

Declared In

ABMultiValue.h

---