iOS Developer Library — Prerelease

Developer

Foundation Framework Reference NSCoder Class Reference

Options
Deployment Target:

On This Page
Language:

NSCoder

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.

    Availability

    Available in iOS 2.0 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 * nonnull)key

    Discussion

    Subclasses must override this method if they perform keyed coding.

    The string is passed as key.

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func encodeCGPoint(_ point: CGPoint, forKey key: String)

    Objective-C

    - (void)encodeCGPoint:(CGPoint)point forKey:(NSString * nonnull)key

    Parameters

    point

    The point to encode.

    key

    The key identifying the data.

    Discussion

    When decoding the data from the archive, you pass the value in the key parameter to the corresponding decodeCGPointForKey: method to retrieve the data.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func encodeCGRect(_ rect: CGRect, forKey key: String)

    Objective-C

    - (void)encodeCGRect:(CGRect)rect forKey:(NSString * nonnull)key

    Parameters

    rect

    The rectangle to encode.

    key

    The key identifying the data.

    Discussion

    When decoding the data from the archive, you pass the value in the key parameter to the corresponding decodeCGRectForKey: method to retrieve the data.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func encodeCGSize(_ size: CGSize, forKey key: String)

    Objective-C

    - (void)encodeCGSize:(CGSize)size forKey:(NSString * nonnull)key

    Parameters

    size

    The size information to encode.

    key

    The key identifying the data.

    Discussion

    When decoding the data from the archive, you pass the value in the key parameter to the corresponding decodeCGSizeForKey: method to retrieve the data.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func encodeCGAffineTransform(_ transform: CGAffineTransform, forKey key: String)

    Objective-C

    - (void)encodeCGAffineTransform:(CGAffineTransform)transform forKey:(NSString * nonnull)key

    Parameters

    transform

    The transform information to encode.

    key

    The key identifying the data.

    Discussion

    When decoding the data from the archive, you pass the value in the key parameter to the corresponding decodeCGAffineTransformForKey: method to retrieve the data.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func encodeUIEdgeInsets(_ insets: UIEdgeInsets, forKey key: String)

    Objective-C

    - (void)encodeUIEdgeInsets:(UIEdgeInsets)insets forKey:(NSString * nonnull)key

    Parameters

    insets

    The edge insets data to encode.

    key

    The key identifying the data.

    Discussion

    When decoding the data from the archive, you pass the value in the key parameter to the corresponding decodeUIEdgeInsetsForKey: method to retrieve the data.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func encodeUIOffset(_ offset: UIOffset, forKey key: String)

    Objective-C

    - (void)encodeUIOffset:(UIOffset)offset forKey:(NSString * nonnull)key

    Parameters

    offset

    The offset data to encode.

    key

    The key identifying the data.

    Discussion

    When decoding the data from the archive, you pass the value in the key parameter to the corresponding decodeUIOffsetForKey: method to retrieve the data.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 5.0 and later.

  • Decodes and returns the CGPoint structure associated with the specified key in the receiver’s archive.

    Declaration

    Swift

    func decodeCGPointForKey(_ key: String) -> CGPoint

    Objective-C

    - (CGPoint)decodeCGPointForKey:(NSString * nonnull)key

    Parameters

    key

    The key that identifies the point.

    Return Value

    The CGPoint structure.

    Discussion

    Use this method to decode a point that was previously encoded using the encodeCGPoint:forKey: method.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • Decodes and returns the CGRect structure associated with the specified key in the receiver’s archive.

    Declaration

    Swift

    func decodeCGRectForKey(_ key: String) -> CGRect

    Objective-C

    - (CGRect)decodeCGRectForKey:(NSString * nonnull)key

    Parameters

    key

    The key that identifies the rectangle.

    Return Value

    The CGRect structure.

    Discussion

    Use this method to decode a rectangle that was previously encoded using the encodeCGRect:forKey: method.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • Decodes and returns the CGSize structure associated with the specified key in the receiver’s archive.

    Declaration

    Swift

    func decodeCGSizeForKey(_ key: String) -> CGSize

    Objective-C

    - (CGSize)decodeCGSizeForKey:(NSString * nonnull)key

    Parameters

    key

    The key that identifies the size information.

    Return Value

    The CGSize structure.

    Discussion

    Use this method to decode size information that was previously encoded using the encodeCGSize:forKey: method.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • Decodes and returns the CGAffineTransform structure associated with the specified key in the receiver’s archive.

    Declaration

    Swift

    func decodeCGAffineTransformForKey(_ key: String) -> CGAffineTransform

    Objective-C

    - (CGAffineTransform)decodeCGAffineTransformForKey:(NSString * nonnull)key

    Parameters

    key

    The key that identifies the affine transform.

    Return Value

    The affine transform.

    Discussion

    Use this method to decode size information that was previously encoded using the encodeCGAffineTransform:forKey: method.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • Decodes and returns the UIEdgeInsets structure associated with the specified key in the receiver’s archive.

    Declaration

    Swift

    func decodeUIEdgeInsetsForKey(_ key: String) -> UIEdgeInsets

    Objective-C

    - (UIEdgeInsets)decodeUIEdgeInsetsForKey:(NSString * nonnull)key

    Parameters

    key

    The key that identifies the edge insets.

    Return Value

    The edge insets data.

    Discussion

    Use this method to decode size information that was previously encoded using the encodeUIEdgeInsets:forKey: method.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • Decodes and returns the UIOffset structure associated with the specified key in the receiver’s archive.

    Declaration

    Swift

    func decodeUIOffsetForKey(_ key: String) -> UIOffset

    Objective-C

    - (UIOffset)decodeUIOffsetForKey:(NSString * nonnull)key

    Parameters

    key

    The key that identifies the offset.

    Return Value

    The offset data.

    Discussion

    Use this method to decode offset information that was previously encoded using the encodeUIOffset:forKey: method.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 5.0 and later.

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

    Availability

    Available in iOS 6.0 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 <Class> *allowedClasses

    Discussion

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

    Availability

    Available in iOS 6.0 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.

    Availability

    Available in iOS 2.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 * nonnull)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.

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Objective-C

    - (NSZone * nullable)objectZone

    Discussion

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

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Objective-C

    - (void)setObjectZone:(NSZone * nullable)zone

    Availability

    Available in iOS 2.0 and later.