Class

NSCoder

An abstract class that serves as the basis for objects that enable archiving and distribution of other objects.

Declaration

@interface NSCoder : NSObject

Overview

NSCoder declares the interface used by concrete subclasses to transfer objects and other values between memory and some other format. This capability provides the basis for archiving (storing objects and data on disk) and distribution (copying objects and data items between different processes or threads). The concrete subclasses provided by Foundation for these purposes are NSArchiver, NSUnarchiver, NSKeyedArchiver, NSKeyedUnarchiver, and NSPortCoder. Concrete subclasses of NSCoder are “coder classes”, and instances of these classes are “coder objects” (or simply “coders”). A coder that can only encode values is an “encoder”, and one that can only decode values is a “decoder”.

NSCoder operates on objects, scalars, C arrays, structures, strings, and on pointers to these types. It doesn’t handle types whose implementation varies across platforms, such as union, void *, function pointers, and long chains of pointers. A coder 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. An object can change its class when encoded, however; this is described in Archives and Serializations Programming Guide.

The AVFoundation framework adds methods to the NSCoder class to make it easier to create archives including Core Media time structures, and extract Core Media time structure from archives.

Subclassing Notes

For details of how to create a subclass of NSCoder, see Subclassing NSCoder in Archives and Serializations Programming Guide.

Topics

Inspecting a Coder

allowsKeyedCoding

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

- containsValueForKey:

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

decodingFailurePolicy

The action the coder should take when decoding fails.

NSDecodingFailurePolicy

Policies describing the action the coder should take when encountering decode failures.

Encoding General Data

- encodeArrayOfObjCType:count:at:

Encodes an array of the given Objective-C type, provided the number of items and a pointer.

- encodeBool:forKey:

Encodes a Boolean value and associates it with the string key.

- encodeBycopyObject:

An encoding method for subclasses to override such that it creates a copy, rather than a proxy, when decoded.

- encodeByrefObject:

An encoding method for subclasses to override such that it creates a proxy, rather than a copy, when decoded.

- encodeBytes:length:

Encodes a buffer of data of an unspecified type.

- encodeBytes:length:forKey:

Encodes a buffer of data, given its length and a pointer, and associates it with a string key.

- encodeConditionalObject:

An encoding method for subclasses to override to conditionally encode an object, preserving common references to it.

- encodeConditionalObject:forKey:

An encoding method for subclasses to override to conditionally encode an object, preserving common references to it, only if it has been unconditionally encoded.

- encodeDataObject:

Encodes a given data object.

- encodeDouble:forKey:

Encodes a double-precision floating point value and associates it with the string key.

- encodeFloat:forKey:

Encodes a floating point value and associates it with the string key.

- encodeInt:forKey:

Encodes a C integer value and associates it with the string key.

- encodeInteger:forKey:

Encodes an integer value and associates it with the string key.

- encodeInt32:forKey:

Encodes a 32-bit integer value and associates it with the string key.

- encodeInt64:forKey:

Encodes a 64-bit integer value and associates it with the string key.

- encodeNXObject:

Encodes an old-style object onto the coder.

Deprecated
- encodeObject:

Encodes an object.

- encodeObject:forKey:

Encodes an object and associates it with the string key.

- encodePoint:

Encodes a point.

- encodePoint:forKey:

Encodes a point and associates it with the string key.

- encodePropertyList:

Encodes a property list.

- encodeRect:

Encodes a rectangle structure.

- encodeRect:forKey:

Encodes a rectangle structure and associates it with the string key.

- encodeRootObject:

An encoding method for subclasses to override to encode an interconnected group of objects, starting with the provided root object.

- encodeSize:

Encodes a size structure.

- encodeSize:forKey:

Encodes a size structure and associates it with the given string key.

- encodeValueOfObjCType:at:

Encodes a value of the given type at the given address.

- encodeValuesOfObjCTypes:

Encodes a series of values of potentially differing Objective-C types.

Encoding Geometry-Based Data

- encodeCGAffineTransform:forKey:

Encodes an affine transform and associates it with the specified key in the receiver’s archive.

- encodeCGPoint:forKey:

Encodes a point and associates it with the specified key in the receiver’s archive.

- encodeCGRect:forKey:

Encodes a rectangle and associates it with the specified key in the receiver’s archive.

- encodeCGSize:forKey:

Encodes size information and associates it with the specified key in the coder’s archive.

- encodeCGVector:forKey:

