Important: This document may not represent best practices for current development. Links to downloads and other resources may no longer be valid.
Object encoding converts an object’s class identity and state to a format that can be stored or transferred between processes. The class type and instance data are written to a byte stream that can persist after a program terminates. When the program is launched again, a newly allocated object can decode the stored representation of itself and restore itself to its previous runtime state. Encoding usually occurs in concert with archiving, which puts a graph of objects into a format (an archive) that can be written to the file system; unarchiving operates on an archive, asking each object in the stored graph to decode itself.
Object encoding is also used in the OS X distributed objects API for transferring objects from one process to another. However, its most common use is for archiving, which like a property list, is a mechanism for object persistence.
How to Encode and Decode Objects
For your subclass to encode and decode its instances, it must conform to the
NSCoding protocol and implement two methods:
encodeWithCoder:. When a program unarchives or archives an object graph, these methods are invoked. In the
encodeWithCoder: method, you encode the values of an object’s important instance variables; in the
initWithCoder: method, you decode those values and reassign them to their instance variables. If an object receives an
initWithCoder: message, none of its initializer methods are invoked.
The sole argument of
encodeWithCoder: is an
NSCoder object whose purpose is to perform the actual decoding or encoding. Because
NSCoder is an abstract class, the coder object is in most cases an instance of one of the following concrete subclasses:
NSUnarchiver. The archiver classes declare methods for encoding an object’s instance variables; the unarchiver classes declare methods for decoding instance variables.
NSCoder methods work on objects, scalars, C arrays, structures, and strings, and on pointers to these types. Before you encode or decode an instance variable of your own class, be sure to first invoke the superclass implementation of
encodeWithCoder:. When you decode objects from the byte stream, be sure to retain or copy them when you assign them to their instance variables.
Keyed Versus Sequential Archiving
Two of the concrete
NSCoder subclasses are different from each other in a fundamental way. The “keyed” archiver class (
NSKeyedUnarchiver) associate an encoded value with a string key and use that same key when decoding that value; thus instance variables can be encoded and decoded in any sequence. With the other type of coder (
NSUnarchiver) you encode instance variables in a certain sequence, and you must decode them in the same sequence. The sequential coders should be used only with legacy code; new subclasses should use keyed archive coders.