What is the KVC Search Pattern for mutableArrayValueForKey?

Question

I'm attempting to understand Cocoa's Key-Value Coding (KVC) mechanism a little better. I've read Apple's Key-Value Programming Guide but am still a little confused about how certain KVC methods search for keys. Particularly, mutableArrayValueForKey:.

Below I'm going to explain how I understand valueForKey: KVC "getters" to work. Then I'll get to my question regarding mutableArrayValueForKey.

---

There are seven different "getter" KVC methods:

- (id)valueForKey:(NSString *)key;
- (id)valueForKeyPath:(NSString *)keyPath;
- (NSDictionary *)dictionaryWithValuesForKeys:(NSArray *)keys;
- (NSMutableArray *)mutableArrayValueForKey:(NSString *)key;
- (NSMutableArray *)mutableArrayValueForKeyPath:(NSString *)keyPath;
- (NSMutableSet *)mutableSetValueForKey:(NSString *)key;
- (NSMutableSet *)mutableSetValueForKeyPath:(NSString *)keyPath;

When searching for a Value inside a Property (named myKey), Apple's docs state that valueForKey: searches like this:

1. Tries -getMyKey, -myKey, and -isMyKey (in that order) inside the receiver

2. If not found, it attempts these ordered, to-many getters (NSArray):

   // Required:
   - (NSUInteger)countOfMyKey;
   
   // Requires At Least One:
   - (id)objectInMyKeyAtIndex:(NSUInteger)index;
   - (NSArray *)myKeyAtIndexes:(NSIndexSet *)indexes;
   
   // Optional (improves performance):
   - (void)getMyKey:(KeyClass **)buffer range:(NSRange)inRange;
   

3. Next, it attempts these unordered, to-many getters (NSSet):

   - (NSUInteger)countOfMyKey;
   - (NSEnumerator *)enumeratorOfMyKey;
   - (KeyClass *)memberOfMyKey:(KeyClass *)anObject;
   

4. Next, it attempts to access Instance Variables directly, assuming YES is returned by accessInstanceVariablesDirectly, in this order: _myKey, _isMyKey, myKey, isMyKey.

5. Lastly, it gives up and calls the receiving class's - (id)valueForUndefinedKey:(NSString *)key method. Usually an error is raised here.

---

My question is, what is the search order pattern for mutableArrayValueForKey:?

Apple's docs state this:

Accessor Search Pattern for Ordered Collections

The default search pattern for mutableArrayValueForKey: is as follows:

The receiver's class is searched for a pair of methods whose names match the patterns -insertObject:inAtIndex: and -removeObjectFromAtIndex: (corresponding to the NSMutableArray primitive methods insertObject:atIndex: and removeObjectAtIndex: respectively), or methods matching the pattern -insert:atIndexes: and -removeAtIndexes: (corresponding to the NSMutableArrayinsertObjects:atIndexes: and removeObjectsAtIndexes: methods). If at least one insertion method and at least one removal method are found each NSMutableArray message sent to the collection proxy object will result in some combination of -insertObject:inAtIndex:, -removeObjectFromAtIndex:, -insert:atIndexes:, and -removeAtIndexes: messages being sent to the original receiver of mutableArrayValueForKey:. ...etc...

This makes no sense to me as it's discussing "setter" like methods. mutableArrayValueForKey: returns an NSMutableArray. All of the methods listed above return void, and are used to edit an NSMutableArray, not get it. Example:

- (void)insertMyKey:(KeyClass *)keyObject inMyKeyAtIndex:(NSUInteger)index;
- (void)removeObjectFromMyKeyAtIndex:(NSUInteger)index;

Any idea what Apple is trying to say in their docs, or if this is perhaps an error?

My theory is that mutableArrayValueForKey: is likely taking a similar path as valueForKey: when searching to retrieve a KVC value. I'm just not sure what path that really is.

Thanks for any help you can offer! :)

Answer 1

The NSMutableArray you get back from calling mutableArrayValueForKey: is actually a private subclass of NSMutableArray which overrides normal array methods such as -count, -objectAtIndex:, -insertObject:atIndex:, etc. and calls the corresponding KVC methods on the object the array was retrieved from. It basically acts as a proxy for manipulating the to-many relationship of the object, and it's not something you have to worry about creating or returning yourself. A quick example of usage:

Playlist* aPlaylist;
Track* aTrack;
NSMutableArray* mutableTracks = [aPlaylist mutableArrayValueForKey:@"tracks"];
[mutableTracks insertObject:aTrack atIndex:0];

This piece of code adds a track to the beginning of the playlist. If the Playlist class implements KVC methods for its "tracks" relationship, then calling a method on the mutable array will result in the appropriate method being called on the underlying object. So in this example, when you call insertObject:atIndex: on the array, the array will in turn call insertObjectInTracks:atIndex: on the playlist object, and the track gets added to the playlist's array of tracks.

Now, in this example, of course you could just call insertObjectInTracks:atIndex: directly, but there are several advantages you can get out of using mutableArrayValueForKey: instead.

• The array wrapper hides the implementation details of the underlying KVC methods. Implementing the entire list of methods isn't strictly required to be KVC compliant. The Playlist class could just implement -tracks and -setTracks:, and the code above will still work. In this case, instead of calling insertObjectInTracks:atIndex:, the mutable array proxy will create a new array with the object inserted at the beginning, and then just call setTracks: on the Playlist object. This is obviously less efficient, so implementing the full list of KVC methods is usually recommended.
• In the case where, instead of a constant string for the key, you instead have a variable, using mutableArrayValueForKey: allows you to manipulate the relationship without having to know the exact names of the methods you have to call. As long as the object is KVC compliant for the key you're using, everything will "just work".
• It also lets you use any method that NSMutableArray itself implements, so for example you could use methods that search the array for objects, sort the array, etc. without having to rewrite special versions to deal with the KVC stuff.