---

Accessor Search Implementation Details

Key-value coding attempts to use accessor methods to get and set values, before resorting to directly accessing the instance variable. This article describes how the key-value coding methods determine how the value is accessed.

Contents:

Default Search Pattern for setValue:forKey:
Default Search Pattern for valueForKey:
Mac OS X Version 10.3 Compatibility Notes

Default Search Pattern for setValue:forKey:

When the default implementation of setValue:forKey: is invoked for a property the following search pattern is used:

1. The receiver’s class is searched for an accessor method whose name matches the pattern -set<Key>:.

2. If no accessor is found, and the receiver’s class method accessInstanceVariablesDirectly returns YES, the receiver is searched for an instance variable whose name matches the pattern _<key>, _is<Key>, <key>, or is<Key>, in that order.

3. If a matching accessor or instance variable is located, it is used to set the value. If necessary, the value is extracted from the object as described in “Representing Data as Objects.”

4. If no appropriate accessor or instance variable is found, setValue:forUndefinedKey: is invoked for the receiver.

The method takeStoredValue:forKey: is similar to setValue:forKey:, but uses direct access to instance variables rather than public accessors. As a result, the search order is 2, 1, 3, 4.

Default Search Pattern for valueForKey:

When the default implementation of valueForKey: is invoked on a receiver, the following search pattern is used:

1. Search the receiver’s class for an accessor method whose name matches the pattern -get<Key>, -<key>, or -is<Key>, in that order.

2. If no accessor is found, and the receiver’s class method accessInstanceVariablesDirectly returns YES, the receiver is searched for an instance variable whose name matches the pattern _<key>, _is<Key>, <key>, or is<Key>, in that order.

3. If a matching accessor or instance variable is located the resulting value is returned. If necessary, the value is first encapsulated as an object as described in “Representing Data as Objects.”

4. If no appropriate accessor or instance variable is found, valueForUndefinedKey: is invoked for the receiver, and the value is returned.

The method storedValueForKey: is similar to valueForKey:, but prefers direct access to instance variables rather than public accessors. As a result, the search order is 2, 1, 3, 4.

Mac OS X Version 10.3 Compatibility Notes

Mac OS X v10.3 deprecated a number of existing key-value coding methods, replacing them with methods that provide similar functionality.

The following compatibility notes are relevant to the accessor search patterns discussed in “Default Search Pattern for setValue:forKey:” and “Default Search Pattern for valueForKey:”:

• For backward binary compatibility with the behavior of takeValue:forKey:, a method whose name matches the pattern -_set<Key>: is also recognized in step 1. KVC accessor methods whose names start with underscores are deprecated as of Mac OS X v10.3.

• For backward binary compatibility, unableToSetNilForKey: is invoked instead of setNilValueForKey: in step 1 if the receiver’s implementation of unableToSetNilForKey: is not NSObject’s implementation.

• The behavior described in step 2 is different from that of takeValue:forKey:, in which the instance variable search order is <key>, _<key>.

• For backward binary compatibility with the behavior of takeValue:forKey:, handleTakeValue:forUnboundKey: is invoked instead of setValue:forUndefinedKey: in step 4 if the receiver’s implementation of handleTakeValue:forUnboundKey: is not NSObject's implementation.

---