Encodes vector data and associates it with the specified key in the coder’s archive.

- encodeDirectionalEdgeInsets:forKey:

Encodes directional edge inset data and associates it with the specified key in the coder’s archive.

- encodeUIEdgeInsets:forKey:

Encodes edge inset data and associates it with the specified key in the coder’s archive.

- encodeUIOffset:forKey:

Encodes offset data and associates it with the specified key in the coder’s archive.

Encoding Core Media Time Structures

- encodeCMTime:forKey:

Encodes a given Core Media time structure and associates it with a specified key.

- encodeCMTimeRange:forKey:

Encodes a given Core Media time range structure and associates it with a specified key.

- encodeCMTimeMapping:forKey:

Encodes a given Core Media time mapping structure and associates it with a specified key.

Secure Coding

requiresSecureCoding

Indicates whether the archiver requires all archived classes to resist object substitution attacks.

allowedClasses

The set of coded classes allowed for secure coding.

Decoding Top-Level Objects

- decodeTopLevelObjectOfClass:forKey:error:

Decode an object as an expected type, failing if the archived type does not match.

- decodeTopLevelObjectOfClasses:forKey:error:

Decode an object as one of several expected types, failing if the archived type does not match.

- decodeTopLevelObjectAndReturnError:

Decodes a previously-encoded object, populating an error if decoding fails.

- decodeTopLevelObjectForKey:error:

Decodes the previously-encoded object associated by a key, populating an error if decoding fails.

Decoding General Data

- decodeArrayOfObjCType:count:at:

Decodes an array of count items, whose Objective-C type is given by itemType.

- decodeBoolForKey:

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

- decodeBytesForKey:returnedLength:

Decodes a buffer of data that was previously encoded with encodeBytes:length:forKey: and associated with the string key.

- decodeBytesWithReturnedLength:

Decodes a buffer of data whose types are unspecified.

- decodeDataObject

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

- decodeDoubleForKey:

Decodes and returns a double value that was previously encoded with either encodeFloat:forKey: or encodeDouble:forKey: and associated with the string key.

- decodeFloatForKey:

Decodes and returns a float value that was previously encoded with encodeFloat:forKey: or encodeDouble:forKey: and associated with the string key.

- decodeIntForKey:

Decodes and returns an int value that was previously encoded with encodeInt:forKey:, encodeInteger:forKey:, encodeInt32:forKey:, or encodeInt64:forKey: and associated with the string key.

- decodeIntegerForKey:

Decodes and returns an NSInteger value that was previously encoded with encodeInt:forKey:, encodeInteger:forKey:, encodeInt32:forKey:, or encodeInt64:forKey: and associated with the string key.

- decodeInt32ForKey:

Decodes and returns a 32-bit integer value that was previously encoded with encodeInt:forKey:, encodeInteger:forKey:, encodeInt32:forKey:, or encodeInt64:forKey: and associated with the string key.

- decodeInt64ForKey:

Decodes and returns a 64-bit integer value that was previously encoded with encodeInt:forKey:, encodeInteger:forKey:, encodeInt32:forKey:, or encodeInt64:forKey: and associated with the string key.

- decodeNXObject

Decodes an object previously written with encodeNXObject:.

Deprecated
- decodeObject

Decodes and returns an object that was previously encoded with any of the encode…Object methods.

- decodeObjectForKey:

Decodes and returns a previously-encoded object that was previously encoded with encodeObject:forKey: or encodeConditionalObject:forKey: and associated with the string key.

- decodePoint

Decodes and returns an NSPoint structure that was previously encoded with encodePoint:.

- decodePointForKey:

Decodes and returns an NSPoint structure that was previously encoded with encodePoint:forKey:.

- decodePropertyList

Decodes a property list that was previously encoded with encodePropertyList:.

- decodeRect

Decodes and returns an NSRect structure that was previously encoded with encodeRect:.

- decodeRectForKey:

Decodes and returns an NSRect structure that was previously encoded with encodeRect:forKey:.

- decodeSize

Decodes and returns an NSSize structure that was previously encoded with encodeSize:.

- decodeSizeForKey:

Decodes and returns an NSSize structure that was previously encoded with encodeSize:forKey:.

- decodeValueOfObjCType:at:

Decodes a single value, whose Objective-C type is given by valueType.

Deprecated
- decodeValueOfObjCType:at:size:

Decodes a single value of a known type from the specified data buffer.

- decodeValuesOfObjCTypes:

Decodes a series of potentially different Objective-C types.

