- Inherits from:
- NSObject
- Package:
- com.apple.yellow.foundation
The NSCoder abstract class declares the interface used by concrete subclasses to transfer objects and other data items between memory and some other format. This capability provides the basis for archiving (where objects and data items are stored on disk) and distribution (where objects and data items are copied between different processes or threads). The concrete subclasses provided by Foundation for these purposes are NSArchiver and NSUnarchiver. Concrete subclasses of NSCoder are referred to in general as coder classes, and instances of these classes as coder objects (or simply coders). A coder object that can only encode values is referred to as an encoder object, and one that can only decode values as a decoder object.
NSCoder operates on id's, scalars, arrays, structures, and strings, and on pointers to these types. It does not handle types whose implementation varies across platforms function pointers, and long chains of pointers. It can also operate on user-defined structures as well as pointers to any of these data types. A coder object stores object type information along with the data, so an object decoded from a stream of bytes is normally of the same class as the object that was originally encoded into the stream.
To encode or decode an object or data item, you must first create a coder object, then send it a message defined by NSCoder or by a concrete subclass to actually encode or decode the item. NSCoder itself defines no particular method for creating a coder; this typically varies with the subclass.
To encode an object or data item, use any of the encode... methods..
To decode an object or data item, simply use the decode... method corresponding to the original encode... method (as given in the individual method descriptions). Matching these is important, as the method originally used determines the format of the encoded data.
NSCoder's interface is quite general. Concrete subclasses aren't required to properly implement all of NSCoder's methods, and may explicitly restrict themselves to certain types of operations. For example, NSArchiver doesn't implement the decode... methods, and NSUnarchiver doesn't implement the encode... methods.
Objects frequently contain pointers to other objects, which may in turn contain pointers to other objects. When analyzed, a group of objects may contain circular references or one object may be referred to by several other objects. In these cases, the objects form an object graph and require special encoding methods to preserve the graph structure. NSCoder declares the following method to manage object graphs: encodeObject.
See the NSArchiver class specification for more information on managing object graphs.
If you define a subclass of NSCoder, at a minimum your subclass must override the following methods:
In addition, your subclass may override other methods to provide specialized handling for certain situations. In particular, you can implement any of the following methods:
See the individual method descriptions for more information. See also the NSArchiver class specification for an example of a concrete subclass.
With objects, the object being coded is fully responsible for coding itself. However, a few classes hand this responsibility back to the coder object, either for performance reasons or because proper support depends on more information than the object itself has. The notable class in Foundation that does this is NSData. NSData's low-level nature makes optimization important. For this reason, an NSData object always asks its coder to handle its contents directly using the encodeDataObject and decodeDataObject methods described in this class specification.
An implementor of a concrete coder subclass, however, must encode NSData objects itself. Failure to do so can result in an infinite loop.
- Constructors
- NSCoder
- Encoding data
- encodeByte
- encodeChar
- encodeDataObject
- encodeDouble
- encodeFloat
- encodeInt
- encodeLong
- encodeObject
- encodeShort
- Decoding data
- decodeByte
- decodeChar
- decodeDataObject
- decodeDouble
- decodeFloat
- decodeInt
- decodeLong
- decodeObject
- decodeShort
- Getting version information
- systemVersion
- versionForClassName
public NSCoder()
public abstract byte decodeByte()
public abstract char decodeChar()
public abstract NSData decodeDataObject()
The implementation of your overriding method must match the implementation of your encodeDataObject method. For example, a typical encodeDataObject method encodes the number of bytes of data followed by the bytes themselves. Your override of this method must read the number of bytes, create an NSData object of the appropriate size, and decode the bytes into the new NSData object. Your overriding method should return an NSData object.
public abstract double decodeDouble()
public abstract float decodeFloat()
public abstract int decodeInt()
public abstract long decodeLong()
public abstract Object decodeObject()
Subclasses must override this method.
See Also: encodeObject
public abstract short decodeShort()
public abstract void encodeByte(byte aByte)
This method must be matched by a subsequent decodeByte message.
public abstract void encodeChar(char aChar)
This method must be matched by a subsequent decodeChar message.
public abstract void encodeDataObject(NSData data)
See Also: encodeObject
public abstract void encodeDouble(double aDouble)
This method must be matched by a subsequent decodeDouble message.
public abstract void encodeFloat(float aFloat)
This method must be matched by a subsequent decodeFloat message.
public abstract void encodeInt(int anInt)
This method must be matched by a subsequent decodeInt message.
public abstract void encodeLong(long aLong)
This method must be matched by a subsequent decodeLong message.
public abstract void encodeObject(Object object)
This method must be matched by a subsequent decodeObject message.
public abstract void encodeShort(short aShort)
This method must be matched by a subsequent decodeShort message.
public int systemVersion()
By default, this method returns the current system version, which is appropriate for encoding but not for decoding. Subclasses that implement decoding must override this method to return the system version of the data being decoded.
public abstract int versionForClassName(String className)
NotFound
if
no class named className exists in
the archive.