June 2009 – Eschatology

I’ve occasionally been asked about the appropriate form for properties representing to-many relationships in Objective-C 2.0.

Let’s start with the example of a recipe and its ingredients, represented by instances of the Recipe and Ingredient classes.

@interface Recipe : NSObject {
@private
NSMutableSet *_ingredients;
}

@property (copy) NSSet *ingredients;

@end

This is a pretty straightforward interface for the Recipe class, but how should we actually implement it? You might first think of writing something like this:

@implementation Recipe

– (id)init {
if (self = [super init]) {
_ingredients = [[NSMutableSet alloc] init];
}
return self;
}

– (void)dealloc {
[_ingredients release];
[super dealloc];
}

@synthesize ingredients = _ingredients;

@end

However, this **will not** do what you expect. In particular, whenever you manipulate the `ingredients` property, it always **replace the value** of the `_ingredients` instance variable used for its storage with a new, immutable NSSet!

What’s wrong with this? For one thing, you won’t be able to make any finer-grained changes to the `ingredients` property, so your code may wind up doing a lot of work unnecessarily. You’ll only ever post Key-Value Observing changes for the entire property, as well, not for individual manipulations; anything observing those changes will probably wind up doing extra work, too.

Why not instead change the type of the property itself to `NSMutableSet *` then? That way, your code could just manipulate the ingredients of a recipe directly, right? You *could* do that, but then you wouldn’t get **any** Key-Value Observing notifications for changes to the property. Why not? Because KVO is all about notification of **property** changes, and changing the object that stores a property’s data isn’t the same thing as changing the property itself.

What should you do then? Here’s how I would implement the `Recipe.ingredients` property instead of using the above `@synthesize` directive:

@implementation Recipe (IngredientsProperty)

– (void)setIngredients:(NSSet *)value {
[_ingredients setSet:value];
}

– (NSSet *)ingredients {
return [NSSet setWithSet:_ingredients];
}

@end

What’s different here is that I’m taking advantage of the fact that the instance variable backing the property is mutable. For just a getter and a setter, that isn’t a big deal. However, since I’m dealing with a to-many relationship, I wouldn’t just write a getter and a setter. I’d also write some of the additional relationship-KVC methods for the property, so I can manipulate the property more efficiently, and get finer-grained KVO notifications:

@interface Recipe (IngredientsProperty)

– (void)addIngredientsObject:(Ingredient *)ingredient;
– (void)removeIngredientsObject:(Ingredient *)ingredient;

– (void)addIngredients:(NSSet *)ingredients;
– (void)removeIngredients:(NSet *)ingredients;

@end

@implementation Recipe (IngredientsProperty)

– (void)addIngredientsObject:(Ingredient *)ingredient {
[_ingredients addObject:ingredient];
}

– (void)removeIngredientsObject:(Ingredient *)ingredient {
[_ingredients removeObject:ingredient];
}

– (void)addIngredients:(NSSet *)ingredients {
[_ingredients unionSet:ingredients];
}

– (void)removeIngredients:(NSSet *)ingredients {
[_ingredients minusSet:ingredients];
}

@end

By doing this, when I need to manipulate a Recipe’s `ingredients` property I can use `-mutableSetValueForKey:` to do so and any changes I make will be efficient. For example, if I’m creating a Recipe to represent Meghan’s Butternut Squash Panang Curry, I might write some code like this:

NSMutableSet *ingredients = [panangCurryRecipe mutableSetValueForKey:@”ingredients”];

[ingredients addObject:[Ingredient ingredientWithName:@”Butternut Squash” quantity:1]];
[ingredients addObject:[Ingredient ingredientWithName:@”Panang Curry Paste” quantity:1]];
[ingredients addObject:[Ingredient ingredientWithName:@”Coconut Milk” quantity:1]];

Instead of making several copies of the set as I make changes, the underlying mutable set is changed in as efficient a way as possible given the accessors I’ve implemented. I don’t have to do any extra work to make that happen.

I also get efficient KVO change notifications for the property, so if I have any user interface bound to it â€” whether through Cocoa bindings or, if I’m using Cocoa Touch, a “bindings lite” implemented atop KVO â€” the change notifications it receives will reflect exactly the changes made, instead of wholesale replacement of the set.

I could still improve the code above. I’m using `-[NSObject(NSKeyValueCoding) mutableSetValueForKey:]` to manipulate the `Recipe.ingredients` property. That means I don’t get nice Code Sense completion from Xcode, and have to remember the property’s name *and* spell it correctly when I use it in a string. So I’ll add the following property declaration and implementation:

@interface Recipe (IngredientsProperty)
@property (readonly, copy) NSMutableSet *mutableIngredients;
@end

@implementation Recipe (IngredientsProperty)

– (NSMutableSet *)mutableIngredients {
return [self mutableSetValueForKey:@”ingredients”];
}

@end

You’re probably thinking something like “Wait a minute, `readonly` and `NSMutableSet`?!” That’s exactly what I mean to say, though: You can mutate the *collection* you get back (“read”) from the property, but not the *property itself*.

> **Update:** On Twitter, a couple of people asked why I didn’t just use `-[Recipe addIngredientsObject:]` directly, since I have that available. I certainly could have done that, and it’d have all of the advantages I cite, and it wouldn’t require the creation of the proxy mutable set either. However, if I wanted to something more complex than just an addition, using the proxy mutable set is a significant advantage.
>
> This is because the proxy mutable set (or array, if you’re using an ordered relationship and `-mutableArrayValueForKey:`) will do the heavy lifting of figuring out the right combination of the accessors your implemented accessors to perform an operation most efficiently. Also, technologies like Cocoa bindings will always use the proxy.

With this additional property in place, the entire Recipe class will look something like this:

@interface Recipe : NSObject {
@private
NSMutableSet *_ingredients;
}

@property (copy) NSSet *ingredients;
@property (readonly, copy) NSMutableSet *mutableIngredients;