---

NSUnarchiver

Overview

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

Tasks

Constructors

• NSUnarchiver

Decoding Objects

• decodeByte
• decodeChar
• decodeDataObject
• decodeDouble
• decodeFloat
• decodeInt
• decodeLong
• decodeObject
• decodeShort
• unarchiveObjectWithData
• unarchiveObjectWithFile

Managing an NSUnarchiver

• isAtEnd
• data
• versionForClassName

Substituting Classes or Objects

• classNameGloballyDecodedForArchiveClassName
• globallyDecodeClassNameAsClassName
• classNameDecodedForArchiveClassName
• decodeClassNameAsClassName
• replaceObject

Static Methods

classNameGloballyDecodedForArchiveClassName

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

public static String classNameGloballyDecodedForArchiveClassName(String nameInArchive)

Discussion

This method returns nameInArchive if no substitute name has been specified using the static method (not the instance method) globallyDecodeClassNameAsClassName.

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

See Also

• classNameDecodedForArchiveClassName

globallyDecodeClassNameAsClassName

Instructs instances of NSUnarchiver to use the class named trueName when instantiating objects whose ostensible class, according to the archived data, is nameInArchive.

public static void globallyDecodeClassNameAsClassName(String nameInArchive, String trueName)

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 a similar 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.

See Also

• classNameGloballyDecodedForArchiveClassName
• decodeClassNameAsClassName

unarchiveObjectWithData

Decodes and returns the object archived in data.

public static Object unarchiveObjectWithData(NSData data)

Discussion

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

Archives are produced by objects of the NSArchiver class.

See Also

• encodeRootObject (NSArchiver)

unarchiveObjectWithFile

Decodes and returns the object archived in the file path.

public static Object unarchiveObjectWithFile(String path)

Discussion

This convenience method reads the file and then invokes unarchiveObjectWithData.

Archives are produced by objects of the NSArchiver class.

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 nameInArchive.

public String classNameDecodedForArchiveClassName(String nameInArchive)

Discussion

This method returns nameInArchive unless a substitute name has been specified using the instance method (not the static method) decodeClassNameAsClassName.

See Also

• classNameGloballyDecodedForArchiveClassName

data

Returns the archive data.

public NSData data()

Discussion

The returned data object is the same one specified as the argument to the constructor.

decodeByte

Decodes and returns a byte value that was previously encoded with encodeByte.

public byte decodeByte()

decodeChar

Decodes and returns a char value that was previously encoded with encodeChar.

public char decodeChar()

decodeClassNameAsClassName

Instructs the receiver to use the class named trueName when instantiating objects whose ostensible class, according to the archived data, is nameInArchive.

public void decodeClassNameAsClassName(String nameInArchive, String trueName)

Discussion

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

See Also

• classNameDecodedForArchiveClassName
• globallyDecodeClassNameAsClassName

decodeDataObject

Decodes and returns an NSData object that was previously encoded with encodeDataObject.

public NSData decodeDataObject()

decodeDouble

Decodes and returns a double value that was previously encoded with encodeDouble.

public double decodeDouble()

decodeFloat

Decodes and returns a float value that was previously encoded with encodeFloat.

public float decodeFloat()

decodeInt

Decodes and returns an int value that was previously encoded with encodeInt.

public int decodeInt()

decodeLong

Decodes and returns a long value that was previously encoded with encodeLong.

public long decodeLong()

decodeObject

Decodes and returns an Object object that was previously encoded with encodeObject.

public Object decodeObject()

decodeShort

Decodes and returns a short value that was previously encoded with encodeShort.

public short decodeShort()

isAtEnd

Returns true if the receiver has reached the end of the encoded data while decoding, false if more data follows.

public boolean isAtEnd()

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.

replaceObject

Causes the receiver to substitute newObject for object whenever object is extracted from the archive.

public void replaceObject(Object object, Object newObject)

Discussion

newObject can be of a different class from object, and the class mappings set by classNameGloballyDecodedForArchiveClassName and decodeClassNameAsClassName are ignored.

versionForClassName

Returns the version number for the archived implementation of the class named className or NSArray.NotFound if no class named className exists in the archive.

public int versionForClassName(String className)

Discussion

The class version number of each encoded object is written to the archive so that newer versions of the class can detect and properly decode older archived versions.

---