Mac Developer Library

Developer

Foundation Framework Reference NSCoder Class Reference

Options
Deployment Target:

On This Page
Language:

NSCoder

Conforms To


Import Statement


Swift

import Foundation

Objective-C

@import Foundation;

Availability


Available in OS X v10.0 and later.

The NSCoder abstract class 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 (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, NSKeyedUnarchiver, and NSPortCoder. 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, C arrays, structures, and strings, and on pointers to these types. It does not handle types whose implementation varies across platforms, such as union, void *, function pointers, and long chains of pointers. 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. An object can change its class when encoded, however; this is described in Archives and Serializations Programming Guide.

The AV Foundation 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.

  • A Boolean value that indicates whether the receiver supports keyed coding of objects. (read-only)

    Declaration

    Swift

    var allowsKeyedCoding: Bool { get }

    Objective-C

    @property(readonly) BOOL allowsKeyedCoding

    Discussion

    NOfalse by default. Concrete subclasses that support keyed coding, such as NSKeyedArchiver, need to override this property to return YEStrue.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    func containsValueForKey(_ key: String) -> Bool

    Objective-C

    - (BOOL)containsValueForKey:(NSString *)key

    Discussion

    Subclasses must override this method if they perform keyed coding.

    The string is passed as key.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    func decodeArrayOfObjCType(_ itemType: UnsafePointer<Int8>, count count: Int, at array: UnsafeMutablePointer<Void>)

    Objective-C

    - (void)decodeArrayOfObjCType:(const char *)itemType count:(NSUInteger)count at:(void *)array

    Discussion

    The items are decoded into the buffer beginning at address, which must be large enough to contain them all. itemType must contain exactly one type code. NSCoder’s implementation invokes decodeValueOfObjCType:at: to decode the entire array of items.

    This method matches an encodeArrayOfObjCType:count:at: message used during encoding.

    For information on creating an Objective-C type code suitable for itemType, see Type Encodings.

    Special Considerations

    You should not use this method to decode C arrays of Objective-C objects. For historical reasons, returned objects will have an additional ownership reference which you can only relinquish using CFRelease.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func decodeBoolForKey(_ key: String) -> Bool

    Objective-C

    - (BOOL)decodeBoolForKey:(NSString *)key

    Discussion

    Subclasses must override this method if they perform keyed coding.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    func decodeBytesForKey(_ key: String, returnedLength lengthp: UnsafeMutablePointer<Int>) -> UnsafePointer<UInt8>

    Objective-C

    - (const uint8_t *)decodeBytesForKey:(NSString *)key returnedLength:(NSUInteger *)lengthp

    Discussion

    The buffer’s length is returned by reference in lengthp. The returned bytes are immutable. Subclasses must override this method if they perform keyed coding.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.2 and later.

  • Decodes a buffer of data whose types are unspecified.

    Declaration

    Swift

    func decodeBytesWithReturnedLength(_ lengthp: UnsafeMutablePointer<Int>) -> UnsafeMutablePointer<Void>

    Objective-C

    - (void *)decodeBytesWithReturnedLength:(NSUInteger *)lengthp

    Discussion

    NSCoder’s implementation invokes decodeValueOfObjCType:at: to decode the data as a series of bytes, which this method then places into a buffer and returns. The buffer’s length is returned by reference in numBytes. If you need the bytes beyond the scope of the current @autoreleasepool block, you must copy them.

    This method matches an encodeBytes:length: message used during encoding.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func decodeDataObject() -> NSData?

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func decodeDoubleForKey(_ key: String) -> Double

    Objective-C

    - (double)decodeDoubleForKey:(NSString *)key

    Discussion

    Subclasses must override this method if they perform keyed coding.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    func decodeFloatForKey(_ key: String) -> Float

    Objective-C

    - (float)decodeFloatForKey:(NSString *)key

    Discussion

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.2 and later.

  • 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.

    Declaration

    Swift

    func decodeIntForKey(_ key: String) -> Int32

    Objective-C

    - (int)decodeIntForKey:(NSString *)key

    Discussion

    If the encoded integer does not fit into the default integer size, the method raises an NSRangeException. Subclasses must override this method if they perform keyed coding.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.2 and later.

  • 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.

    Declaration

    Swift

    func decodeIntegerForKey(_ key: String) -> Int

    Objective-C

    - (NSInteger)decodeIntegerForKey:(NSString *)key

    Discussion

    If the encoded integer does not fit into the NSInteger size, the method raises an NSRangeException. Subclasses must override this method if they perform keyed coding.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.5 and later.

  • 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.

    Declaration

    Swift

    func decodeInt32ForKey(_ key: String) -> Int32

    Objective-C

    - (int32_t)decodeInt32ForKey:(NSString *)key

    Discussion

    If the encoded integer does not fit into a 32-bit integer, the method raises an NSRangeException. Subclasses must override this method if they perform keyed coding.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.2 and later.

  • 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.

    Declaration

    Swift

    func decodeInt64ForKey(_ key: String) -> Int64

    Objective-C

    - (int64_t)decodeInt64ForKey:(NSString *)key

    Discussion

    Subclasses must override this method if they perform keyed coding.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.2 and later.

  • Decodes an object previously written with encodeNXObject:.

    Declaration

    Objective-C

    - (id)decodeNXObject

    Discussion

    No sharing is done across separate decodeNXObject invocations. Callers must have implemented an initWithCoder:, which parallels the read: methods, on all of their classes that may be touched by this operation.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.5.

  • Decodes an Objective-C object that was previously encoded with any of the encode...Object: methods.

    Declaration

    Swift

    func decodeObject() -> AnyObject?

    Objective-C

    - (id)decodeObject

    Discussion

    NSCoder’s implementation invokes decodeValueOfObjCType:at: to decode the object data.

    Subclasses may need to override this method if they override any of the corresponding encode...Object: methods. For example, if an object was encoded conditionally using the encodeConditionalObject: method, this method needs to check whether the object had actually been encoded.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func decodeObjectForKey(_ key: String) -> AnyObject?

    Objective-C

    - (id)decodeObjectForKey:(NSString *)key

    Discussion

    Subclasses must override this method if they perform keyed coding.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    func decodePoint() -> NSPoint

    Objective-C

    - (NSPoint)decodePoint

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func decodePointForKey(_ key: String) -> NSPoint

    Objective-C

    - (NSPoint)decodePointForKey:(NSString *)key

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    func decodePropertyList() -> AnyObject?

    Objective-C

    - (id)decodePropertyList

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func decodeRect() -> NSRect

    Objective-C

    - (NSRect)decodeRect

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func decodeRectForKey(_ key: String) -> NSRect

    Objective-C

    - (NSRect)decodeRectForKey:(NSString *)key

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    func decodeSize() -> NSSize

    Objective-C

    - (NSSize)decodeSize

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func decodeSizeForKey(_ key: String) -> NSSize

    Objective-C

    - (NSSize)decodeSizeForKey:(NSString *)key

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    func decodeValueOfObjCType(_ type: UnsafePointer<Int8>, at data: UnsafeMutablePointer<Void>)

    Objective-C

    - (void)decodeValueOfObjCType:(const char *)type at:(void *)data

    Discussion

    valueType must contain exactly one type code, and the buffer specified by data must be large enough to hold the value corresponding to that type code. For information on creating an Objective-C type code suitable for valueType, see Type Encodings.

    Subclasses must override this method and provide an implementation to decode the value. In your overriding implementation, decode the value into the buffer beginning at data.

    This method matches an encodeValueOfObjCType:at: message used during encoding.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Decodes a series of potentially different Objective-C types.

    Declaration

    Objective-C

    - (void)decodeValuesOfObjCTypes:(const char *)types, ...

    Discussion

    valueTypes is a single C string containing any number of type codes. The variable arguments to this method consist of one or more pointer arguments, each of which specifies the buffer in which to place a single decoded value. For each type code in valueTypes, you must specify a corresponding pointer argument whose buffer is large enough to hold the decoded value.

    This method matches an encodeValuesOfObjCTypes: message used during encoding.

    NSCoder’s implementation invokes decodeValueOfObjCType:at: to decode individual types. Subclasses that implement the decodeValueOfObjCType:at: method do not need to override this method.

    For information on creating Objective-C type codes suitable for valueTypes, see Type Encodings.

    Special Considerations

    You should not use this method to decode Objective-C objects. See decodeArrayOfObjCType:count:at: for more details.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func decodeObjectOfClass(_ aClass: AnyClass, forKey key: String) -> AnyObject?

    Objective-C

    - (id)decodeObjectOfClass:(Class)aClass forKey:(NSString *)key

    Parameters

    aClass

    The expect class type.

    key

    The coder key.

    Return Value

    The decoded object.

    Discussion

    If the coder responds YEStrue to requiresSecureCoding, then an exception will be thrown if the class to be decoded does not implement NSSecureCoding or is not isKindOfClass: of aClass.

    If the coder responds NOfalse to requiresSecureCoding, then the class argument is ignored and no check of the class of the decoded object is performed, exactly as if decodeObjectForKey: had been called.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.8 and later.

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

    Declaration

    Swift

    func decodeObjectOfClasses(_ classes: Set<NSObject>, forKey key: String) -> AnyObject?

    Objective-C

    - (id)decodeObjectOfClasses:(NSSet *)classes forKey:(NSString *)key

    Parameters

    classes

    A set of the expected classes.

    key

    The coder key.

    Return Value

    The decoded object.

    Discussion

    The class of the object may be any class in the classes set, or a subclass of any class in the set. Otherwise, the behavior is the same as decodeObjectOfClass:forKey:.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.8 and later.

  • Returns a decoded property list for the specified key.

    Declaration

    Swift

    func decodePropertyListForKey(_ key: String) -> AnyObject?

    Objective-C

    - (id)decodePropertyListForKey:(NSString *)key

    Parameters

    key

    The coder key.

    Return Value

    A decoded object containing a property list.

    Discussion

    This method calls decodeObjectOfClasses:forKey: with a set allowing only property list types.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.8 and later.

  • Decodes a color structure from NEXTSTEP Release 3 or earlier and returns an NSColor object.

    Declaration

    Objective-C

    - (NSColor *)decodeNXColor

    Return Value

    An autoreleased NSColor object. Returns nil if the archived color is invalid.

    Discussion

    This method does not have a matching method for encoding an NXColor structure. Encode an NSColor object instead.

    NXColor, a type that dates from pre-OpenStep versions of NEXTSTEP, was a struct. Its replacement, NSColor, is a class. The difficulties of converting from a struct to a class require a special method like decodeNXColor.

    The decodeNXColor method becomes part of the NSCoder class only for apps that use AppKit.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

  • Boolean value that indicates whether the coder requires secure coding. (read-only)

    Declaration

    Swift

    var requiresSecureCoding: Bool { get }

    Objective-C

    @property(readonly) BOOL requiresSecureCoding

    Discussion

    YEStrue if this coder requires secure coding; NOfalse otherwise.

    Secure coders check a set of allowed classes before decoding objects, and all objects must implement the NSSecureCoding protocol.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.8 and later.

  • The set of coded classes allowed for secure coding. (read-only)

    Declaration

    Swift

    var allowedClasses: Set<NSObject>? { get }

    Objective-C

    @property(readonly, copy) NSSet *allowedClasses

    Discussion

    Secure coders check this set of allowed classes before decoding objects, and all objects must implement the NSSecureCoding protocol.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.8 and later.

  • The system version in effect for the archive. (read-only)

    Declaration

    Swift

    var systemVersion: UInt32 { get }

    Objective-C

    @property(readonly) unsigned int systemVersion

    Discussion

    During encoding, the current version. During decoding, the version that was in effect when the data was encoded.

    Subclasses that implement decoding must override this property to return the system version of the data being decoded.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func versionForClassName(_ className: String) -> Int

    Objective-C

    - (NSInteger)versionForClassName:(NSString *)className

    Return Value

    The version in effect for the class named className or NSNotFound if no class named className exists.

    Discussion

    The version number does apply not to NSKeyedArchiver/NSKeyedUnarchiver. A keyed archiver does not encode class version numbers.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Objective-C

    - (NSZone *)objectZone

    Discussion

    NSCoder’s implementation returns the default memory zone, as given by NSDefaultMallocZone().

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Objective-C

    - (void)setObjectZone:(NSZone *)zone

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.0 and later.