NSCoding Protocol Reference

Adopted by
Various Cocoa classes
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in OS X v10.0 and later.
Companion guide
Declared in
NSObject.h
Related sample code
With and Without Bindings

Overview

The NSCoding protocol declares the two methods that a class must implement so that instances of that class can be encoded and decoded. This capability provides the basis for archiving (where objects and other structures are stored on disk) and distribution (where objects are copied to different address spaces).

In keeping with object-oriented design principles, an object being encoded or decoded is responsible for encoding and decoding its instance variables. A coder instructs the object to do so by invoking encodeWithCoder: or initWithCoder:. encodeWithCoder: instructs the object to encode its instance variables to the coder provided; an object can receive this method any number of times. initWithCoder: instructs the object to initialize itself from data in the coder provided; as such, it replaces any other initialization method and is sent only once per object. Any object class that should be codable must adopt the NSCoding protocol and implement its methods.

It is important to consider the possible types of archiving that a coder supports. On OS X version 10.2 and later, keyed archiving is preferred. You may, however, need to support classic archiving. For details, see Archives and Serializations Programming Guide.

Tasks

Initializing with a Coder

Encoding with a Coder

Instance Methods

encodeWithCoder:

Encodes the receiver using a given archiver. (required)

- (void)encodeWithCoder:(NSCoder *)encoder
Parameters
encoder

An archiver object.

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

initWithCoder:

Returns an object initialized from data in a given unarchiver. (required)

- (id)initWithCoder:(NSCoder *)decoder
Parameters
decoder

An unarchiver object.

Return Value

self, initialized using the data in decoder.

Discussion

You must return self from initWithCoder:. If you have an advanced need that requires substituting a different object after decoding, you can do so in awakeAfterUsingCoder:.

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