NSUnarchiver Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in OS X v10.0 and later.
Companion guide
Declared in
NSArchiver.h
Related sample code

Overview

NSUnarchiver, a concrete subclass of NSCoder, defines methods for decoding a set of Objective-C objects from an archive. Such archives are produced by objects of the NSArchiver class.

In OS X v10.2 and later, NSArchiver and NSUnarchiver have been replaced by NSKeyedArchiver and NSKeyedUnarchiver respectively—see Archives and Serializations Programming Guide.

Tasks

Initializing an NSUnarchiver

Decoding Objects

Managing an NSUnarchiver

Substituting Classes or Objects

Class Methods

classNameDecodedForArchiveClassName:

Returns the name of the class used when instantiating objects whose ostensible class, according to the archived data, is a given name.

+ (NSString *)classNameDecodedForArchiveClassName:(NSString *)nameInArchive
Parameters
nameInArchive

The name of a class.

Return Value

The name of the class used when instantiating objects whose ostensible class, according to the archived data, is nameInArchive. Returns nameInArchive if no substitute name has been specified using the class method (not the instance method) decodeClassName:asClassName:.

Discussion

Note that each individual instance of NSUnarchiver can be given its own class name mappings by invoking the instance method decodeClassName:asClassName:. The NSUnarchiver class has no information about these instance-specific mappings, however, so they don’t affect the return value of classNameDecodedForArchiveClassName:.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSArchiver.h

decodeClassName:asClassName:

Instructs instances of NSUnarchiver to use the class with a given name when instantiating objects whose ostensible class, according to the archived data, is another given name.

+ (void)decodeClassName:(NSString *)nameInArchive asClassName:(NSString *)trueName
Parameters
nameInArchive

The ostensible name of a class in an archive.

trueName

The name of the class to use when instantiating objects whose ostensible class, according to the archived data, is nameInArchive.

Discussion

This method enables easy conversion of unarchived data when the name of a class has changed since the archive was created.

Note that there is also an instance method of the same name. An instance of NSUnarchiver can maintain its own mapping of class names. However, if both the class method and the instance method have been invoked using an identical value for nameInArchive, the class method takes precedence.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSArchiver.h

unarchiveObjectWithData:

Decodes and returns the object archived in a given NSData object.

+ (id)unarchiveObjectWithData:(NSData *)data
Parameters
data

An NSData object that contains an archive created using NSArchiver.

Return Value

The object, or object graph, that was archived in data. Returns nil if data cannot be unarchived.

Discussion

This method invokes initForReadingWithData: and decodeObject to create a temporary NSUnarchiver object that decodes the object. If the archived object is the root of a graph of objects, the entire graph is unarchived.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSArchiver.h

unarchiveObjectWithFile:

Decodes and returns the object archived in the file path.

+ (id)unarchiveObjectWithFile:(NSString *)path
Parameters
path

The path to a file than contains an archive created using NSArchiver.

Return Value

The object, or object graph, that was archived in the file at path. Returns nil if the file at path cannot be unarchived.

Discussion

This convenience method reads the file by invoking the NSData method dataWithContentsOfFile: and then invokes unarchiveObjectWithData:.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSArchiver.h

Instance Methods

classNameDecodedForArchiveClassName:

Returns the name of the class that will be used when instantiating objects whose ostensible class, according to the archived data, is a given name.

- (NSString *)classNameDecodedForArchiveClassName:(NSString *)nameInArchive
Parameters
nameInArchive

The ostensible name of a class in an archive.

Return Value

The name of the class that will be used when instantiating objects whose ostensible class, according to the archived data, is nameInArchive. Returns nameInArchive unless a substitute name has been specified using the instance method (not the class method) decodeClassName:asClassName:.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSArchiver.h

decodeClassName:asClassName:

Instructs the receiver to use the class with a given name when instantiating objects whose ostensible class, according to the archived data, is another given name.

- (void)decodeClassName:(NSString *)nameInArchive asClassName:(NSString *)trueName
Parameters
nameInArchive

The ostensible name of a class in an archive.

trueName

The name of the class to use when instantiating objects whose ostensible class, according to the archived data, is nameInArchive.

Discussion

This method enables easy conversion of unarchived data when the name of a class has changed since the archive was created.

Note that there’s also a class method of the same name. The class method has precedence in case of conflicts.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSArchiver.h

initForReadingWithData:

Returns an NSUnarchiver object initialized to read an archive from a given data object.

- (id)initForReadingWithData:(NSData *)data
Parameters
data

The archive data.

Return Value

An NSUnarchiver object initialized to read an archive from data. Returns nil if data is not a valid archive.

Discussion

The method decodes the system version number that was archived in data prepares the NSUnarchiver object for a subsequent invocation of decodeObject.

Raises an NSInvalidArgumentException if data is nil.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSArchiver.h

isAtEnd

Returns a Boolean value that indicates whether the receiver has reached the end of the encoded data while decoding.

- (BOOL)isAtEnd
Return Value

YES if the receiver has reached the end of the encoded data while decoding, otherwise NO.

Discussion

You can invoke this method after invoking decodeObject to discover whether the archive contains extra data following the encoded object graph. If it does, you can either ignore this anomaly or consider it an error.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSArchiver.h

objectZone

Returns the memory zone used to allocate decoded objects.

- (NSZone *)objectZone
Return Value

The memory zone used to allocate decoded objects.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSArchiver.h

replaceObject:withObject:

Causes the receiver to substitute one given object for another whenever the latter is extracted from the archive.

- (void)replaceObject:(id)object withObject:(id)newObject
Parameters
object

The archived object to replace.

newObject

The object with which to replace object.

Discussion

newObject can be of a different class from object, and the class mappings set by classNameDecodedForArchiveClassName: and decodeClassName:asClassName: are ignored.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSArchiver.h

setObjectZone:

Sets the memory zone used to allocate decoded objects.

- (void)setObjectZone:(NSZone *)zone
Parameters
zone

The memory zone used to allocate decoded objects.

Discussion

If zone is nil, or if this method is never invoked, the default zone is used, as given by NSDefaultMallocZone().

Availability
  • Available in OS X v10.0 and later.
Declared In
NSArchiver.h

systemVersion

Returns the system version number in effect when the archive was created.

- (unsigned)systemVersion
Return Value

The system version number in effect when the archive was created.

Discussion

This information is available as soon as the receiver has been initialized.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSArchiver.h