---

NSCoder

Overview

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, NSUnarchiver, NSKeyedArchiver, and NSKeyedUnarchiver. 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 objects, scalars, arrays, structures, and strings. It does not handle types whose implementation varies across platforms. 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.

Tasks

Constructors

• NSCoder

Testing Coder

• allowsKeyedCoding
• containsValueForKey

Encoding Data

• encodeBoolForKey
• encodeByte
• encodeByteForKey
• encodeChar
• encodeCharForKey
• encodeConditionalObjectForKey
• encodeDataObject
• encodeDouble
• encodeDoubleForKey
• encodeFloat
• encodeFloatForKey
• encodeIntForKey
• encodeInt
• encodeLong
• encodeLongForKey
• encodeObject
• encodeObjectForKey
• encodeShort
• encodeShortForKey

Decoding Data

• decodeBoolForKey
• decodeByte
• decodeByteForKey
• decodeChar
• decodeCharForKey
• decodeDataObject
• decodeDouble
• decodeDoubleForKey
• decodeFloat
• decodeFloatForKey
• decodeInt
• decodeIntForKey
• decodeLong
• decodeLongForKey
• decodeObject
• decodeObjectForKey
• decodeShort
• decodeShortForKey

Getting Version Information

• systemVersion
• versionForClassName

Instance Methods

allowsKeyedCoding

Returns a Boolean value that indicates whether the receiver supports keyed coding of objects.

public boolean allowsKeyedCoding()

Discussion

The default implementation returns false. Concrete subclasses that support keyed coding, such as NSKeyedArchiver, need to override this method to return true.

Availability

• Available in Mac OS X v10.2 and later.

containsValueForKey

Returns a Boolean value that indicates whether an encoded value is available for a string.

public boolean containsValueForKey(String key)

Discussion

The string is passed as key. Subclasses must override this method if they perform keyed coding.

Availability

• Available in Mac OS X v10.2 and later.

decodeBoolForKey

Decodes and returns a boolean value that was previously encoded with encodeBoolForKey and associated with the string key.

public boolean decodeBoolForKey(String key)

Discussion

Subclasses must override this method if they perform keyed coding.

Availability

• Available in Mac OS X v10.2 and later.

decodeByte

Decodes and returns a byte value that was previously encoded with encodeByte.

public byte decodeByte()

Discussion

Subclasses must override this method.

decodeByteForKey

Decodes and returns a byte value that was previously encoded with encodeByteForKey and associated with the string key.

public byte decodeByteForKey(String key)

Discussion

Subclasses must override this method if they perform keyed coding.

Availability

• Available in Mac OS X v10.2 and later.

decodeChar

Decodes and returns a char value that was previously encoded with encodeChar.

public char decodeChar()

Discussion

Subclasses must override this method.

decodeCharForKey

Decodes and returns a char value that was previously encoded with encodeCharForKey and associated with the string key.

public char decodeCharForKey(String key)

Discussion

Subclasses must override this method if they perform keyed coding.

Availability

• Available in Mac OS X v10.2 and later.

decodeDataObject

Decodes and returns an NSData object that was previously encoded with encodeDataObject. Subclasses must override this method.

public NSData decodeDataObject()

Discussion

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.

decodeDouble

Decodes and returns a double value that was previously encoded with encodeDouble.

public double decodeDouble()

Discussion

Subclasses must override this method.

decodeDoubleForKey

Decodes and returns a double value that was previously encoded with either encodeFloatForKey or encodeDoubleForKey and associated with the string key.

public double decodeDoubleForKey(String key)

Discussion

Subclasses must override this method if they perform keyed coding.

Availability

• Available in Mac OS X v10.2 and later.

decodeFloat

Decodes and returns a float value that was previously encoded with encodeFloat.

public float decodeFloat()

Discussion

Subclasses must override this method.

decodeFloatForKey

Decodes and returns a float value that was previously encoded with encodeFloatForKey or encodeDoubleForKey and associated with the string key.

public float decodeFloatForKey(String key)

Discussion

If the value was encoded as a double, the extra precision is lost. Also, if the encoded real value does not fit into a float, the method throws a RangeException. Subclasses must override this method if they perform keyed coding.

Availability

• Available in Mac OS X v10.2 and later.

decodeInt

Decodes and returns an int value that was previously encoded with encodeInt.

public int decodeInt()

Discussion

Subclasses must override this method.

decodeIntForKey

Decodes and returns an int value that was previously encoded with encodeIntForKey, encodeShortForKey, or encodeLongForKey and associated with the string key.

public int decodeIntForKey(String key);

Discussion

If the encoded integer does not fit into the default integer size, the method throws a RangeException. Subclasses must override this method if they perform keyed coding.

Availability

• Available in Mac OS X v10.2 and later.

decodeLong

Decodes and returns a long value that was previously encoded with encodeLong.

public long decodeLong()

Discussion

Subclasses must override this method.

decodeLongForKey

Decodes and returns a long value that was previously encoded with encodeShortForKey, encodeIntForKey, or encodeLongForKey and associated with the string key.

public long decodeLongForKey(String key)

Discussion

Subclasses must override this method if they perform keyed coding.

Availability

• Available in Mac OS X v10.2 and later.

decodeObject

Decodes an object that was previously encoded with any of the encode... methods.

public Object decodeObject()

Discussion

Subclasses may need to override this method.

See Also

• encodeObject

decodeObjectForKey

Decodes and returns an object that was previously encoded with encodeObjectForKey or encodeConditionalObjectForKey and associated with the string key.

public Object decodeObjectForKey(String key)

Discussion

Subclasses must override this method if they perform keyed coding.

Availability

• Available in Mac OS X v10.2 and later.

