Inherits from | |
Conforms to | |
Framework | /System/Library/Frameworks/Foundation.framework |
Availability | Available in Mac OS X v10.2 and later. |
Companion guide | |
Declared in | NSKeyedArchiver.h |
Related sample code |
NSKeyedUnarchiver
, a concrete subclass of NSCoder
, defines methods for decoding a set of named objects (and scalar values) from a keyed archive. Such archives are produced by instances of the NSKeyedArchiver
class.
A keyed archive is encoded as a hierarchy of objects. Each object in the hierarchy serves as a namespace into which other objects are encoded. The objects available for decoding are restricted to those that were encoded within the immediate scope of a particular object. Objects encoded elsewhere in the hierarchy, whether higher than, lower than, or parallel to this particular object, are not accessible. In this way, the keys used by a particular object to encode its instance variables need to be unique only within the scope of that object.
If you invoke one of the decode...
methods of this class using a key that does not exist in the archive, a non-positive value is returned. This value varies by decoded type. For example, if a key does not exist in an archive, decodeBoolForKey:
returns NO
, decodeIntForKey:
returns 0
, and decodeObjectForKey:
returns nil.
NSKeyedUnarchiver
supports limited type coercion. A value encoded as any type of integer, whether a standard int or an explicit 32-bit or 64-bit integer, can be decoded using any of the integer decode methods. Likewise, a value encoded as a float or double can be decoded as either a float or a double value. If an encoded value is too large to fit within the coerced type, the decoding method raises an NSRangeException
. Further, when trying to coerce a value to an incompatible type, for example decoding an int as a float, the decoding method raises an NSInvalidUnarchiveOperationException
.
– containsValueForKey:
– decodeBoolForKey:
– decodeBytesForKey:returnedLength:
– decodeDoubleForKey:
– decodeFloatForKey:
– decodeIntForKey:
– decodeInt32ForKey:
– decodeInt64ForKey:
– decodeObjectForKey:
– finishDecoding
– unarchiver:cannotDecodeObjectOfClassName:originalClasses:
delegate method
– unarchiver:didDecodeObject:
delegate method
– unarchiver:willReplaceObject:withObject:
delegate method
– unarchiverDidFinish:
delegate method
– unarchiverWillFinish:
delegate method
Returns the class from which NSKeyedUnarchiver
instantiates an encoded object with a given class name.
+ (Class)classForClassName:(NSString *)codedName
The ostensible name of a class in an archive.
The class from which NSKeyedUnarchiver
instantiates an object encoded with the class name codedName. Returns nil
if NSKeyedUnarchiver
does not have a translation mapping for codedName.
NSKeyedArchiver.h
Adds a class translation mapping to NSKeyedUnarchiver
whereby objects encoded with a given class name are decoded as instances of a given class instead.
+ (void)setClass:(Class)cls forClassName:(NSString *)codedName
The class with which to replace instances of the class named codedName.
The ostensible name of a class in an archive.
When decoding, the class’s translation mapping is used only if no translation is found first in an instance’s separate translation map.
NSKeyedArchiver.h
Decodes and returns the object graph previously encoded by NSKeyedArchiver
and stored in a given NSData
object.
+ (id)unarchiveObjectWithData:(NSData *)data
An object graph previously encoded by NSKeyedArchiver
.
The object graph previously encoded by NSKeyedArchiver
and stored in data.
This method raises an NSInvalidArchiveOperationException if data is not a valid archive.
NSKeyedArchiver.h
Decodes and returns the object graph previously encoded by NSKeyedArchiver
written to the file at a given path.
+ (id)unarchiveObjectWithFile:(NSString *)path
A path to a file that contains an object graph previously encoded by NSKeyedArchiver
.
The object graph previously encoded by NSKeyedArchiver
written to the file path. Returns nil
if there is no file at path.
This method raises an NSInvalidArgumentException
if the file at path does not contain a valid archive.
NSKeyedArchiver.h
Returns the class from which the receiver instantiates an encoded object with a given class name.
- (Class)classForClassName:(NSString *)codedName
The name of a class.
The class from which the receiver instantiates an encoded object with the class name codedName. Returns nil
if the receiver does not have a translation mapping for codedName.
The class’s separate translation map is not searched.
NSKeyedArchiver.h
Returns a Boolean value that indicates whether the archive contains a value for a given key within the current decoding scope.
- (BOOL)containsValueForKey:(NSString *)key
A key in the archive within the current decoding scope. key must not be nil
.
YES
if the archive contains a value for key within the current decoding scope, otherwise NO
.
NSKeyedArchiver.h
Decodes a Boolean value associated with a given key.
- (BOOL)decodeBoolForKey:(NSString *)key
A key in the archive within the current decoding scope. key must not be nil
.
The Boolean value associated with the key key. Returns NO
if key does not exist.
– encodeBool:forKey:
(NSKeyedArchiver
)NSKeyedArchiver.h
Decodes a stream of bytes associated with a given key.
- (const uint8_t *)decodeBytesForKey:(NSString *)key returnedLength:(NSUInteger *)lengthp
A key in the archive within the current decoding scope. key must not be nil
.
Upon return, contains the number of bytes returned.
The stream of bytes associated with the key key. Returns NULL
if key does not exist.
The returned value is a pointer to a temporary buffer owned by the receiver. The buffer goes away with the unarchiver, not the containing autorelease pool. You must copy the bytes into your own buffer if you need the data to persist beyond the life of the receiver.
– encodeBytes:length:forKey:
(NSKeyedArchiver
)NSKeyedArchiver.h
Decodes a double-precision floating-point value associated with a given key.
- (double)decodeDoubleForKey:(NSString *)key
A key in the archive within the current decoding scope. key must not be nil
.
The double-precision floating-point value associated with the key key. Returns 0.0
if key does not exist.
If the archived value was encoded as single-precision, the type is coerced.
– encodeDouble:forKey:
(NSKeyedArchiver
)– encodeFloat:forKey:
(NSKeyedArchiver
)NSKeyedArchiver.h
Decodes a single-precision floating-point value associated with a given key.
- (float)decodeFloatForKey:(NSString *)key
A key in the archive within the current decoding scope. key must not be nil
.
The single-precision floating-point value associated with the key key. Returns 0.0
if key does not exist.
If the archived value was encoded as double precision, the type is coerced, loosing precision. If the archived value is too large for single precision, the method raises an NSRangeException
.
– encodeFloat:forKey:
(NSKeyedArchiver
)– encodeDouble:forKey:
(NSKeyedArchiver
)NSKeyedArchiver.h
Decodes a 32-bit integer value associated with a given key.
- (int32_t)decodeInt32ForKey:(NSString *)key
A key in the archive within the current decoding scope. key must not be nil
.
The 32-bit integer value associated with the key key. Returns 0
if key does not exist.
If the archived value was encoded with a different size but is still an integer, the type is coerced. If the archived value is too large to fit into a 32-bit integer, the method raises an NSRangeException
.
– encodeInt32:forKey:
(NSKeyedArchiver
)NSKeyedArchiver.h
Decodes a 64-bit integer value associated with a given key.
- (int64_t)decodeInt64ForKey:(NSString *)key
A key in the archive within the current decoding scope. key must not be nil
.
The 64-bit integer value associated with the key key. Returns 0
if key does not exist.
If the archived value was encoded with a different size but is still an integer, the type is coerced.
– encodeInt64:forKey:
(NSKeyedArchiver
)NSKeyedArchiver.h
Decodes an integer value associated with a given key.
- (int)decodeIntForKey:(NSString *)key
A key in the archive within the current decoding scope. key must not be nil
.
The integer value associated with the key key
. Returns 0
if key does not exist.
If the archived value was encoded with a different size but is still an integer, the type is coerced. If the archived value is too large to fit into the default size for an integer, the method raises an NSRangeException
.
– encodeInt:forKey:
(NSKeyedArchiver
)NSKeyedArchiver.h
Decodes and returns an object associated with a given key.
- (id)decodeObjectForKey:(NSString *)key
A key in the archive within the current decoding scope. key must not be nil
.
The object associated with the key key. Returns nil
if key does not exist, or if the value for key is nil
.
– encodeObject:forKey:
(NSKeyedArchiver
)NSKeyedArchiver.h
Returns the receiver’s delegate.
- (id)delegate
The receiver’s delegate.
NSKeyedArchiver.h
Tells the receiver that you are finished decoding objects.
- (void)finishDecoding
Invoking this method allows the receiver to notify its delegate and to perform any final operations on the archive. Once this method is invoked, the receiver cannot decode any further values.
NSKeyedArchiver.h
Initializes the receiver for decoding an archive previously encoded by NSKeyedArchiver
.
- (id)initForReadingWithData:(NSData *)data
An archive previously encoded by NSKeyedArchiver
.
An NSKeyedUnarchiver
object initialized for for decoding data.
When you finish decoding data, you should invoke finishDecoding
.
This method raises an NSInvalidArchiveOperationException if data is not a valid archive.
NSKeyedArchiver.h
Adds a class translation mapping to the receiver whereby objects encoded with a given class name are decoded as instances of a given class instead.
- (void)setClass:(Class)cls forClassName:(NSString *)codedName
The class with which to replace instances of the class named codedName.
The ostensible name of a class in an archive.
When decoding, the receiver’s translation map overrides any translation that may also be present in the class’s map (see setClass:forClassName:).
NSKeyedArchiver.h
Sets the receiver’s delegate.
- (void)setDelegate:(id)delegate
The delegate for the receiver.
NSKeyedArchiver.h
Informs the delegate that the class with a given name is not available during decoding.
- (Class)unarchiver:(NSKeyedUnarchiver *)unarchiver cannotDecodeObjectOfClassName:(NSString *)name originalClasses:(NSArray *)classNames
An unarchiver for which the receiver is the delegate.
The name of the class of an object unarchiver
is trying to decode.
An array describing the class hierarchy of the encoded object, where the first element is the class name string of the encoded object, the second element is the class name of its immediate superclass, and so on.
The class unarchiver should use in place of the class named name.
The delegate may, for example, load some code to introduce the class to the runtime and return the class, or substitute a different class object. If the delegate returns nil
, unarchiving aborts and the method raises an NSInvalidUnarchiveOperationException
.
NSKeyedArchiver.h
Informs the delegate that a given object has been decoded.
- (id)unarchiver:(NSKeyedUnarchiver *)unarchiver didDecodeObject:(id)object
An unarchiver for which the receiver is the delegate.
The object that has been decoded. object may be nil
.
The object to use in place of object. The delegate can either return object or return a different object to replace the decoded one. If the delegate returns nil
, nil
is the result of decoding object.
This method is called after object has been sent initWithCoder:
and awakeAfterUsingCoder:
.
The delegate may use this method to keep track of the decoded objects.
NSKeyedArchiver.h
Informs the delegate that one object is being substituted for another.
- (void)unarchiver:(NSKeyedUnarchiver *)unarchiver willReplaceObject:(id)object withObject:(id)newObject
An unarchiver for which the receiver is the delegate.
An object in the archive.
The object with which unarchiver will replace object.
This method is called even when the delegate itself is doing, or has done, the substitution with unarchiver:didDecodeObject:
.
The delegate may use this method if it is keeping track of the encoded or decoded objects.
NSKeyedArchiver.h
Notifies the delegate that decoding has finished.
- (void)unarchiverDidFinish:(NSKeyedUnarchiver *)unarchiver
An unarchiver for which the receiver is the delegate.
NSKeyedArchiver.h
Notifies the delegate that decoding is about to finish.
- (void)unarchiverWillFinish:(NSKeyedUnarchiver *)unarchiver
An unarchiver for which the receiver is the delegate.
NSKeyedArchiver.h
Names of exceptions that are raised by NSKeyedUnarchiver
if there is a problem extracting an archive.
extern NSString *NSInvalidUnarchiveOperationException;
NSInvalidUnarchiveOperationException
The name of the exception raised by NSKeyedArchiver
if there is a problem extracting an archive.
Available in Mac OS X v10.2 and later.
Declared in NSKeyedArchiver.h
.
NSKeyedUnarchiver.h
© 2008 Apple Inc. All Rights Reserved. (Last updated: 2008-10-15)