Class

NSKeyedUnarchiver

A decoder that restores data from an archive referenced by keys.

Declaration

@interface NSKeyedUnarchiver : NSCoder

Overview

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 throws a NSRangeException. Further, when trying to coerce a value to an incompatible type, for example decoding an int as a float, the decoding method throws an NSInvalidUnarchiveOperationException.

Topics

Initializing a Keyed Unarchiver

- initForReadingWithData:

Initializes the receiver for decoding an archive previously encoded by NSKeyedArchiver.

Deprecated

Unarchiving Data

+ unarchiveObjectWithData:

Decodes and returns the object graph previously encoded by NSKeyedArchiver and stored in a given NSData object.

Deprecated
+ unarchiveObjectWithFile:

Decodes and returns the object graph previously encoded by NSKeyedArchiver written to the file at a given path.

Deprecated
requiresSecureCoding

Indicates whether the receiver requires all unarchived classes to conform to NSSecureCoding.

Decoding Data

- containsValueForKey:

Returns a Boolean value that indicates whether the archive contains a value for a given key within the current decoding scope.

- decodeBoolForKey:

Decodes a Boolean value associated with a given key.

- decodeBytesForKey:returnedLength:

Decodes a stream of bytes associated with a given key.

- decodeDoubleForKey:

Decodes a double-precision floating-point value associated with a given key.

- decodeFloatForKey:

Decodes a single-precision floating-point value associated with a given key.

- decodeIntForKey:

Decodes an integer value associated with a given key.

- decodeInt32ForKey:

Decodes a 32-bit integer value associated with a given key.

- decodeInt64ForKey:

Decodes a 64-bit integer value associated with a given key.

- decodeObjectForKey:

Decodes and returns an object associated with a given key.

- finishDecoding

Tells the receiver that you are finished decoding objects.

Managing the Delegate

delegate

The receiver’s delegate.

Managing Class Names

+ setClass:forClassName:

Adds a class translation mapping to NSKeyedUnarchiver whereby objects encoded with a given class name are decoded as instances of a given class instead.

+ classForClassName:

Returns the class from which NSKeyedUnarchiver instantiates an encoded object with a given class name.

- setClass:forClassName:

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.

- classForClassName:

Returns the class from which the receiver instantiates an encoded object with a given class name.

Constants

Keyed Unarchiving Exception Names

Names of exceptions that are raised by NSKeyedUnarchiver if there is a problem extracting an archive.

Instance Properties

Relationships

Inherits From

See Also

Keyed Archivers

NSKeyedArchiver

A coder that stores an object's data to an archive referenced by keys.

NSKeyedArchiverDelegate

The optional methods implemented by the delegate of a keyed archiver.

NSKeyedUnarchiverDelegate

The optional methods implemented by the delegate of a keyed unarchiver.

NSCoder

An abstract class that serves as the basis for objects that enable archiving and distribution of other objects.

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software