- decodeObjectOfClass:forKey:

Decodes an object for the key, restricted to the specified class.

- decodeObjectOfClasses:forKey:

Decodes an object for the key, restricted to the specified classes.

- decodePropertyListForKey:

Returns a decoded property list for the specified key.

Decoding Color Struct Data

- decodeNXColor

Decodes a color structure from NEXTSTEP Release 3 or earlier.

Deprecated

Decoding Geometry-Based Data

- decodeCGAffineTransformForKey:

Decodes and returns the Core Graphics affine transform structure associated with the specified key in the coder’s archive.

- decodeCGPointForKey:

Decodes and returns the Core Graphics point structure associated with the specified key in the coder’s archive.

- decodeCGRectForKey:

Decodes and returns the Core Graphics rectangle structure associated with the specified key in the coder’s archive.

- decodeCGSizeForKey:

Decodes and returns the Core Graphics size structure associated with the specified key in the coder’s archive.

- decodeCGVectorForKey:

Decodes and returns the Core Graphics vector data associated with the specified key in the coder’s archive.

- decodeDirectionalEdgeInsetsForKey:

Decodes and returns the UIKit directional edge insets structure associated with the specified key in the coder’s archive.

- decodeUIEdgeInsetsForKey:

Decodes and returns the UIKit edge insets structure associated with the specified key in the coder’s archive.

- decodeUIOffsetForKey:

Decodes and returns the UIKit offset structure associated with the specified key in the coder’s archive.

Decoding Core Media Time Structures

- decodeCMTimeForKey:

Returns the Core Media time structure associated with a given key.

- decodeCMTimeRangeForKey:

Returns the Core Media time range structure associated with a given key.

- decodeCMTimeMappingForKey:

Returns the Core Media time mapping structure associated with a given key.

Managing Decode Errors

- failWithError:

Signals to this coder that the decode operation has failed.

error

An error in the top-level encode.

Getting Version Information

systemVersion

The system version in effect for the archive.

- versionForClassName:

This method is present for historical reasons and is not used with keyed archivers.

Managing Zones

- objectZone

This method is present for historical reasons and has no effect.

- setObjectZone:

This method is present for historical reasons and has no effect.

Representing Geometric Types as Strings

CGAffineTransformFromString

Returns a Core Graphics affine transform structure corresponding to the data in a given string.

CGPointFromString

Returns a Core Graphics point structure corresponding to the data in a given string.

CGRectFromString

Returns a Core Graphics rectangle structure corresponding to the data in a given string.

CGSizeFromString

Returns a Core Graphics size structure corresponding to the data in a given string.

CGVectorFromString

Returns a Core Graphics vector corresponding to the data in a given string.

NSDirectionalEdgeInsetsFromString

Returns a directional edge insets structure based on the data in the specified string.

UIEdgeInsetsFromString

Returns a UIKit edge insets structure based on the data in the specified string.

UIOffsetFromString

Returns a UIKit offset structure corresponding to the data in a given string.

NSStringFromCGRect

Returns a string formatted to contain the data from a rectangle.

NSStringFromCGVector

Returns a string formatted to contain the data from a vector data structure.

NSStringFromCGAffineTransform

Returns a string formatted to contain the data from an affine transform.

NSStringFromCGPoint

Returns a string formatted to contain the data from a point.

NSStringFromCGSize

Returns a string formatted to contain the data from a size data structure.

NSStringFromDirectionalEdgeInsets

Returns a string formatted to contain the data from a directional edge insets structure.

NSStringFromUIEdgeInsets

Returns a string formatted to contain the data from an edge insets structure.

NSStringFromUIOffset

Returns a string formatted to contain the data from an offset structure.

Error Codes

NSCoderErrorMaximum

The end of the range of error codes reserved for coder errors.

NSCoderErrorMinimum

The start of the range of error codes reserved for coder errors.

NSCoderReadCorruptError

Decoding failed due to corrupt data.

NSCoderValueNotFoundError

The requested data wasn’t found.

Relationships

Inherits From

See Also

Keyed Archivers

NSKeyedArchiver

An encoder that stores an object’s data to an archive referenced by keys.

NSKeyedArchiverDelegate

The optional methods implemented by the delegate of a keyed archiver.

NSKeyedUnarchiver

A decoder that restores data from an archive referenced by keys.

NSKeyedUnarchiverDelegate

The optional methods implemented by the delegate of a keyed unarchiver.

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software