Copyright ã1994 by NeXT Computer, Inc.  All Rights Reserved.

NSCoder 

Inherits From:	NSObject

Conforms To:	NSObject (NSObject)

Declared In:	Foundation/NSCoder.h
Foundation/NSGeometry.h 

Class Description

NSCoder is an abstract class that declares the interface used by subclasses to take objects from dynamic memory and code them into and out of some other format. 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). See the NSArchiver and NSUnarchiver class specifications for more information on archiving.

NSCoder operates on the basic C and Objective C typesÐint, float, id, and so on (but excluding void * and union)Ðas well as on user-defined structures and pointers to these types. 

NSCoder declares methods that a subclass can override if it wants:

·	To encode or decode an object only under certain conditions, such as it being an intrinsic part of a larger structure (encodeRootObject: and encodeConditionalObject:). 

·	To allow decoded objects to be allocated from a specific memory zone (setObjectZone:).

·	To allow system versioning (systemVersion).

NSCoder differs from the NSSerializer and NSDeserializer classes in that NSCoders aren't restricted to operating on property list objects (objects of the NSData, NSString, NSArray, and NSDictionary classes). Also, unlike NSSerializers, NSCoders store type information along with the data. Thus, an object decoded from a stream of bytes will be of the same class as the object that was originally encoded into the stream.

Encoding and Decoding Objects

In OpenStep, coding is facilitated by methods declared in several places, most notably the NSCoder class, the NSObject class, and the NSCoding protocol.

The NSCoding protocol declares the two methods (encodeWithCoder: and initWithCoder:) that a class must implement so that objects of that class can be encoded and decoded. When an object receives an encodeWithCoder: message, it should send a message to super to encode inherited instance variables before it encodes the instance variables that it's class declares. For example, a fictitious MapView class that displays a legend and a map at various magnifications, might implement encodeWithCoder: like this:

- (void)encodeWithCoder:(NSCoder *)coder
{
    [super encodeWithCoder:coder];
    [coder encodeValuesOfObjCTypes:"si@", &mapName, &magnification, &legendView];
}

Objects are decoded in two steps. First, an object of the appropriate class is allocated and then it's sent an initWithCoder: messages to allow it to initialize its instance variables. Again, the object should first send a message to super to initialized inherited instance variables, and then it should initialize its own. MapView's implementation of this method looks like this:

- (id)initWithCoder:(NSCoder *)coder
{
    self = [super initWithCoder:coder];
    [coder decodeValuesOfObjCTypes:"si@", &mapName, &magnification, &legendView];
    return self;
}

Note the assignment of the return value of initWithCoder: to self in the example above. This is done in the subclass because the superclass, in its implementation of initWithCoder:, may decide to return a object other than itself.

There are other methods that allow an object to customize its response to encoding or decoding. NSObject declares these methods:

Method	Typical Use

classForCoder:	Allows an object, when being encoded, to substitute a class other than its own. For example, the private subclasses of a class cluster substitute the name of their public superclass when being archived.

replacementObjectForCoder:	Allows an object, when being encoded, to substitute another object for itself. For example, an object might encode itself into an archive, but encode a proxy for itself if it's being encoded for distribution.

awakeAfterUsingCoder:	Allows an object, when being decoded, to substitute another object for itself. For example, an object that represents a font might, upon being decoded, release itself and return an existing object having the same font description as itself. In this way, redundant objects can be eliminated.

See the NSObject class specification for more information.

Encoding Data

- (void)encodeArrayOfObjCType:(const char *)types	
count:(unsigned int)count	Encodes data of Objective C types listed in types having 
at:(const void *)array		count elements residing at address array.

- (void)encodeBycopyObject:(id)anObject	Overridden by subclasses to encode the supplied Objective C object so that a copy rather than a proxy of anObject is created upon decoding. NSCoder's implementation simply invokes encodeObject:.

- (void)encodeConditionalObject:(id)anObject	Overridden by subclasses to conditionally encode the supplied Objective C object. The object should be encoded only if it is an intrinsic member of the larger data structure. NSCoder's implementation simply invokes encodeObject:.

- (void)encodeDataObject:(NSData *)data	Encodes the NSData object data.

- (void)encodeObject:(id)anObject	Encodes the supplied Objective C object.

- (void)encodePropertyList:(id)aPropertyList	Encodes the supplied property list (NSData, NSArray, NSDictionary, or NSString objects).

- (void)encodePoint:(NSPoint)point	Encodes the supplied point structure.

- (void)encodeRect:(NSRect)rect	Encodes the supplied rectangle structure.

- (void)encodeRootObject:(id)rootObject	Overridden by subclasses to start encoding an interconnected group of Objective C objects, starting with rootObject. NSCoder's implementation simply invokes encodeObject:.

- (void)encodeSize:(NSSize)size	Encodes the supplied size structure.

- (void)encodeValueOfObjCType:(const char *)type	Encodes data of the specified Objective C type
at:(const void *)address		residing at address.

- (void)encodeValuesOfObjCTypes:(const char *)types,...
	Encodes values corresponding to the Objective C types listed in types argument list.

Decoding Data

- (void)decodeArrayOfObjCType:(const char *)types
count:(unsigned)count	Decodes data of Objective C types listed in type having
at:(void *)address		count elements residing at address.

- (NSData *)decodeDataObject	Decodes and returns an NSData object.

- (id)decodeObject	Decodes an Objective C object.

- (id)decodePropertyList	Decodes a property list (NSData, NSArray, NSDictionary, or NSString objects).

- (NSPoint)decodePoint	Decodes a point structure.

- (NSRect)decodeRect	Decodes a rectangle structure.

- (NSSize)decodeSize	Decodes a size structure.

- (void)decodeValueOfObjCType:(const char *)type
at:(void *)address	Decodes data of the specified Objective C type residing at address. You are responsible for releasing the resulting objects.

- (void)decodeValuesOfObjCTypes:(const char *)types,...
	Decodes values corresponding to the Objective C types listed in types argument list. You are responsible for releasing the resulting objects.

Managing Zones

- (NSZone *)objectZone	Returns the memory zone used by decoded objects. For instances of NSCoder, this is the default memory zone, the one returned by NSDefaultMallocZone().

- (void)setObjectZone:(NSZone *)zone	Sets the memory zone used by decoded objects. Instances of NSCoder always use the default memory zone, the one returned by NSDefaultMallocZone(), and so ignore this method.

Getting a Version

- (unsigned int)systemVersion	Returns the system version number as of the time the archive was created.

- (unsigned int)versionForClassName:(NSString *)className	
	Returns the version number of the class className as of the time it was archived.