decodeShort

Decodes and returns a short value that was previously encoded with encodeShort.

public short decodeShort()

Discussion

Subclasses must override this method.

decodeShortForKey

Decodes and returns a short value that was previously encoded with encodeShortForKey, encodeIntForKey, or encodeLongForKey and associated with the string key.

public short decodeShortForKey(String key)

Discussion

If the encoded integer does not fit into the default integer size, the method throws a RangeException. Subclasses must override this method if they perform keyed coding.

Availability

• Available in Mac OS X v10.2 and later.

encodeBoolForKey

Encodes boolv and associates it with the string key.

public void encodeBoolForKey(boolean boolv, String key)

Discussion

Subclasses must override this method if they perform keyed coding.

Availability

• Available in Mac OS X v10.2 and later.

See Also

• decodeBoolForKey

encodeByte

Encodes aByte.

public void encodeByte(byte aByte)

Discussion

Subclasses must override this method.

This method must be matched by a subsequent decodeByte message.

encodeByteForKey

Encodes bytev and associates it with the string key.

public void encodeByteForKey(byte bytev, String key)

Availability

• Available in Mac OS X v10.2 and later.

See Also

• decodeByteForKey

encodeChar

Encodes aChar.

public void encodeChar(char aChar)

Discussion

Subclasses must override this method.

This method must be matched by a subsequent decodeChar message.

encodeCharForKey

Encodes charv and associates it with the string key.

public void encodeCharForKey(char charv, String key)

Availability

• Available in Mac OS X v10.2 and later.

See Also

• decodeCharForKey

encodeConditionalObjectForKey

Conditionally encodes a reference to objv and associates it with the string key only if objv has been unconditionally encoded with encodeObjectForKey.

public void encodeConditionalObjectForKey(Object objv, String key)

Discussion

Subclasses must override this method if they support keyed coding.

The encoded object is decoded with the decodeObjectForKey method. If objv was never encoded unconditionally, decodeObjectForKey returns null in place of objv.

Availability

• Available in Mac OS X v10.2 and later.

encodeDataObject

Encodes the NSData object data.

public void encodeDataObject(NSData data)

Discussion

Subclasses must override this method.

This method must be matched by a subsequent decodeDataObject message.

See Also

• encodeObject

encodeDouble

Encodes aDouble.

public void encodeDouble(double aDouble)

Discussion

Subclasses must override this method.

This method must be matched by a subsequent decodeDouble message.

encodeDoubleForKey

Encodes realv and associates it with the string key.

public void encodeDoubleForKey(double realv, String key)

Discussion

Subclasses must override this method if they perform keyed coding.

Availability

• Available in Mac OS X v10.2 and later.

See Also

• decodeDoubleForKey
• decodeFloatForKey

encodeFloat

Encodes aFloat.

public void encodeFloat(float aFloat)

Discussion

Subclasses must override this method.

This method must be matched by a subsequent decodeFloat message.

encodeFloatForKey

Encodes realv and associates it with the string key.

public void encodeFloatForKey(float realv, String key)

Discussion

Subclasses must override this method if they perform keyed coding.

Availability

• Available in Mac OS X v10.2 and later.

See Also

• decodeFloatForKey
• decodeDoubleForKey

encodeInt

Encodes anInt.

public void encodeInt(int anInt)

Discussion

Subclasses must override this method.

This method must be matched by a subsequent decodeInt message.

encodeIntForKey

Encodes intv and associates it with the string key.

public void encodeIntForKey(int intv, String key)

Discussion

Subclasses must override this method if they perform keyed coding.

Availability

• Available in Mac OS X v10.2 and later.

See Also

• decodeIntForKey
• decodeLongForKey
• decodeShortForKey

encodeLong

Encodes aLong.

public void encodeLong(long aLong)

Discussion

Subclasses must override this method.

This method must be matched by a subsequent decodeLong message.

encodeLongForKey

Encodes longv and associates it with the string key.

public void encodeLongForKey(long longv, String key)

Availability

• Available in Mac OS X v10.2 and later.

See Also

• decodeLongForKey
• decodeIntForKey
• decodeShortForKey

encodeObject

Encodes object.

public void encodeObject(Object object)

Discussion

Subclasses must override this method. For example, NSArchiver detects duplicate objects and encodes a reference to the original object rather than encode the same object twice.

This method must be matched by a subsequent decodeObject message.

encodeObjectForKey

Encodes the object objv and associates it with the string key.

public void encodeObjectForKey(Object objv, String key)

Discussion

Subclasses must override this method to identify multiple encodings of objv and encode a reference to objv instead. For example, NSKeyedArchiver detects duplicate objects and encodes a reference to the original object rather than encode the same object twice.

Availability

• Available in Mac OS X v10.2 and later.

See Also

• decodeObjectForKey

encodeShort

Encodes aShort.

public void encodeShort(short aShort)

Discussion

Subclasses must override this method.

This method must be matched by a subsequent decodeShort message.

encodeShortForKey

Encodes shortv and associates it with the string key.

public void encodeShortForKey(short shortv, String key)

Availability

• Available in Mac OS X v10.2 and later.

See Also

• decodeShortForKey
• decodeLongForKey
• decodeIntForKey

systemVersion

During encoding, this method should return the system version currently in effect.

public int systemVersion()

Discussion

During decoding, this method should return the version that was in effect when the data was encoded.

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.

versionForClassName

Returns the version in effect for the class named className or NSArray.NotFound if no class named className exists.

public abstract int versionForClassName(String className)

Discussion

When encoding, this method returns the current version number of the class. When decoding, this method returns the version number of the class being decoded. Subclasses must override this method.

Constants

The following exceptions may be thrown when an error is encountered:

---