Key-Value Coding (KVC) and Generic Programming

Key-Value Coding (KVC) is a Cocoa protocol for getting and setting values generically. In programming, the term "generically" describes a way of doing things that applies to many different situations.

Generic code can reduce to total amount of code in a project (which is always good) and helps software to handle situations that the programmer didn't anticipate. Generic, reusable code is emphasized throughout Cocoa.

For example, here's a non-generic way to set a first name and last name on an object:


[person setFirstName: @"Scott"];
[person setLastName:  @"Stevenson"];



This works fine, but I can use KVC messages to write more generic code:


[person setValue:@"Scott" forKey:@"firstName"];
[person setValue:@"Stevenson" forKey:@"lastName"];



Beginners might wonder what the point is here. In fact, it actually seems like the KVC version requires more typing. Let's choose another scenario where KVC's value is more apparent.

First, let's define the class:


@interface CDCPerson : NSObject
{
    NSString * firstName;
    NSString * lastName;
    NSNumber * phoneNumber;
    NSString * emailAddress;
}
- (void) setFirstName:    (NSString *)value;
- (void) setLastName:     (NSString *)value;
- (void) setPhoneNumber:  (NSNumber *)value;
- (void) setEmailAddress: (NSString *)value;
@end



Now, some actual code:


// assume inputValues contains values we want to
// set on the person

NSDictionary * inputValues;
CDCPerson    * person = [[CDCPerson alloc] init];
                                  
NSEnumerator *e = [inputValues keyEnumerator];
id dictKey, dictValue;

while ( dictKey = [e nextObject] )
{
    dictValue = [inputValues valueForKey: dictKey];
    [person setValue: dictValue forKey: dictKey];
}



This snippet of code is generic, meaning that we don't need to change it everytime new instance variables are added to the Person class.

But it gets better! Here's an even simpler version of the code above:


// assume inputValues contains values we want to
// set on the person

NSDictionary * inputValues;
CDCPerson    * person = [[CDCPerson alloc] init];

[person setValuesForKeysWithDictionary: inputValues];



Intrigued? Here's Apple explanation of what's happening in -setValuesForKeysWithDictionary:

Sets properties of the receiver with values from keyedValues, using its keys to identify the properties. The default implementation invokes setValue:forKey: for each key-value pair, substituting nil for NSNull values in keyedValues.

In other words, essentially the same as the first example. But what is -setValue:forKey: actually doing? This is where the KVC magic comes in. It will actually find the -setFirstName:, -setLastName:, -setPhoneNumber: and -setEmailAddress: implementations and call those. If it can't find these, KVC will try quite a few different options before ultimately just setting a value on the instance variable itself.

KVC can also be used to pull values out of an object:


// assume person already exists and is populated with values

CDCPerson * person;

NSMutableDictionary * outputValues;
outputValues = [NSMutableDictionary dictionary];

NSArray * keys;
keys = [NSArray arrayWithObjects: @"firstName",
                                  @"lastName",
                                  @"phoneNumber",
                                  @"emailAddress",
                                  nil];

NSEnumerator *e = [keys objectEnumator];
id key, value;

while ( key = [e nextObject] )
{
    value = [person valueForKey: key];
    [outputValues setValue: value forKey: key];
}




Or, the simpler version:


// assume person already exists and is populated with values

CDCPerson    * person;
NSArray      * keys;

keys = [NSArray arrayWithObjects: @"firstName",
                                  @"lastName",
                                  @"phoneNumber",
                                  @"emailAddress",
                                  nil];

NSDictionary * outputValues;
outputValues = [person dictionaryWithValuesForKeys: keys];



Just as with setting values, getting values with -valueForKey: will cause KVC to look for a method the same name as the key:


// this will cause KVC to look for a method called -firstName;

NSString * name = [person valueForKey:@"firstName"];



Key-value coding is key element in Cocoa Bindings and Core Data, so it really pays to understand the basic ideas. KVC can handle keypaths, such as:


// getting
[obj valueForKeyPath: @"storage.firstName"];

// setting
[obj setValue: @"Scott" forKeyPath: @"storage.firstName"];



This is similar to doing:


// getting
[[obj storage] firstName];

// setting
[[obj storage] setFirstName:@"Scott"];



For more details on Key-value coding, take a look at this page on ADC.

Comments Temporarily Disabled

I had to temporarily disable comments due to spam. I'll re-enable them soon.