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: initWithCoder: and 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 initWithCoder: and 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: NSKeyedArchiver, NSKeyedUnarchiver, NSArchiver, NSUnarchiver. The archiver classes declare methods for encoding an object’s instance variables; the unarchiver classes declare methods for decoding instance variables.

The 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 initWithCoder: or 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 (NSKeyedArchiver and 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 (NSArchiver and 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.