Key-Value Coding Programming Guide: Defining Collection Methods (original) (raw)

When you create accessors and ivars using standard naming conventions, as described in Achieving Basic Key-Value Coding Compliance, the key-value coding protocol’s default implementation can locate them in response to key-value coded messages. This is as true for collection objects representing to-many relationships as it is for other properties. However, if you implement the collection accessor methods instead of, or in addition to, the basic accessors for a collection property, you can:

You implement one of two categories of collection accessors, depending on whether you want the relationship to behave like an indexed, ordered collection (like an NSArray object) or an unordered, uniqued collection (like an NSSet object). In either case, you implement at least one set of methods to support read access to the property, and then add an additional set to enable mutation of the collection’s contents.

Accessing Indexed Collections

You add indexed accessor methods to provide a mechanism for counting, retrieving, adding, and replacing objects in an ordered relationship. The underlying object is often an instance of NSArray or NSMutableArray, but if you provide the collection accessors, you enable any object property for which you implement these methods to be manipulated as if it were an array.

Indexed Collection Getters

For a collection property that has no default getter, if you provide the following indexed collection getter methods, the default implementation of the protocol, in response to a valueForKey: message, returns a proxy object that behaves like an NSArray, but calls the following collection methods to do its work.

Indexed Collection Mutators

Supporting a mutable to-many relationship with indexed accessors requires implementing a different group of methods. When you provide these setter methods, the default implementation, in response to the mutableArrayValueForKey: message, returns a proxy object that behaves like an NSMutableArray object, but uses your object’s methods to do its work. This is generally more efficient than returning an NSMutableArray object directly. It also enables the contents of a to-many relationship to be key-value observing compliant (see Key-Value Observing Programming Guide).

In order to make your object key-value coding compliant for a mutable ordered to-many relationship, implement the following methods:

Accessing Unordered Collections

You add unordered collection accessor methods to provide a mechanism for accessing and mutating objects in an unordered relationship. Typically, this relationship is an instance of an NSSet or NSMutableSet object. However, when you implement these accessors, you enable any class to model the relationship and be manipulated using key-value coding just as if it were an instance of NSSet.

Unordered Collection Getters

When you provide the following collection getter methods to return the number of objects in the collection, iterate over the collection objects, and test if an object is already present in the collection, the default implementation of the protocol, in response to a valueForKey: message, returns a proxy object that behaves like an NSSet, but calls the following collection methods to do its work.

Unordered Collection Mutators

Supporting a mutable to-many relationship with unordered accessors requires implementing additional methods. Implement the mutable unordered accessors to allow your object to supply an unordered set proxy object in response to the mutableSetValueForKey: method. Implementing these accessors is much more efficient than relying on an accessor that returns a mutable object directly for making changes to the data in the relationship. It also makes your class key-value observing compliant for the collected objects (see Key-Value Observing Programming Guide).

In order to be key-value coding complaint for a mutable unordered to-many relationship implement the following methods:

Achieving Basic Key-Value Coding Compliance

Handling Non-Object Values

Copyright © 2018 Apple Inc. All rights reserved. Terms of Use | Privacy Policy | Updated: 2016-10-27