Accessor Search Patterns
The default implementation of the NSKeyValueCoding
protocol provided by NSObject
maps key-based accessor calls to an object’s underlying properties using a clearly defined set of rules. These protocol methods use a key parameter to search their own object instance for accessors, instance variables, and related methods that follow certain naming conventions. Although you rarely modify this default search, it can be helpful to understand how it works, both for tracing the behavior of key-value coded objects, and for making your own objects compliant.
Search Pattern for the Basic Getter
The default implementation of valueForKey:
, given a key
parameter as input, carries out the following procedure, operating from within the class instance receiving the valueForKey:
call.
Search the instance for the first accessor method found with a name like
get<Key>
,<key>
,is<Key>
, or_<key>
, in that order. If found, invoke it and proceed to step 5 with the result. Otherwise proceed to the next step.If no simple accessor method is found, search the instance for methods whose names match the patterns
countOf<Key>
andobjectIn<Key>AtIndex:
(corresponding to the primitive methods defined by theNSArray
class) and<key>AtIndexes:
(corresponding to theNSArray
methodobjectsAtIndexes:
).If the first of these and at least one of the other two is found, create a collection proxy object that responds to all
NSArray
methods and return that. Otherwise, proceed to step 3.The proxy object subsequently converts any
NSArray
messages it receives to some combination ofcountOf<Key>
,objectIn<Key>AtIndex:
, and<key>AtIndexes:
messages to the key-value coding compliant object that created it. If the original object also implements an optional method with a name likeget<Key>:range:
, the proxy object uses that as well, when appropriate. In effect, the proxy object working together with the key-value coding compliant object allows the underlying property to behave as if it were anNSArray
, even if it is not.If no simple accessor method or group of array access methods is found, look for a triple of methods named
countOf<Key>
,enumeratorOf<Key>
, andmemberOf<Key>:
(corresponding to the primitive methods defined by theNSSet
class).If all three methods are found, create a collection proxy object that responds to all
NSSet
methods and return that. Otherwise, proceed to step 4.This proxy object subsequently converts any
NSSet
message it receives into some combination ofcountOf<Key>
,enumeratorOf<Key>
, andmemberOf<Key>:
messages to the object that created it. In effect, the proxy object working together with the key-value coding compliant object allows the underlying property to behave as if it were anNSSet
, even if it is not.If no simple accessor method or group of collection access methods is found, and if the receiver's class method
accessInstanceVariablesDirectly
returnsYES
true
, search for an instance variable named_<key>
,_is<Key>
,<key>
, oris<Key>
, in that order. If found, directly obtain the value of the instance variable and proceed to step 5. Otherwise, proceed to step 6.If the retrieved property value is an object pointer, simply return the result.
If the value is a scalar type supported by
NSNumber
, store it in anNSNumber
instance and return that.If the result is a scalar type not supported by NSNumber, convert to an
NSValue
object and return that.If all else fails, invoke
valueForUndefinedKey:
. This raises an exception by default, but a subclass ofNSObject
may provide key-specific behavior.
Search Pattern for the Basic Setter
The default implementation of setValue:forKey:
, given key
and value
parameters as input, attempts to set a property named key
to value
(or, for non-object properties, the unwrapped version of value
, as described in Representing Non-Object Values) inside the object receiving the call, using the following procedure:
Look for the first accessor named
set<Key>:
or_set<Key>
, in that order. If found, invoke it with the input value (or unwrapped value, as needed) and finish.If no simple accessor is found, and if the class method
accessInstanceVariablesDirectly
returnsYES
true
, look for an instance variable with a name like_<key>
,_is<Key>
,<key>
, oris<Key>
, in that order. If found, set the variable directly with the input value (or unwrapped value) and finish.Upon finding no accessor or instance variable, invoke
setValue:forUndefinedKey:
. This raises an exception by default, but a subclass ofNSObject
may provide key-specific behavior.
Search Pattern for Mutable Arrays
The default implementation of mutableArrayValueForKey:
, given a key
parameter as input, returns a mutable proxy array for a property named key
inside the object receiving the accessor call, using the following procedure:
Look for a pair of methods with names like
insertObject:in<Key>AtIndex:
andremoveObjectFrom<Key>AtIndex:
(corresponding to theNSMutableArray
primitive methodsinsertObject:atIndex:
andremoveObjectAtIndex:
respectively), or methods with names likeinsert<Key>:atIndexes:
andremove<Key>AtIndexes:
(corresponding to theNSMutableArray
insertObjects:atIndexes:
andremoveObjectsAtIndexes:
methods).If the object has at least one insertion method and at least one removal method, return a proxy object that responds to
NSMutableArray
messages by sending some combination ofinsertObject:in<Key>AtIndex:
,removeObjectFrom<Key>AtIndex:
,insert<Key>:atIndexes:
, andremove<Key>AtIndexes:
messages to the original receiver ofmutableArrayValueForKey:
.When the object receiving a
mutableArrayValueForKey:
message also implements an optional replace object method with a name likereplaceObjectIn<Key>AtIndex:withObject:
orreplace<Key>AtIndexes:with<Key>:
, the proxy object utilizes those as well when appropriate for best performance.If the object does not have the mutable array methods, look instead for an accessor method whose name matches the pattern
set<Key>:
. In this case, return a proxy object that responds toNSMutableArray
messages by issuing aset<Key>:
message to the original receiver ofmutableArrayValueForKey:
.If neither the mutable array methods, nor the accessor are found, and if the receiver's class responds
YES
true
toaccessInstanceVariablesDirectly
, search for an instance variable with a name like_<key>
or<key>
, in that order.If such an instance variable is found, return a proxy object that forwards each
NSMutableArray
message it receives to the instance variable's value, which typically is an instance ofNSMutableArray
or one of its subclasses.If all else fails, return a mutable collection proxy object that issues a
setValue:forUndefinedKey:
message to the original receiver of themutableArrayValueForKey:
message whenever it receives anNSMutableArray
message.The default implementation of setValue:forUndefinedKey: raises an
NSUndefinedKeyException
, but subclasses may override this behavior.
Search Pattern for Mutable Ordered Sets
The default implementation of mutableOrderedSetValueForKey:
recognizes the same simple accessor methods and ordered set accessor methods as valueForKey:
(see Default Search Pattern for the Basic Getter), and follows the same direct instance variable access policies, but always returns a mutable collection proxy object instead of the immutable collection that valueForKey:
returns. In addition, it does the following:
Search for methods with names like
insertObject:in<Key>AtIndex:
andremoveObjectFrom<Key>AtIndex:
(corresponding to the two most primitive methods defined by theNSMutableOrderedSet
class), and alsoinsert<Key>:atIndexes:
andremove<Key>AtIndexes:
(corresponding toinsertObjects:atIndexes:
andremoveObjectsAtIndexes:
).If at least one insertion method and at least one removal method are found, the returned proxy object sends some combination of
insertObject:in<Key>AtIndex:
,removeObjectFrom<Key>AtIndex:
,insert<Key>:atIndexes:
, andremove<Key>AtIndexes:
messages to the original receiver of themutableOrderedSetValueForKey:
message when it receivesNSMutableOrderedSet
messages.The proxy object also makes use of methods with names like
replaceObjectIn<Key>AtIndex:withObject:
orreplace<Key>AtIndexes:with<Key>:
when they exist in the original object.If the mutable set methods are not found, search for an accessor method with a name like
set<Key>:
. In this case, the returned proxy object sends aset<Key>:
message to the original receiver ofmutableOrderedSetValueForKey:
every time it receives aNSMutableOrderedSet
message.If neither the mutable set messages nor the accessor are found, and if the receiver’s
accessInstanceVariablesDirectly
class method returnsYES
true
, search for an instance variable with a name like_<key>
or<key>
, in that order. If such an instance variable is found, the returned proxy object forwards anyNSMutableOrderedSet
messages it receives to the instance variable’s value, which is typically an instance ofNSMutableOrderedSet
or one of its subclasses.If all else fails, the returned proxy object sends a
setValue:forUndefinedKey:
message to the original receiver ofmutableOrderedSetValueForKey:
whenever it receives a mutable set message.The default implementation of
setValue:forUndefinedKey:
raises anNSUndefinedKeyException
, but objects may override this behavior.
Search Pattern for Mutable Sets
The default implementation of mutableSetValueForKey:
, given a key
parameter as input, returns a mutable proxy set for an array property named key
inside the object receiving the accessor call, using the following procedure:
Search for methods with names like
add<Key>Object:
andremove<Key>Object:
(corresponding to theNSMutableSet
primitive methodsaddObject:
andremoveObject:
respectively) and alsoadd<Key>:
andremove<Key>:
(corresponding toNSMutableSet
methodsunionSet:
andminusSet:
). If at least one addition method and at least one removal method are found, return a proxy object that sends some combination ofadd<Key>Object:
,remove<Key>Object:
,add<Key>:
, andremove<Key>:
messages to the original receiver ofmutableSetValueForKey:
for eachNSMutableSet
message it receives.The proxy object also makes use of the methods with a name like
intersect<Key>:
orset<Key>:
for best performance, if they are available.If the receiver of the
mutableSetValueForKey:
call is a managed object, the search pattern does not continue as it would for non-managed objects. See Managed Object Accessor Methods in Core Data Programming Guide for more information.If the mutable set methods are not found, and if the object is not a managed object, search for an accessor method with a name like
set<Key>:
. If such a method is found, the returned proxy object sends aset<Key>:
message to the original receiver ofmutableSetValueForKey:
for eachNSMutableSet
message it receives.If the mutable set methods and the accessor method are not found, and if the
accessInstanceVariablesDirectly
class method returnsYES
true
, search for an instance variable with a name like_<key>
or<key>
, in that order. If such an instance variable is found, the proxy object forwards eachNSMutableSet
message it receives to the instance variable's value, which is typically an instance ofNSMutableSet
or one of its subclasses.If all else fails, the returned proxy object responds to any
NSMutableSet
message it receives by sending asetValue:forUndefinedKey:
message to the original receiver ofmutableSetValueForKey:
.
Copyright © 2018 Apple Inc. All rights reserved. Terms of Use | Privacy Policy | Updated: 2016-10-27