iOS Developer Library — Pre-Release

Developer

Foundation Framework Reference NSKeyedArchiver Class Reference

Options
Deployment Target:

On This Page
Language:

NSKeyedArchiver

NSKeyedArchiver, a concrete subclass of NSCoder, provides a way to encode objects (and scalar values) into an architecture-independent format that can be stored in a file. When you archive a set of objects, the class information and instance variables for each object are written to the archive. NSKeyedArchiver’s companion class, NSKeyedUnarchiver, decodes the data in an archive and creates a set of objects equivalent to the original set.

A keyed archive differs from a non-keyed archive in that all the objects and values encoded into the archive are given names, or keys. When decoding a non-keyed archive, values have to be decoded in the same order in which they were encoded. When decoding a keyed archive, because values are requested by name, values can be decoded out of sequence or not at all. Keyed archives, therefore, provide better support for forward and backward compatibility.

The keys given to encoded values must be unique only within the scope of the current object being encoded. A keyed archive is hierarchical, so the keys used by object A to encode its instance variables do not conflict with the keys used by object B, even if A and B are instances of the same class. Within a single object, however, the keys used by a subclass can conflict with keys used in its superclasses.

An NSArchiver object can write the archive data to a file or to a mutable-data object (an instance of NSMutableData) that you provide.

Inheritance


Conforms To


Import Statement


Swift

import Foundation

Objective-C

@import Foundation;

Availability


Available in iOS 2.0 and later.
  • Returns the receiver, initialized for encoding an archive into a given a mutable-data object.

    Declaration

    Swift

    init(forWritingWithMutableData data: NSMutableData)

    Objective-C

    - (instancetype)initForWritingWithMutableData:(NSMutableData *)data

    Parameters

    data

    The mutable-data object into which the archive is written.

    Return Value

    The receiver, initialized for encoding an archive into data.

    Discussion

    When you finish encoding data, you must invoke finishEncoding at which point data is filled. The format of the receiver is NSPropertyListBinaryFormat_v1_0.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Returns an NSData object containing the encoded form of the object graph whose root object is given.

    Declaration

    Swift

    class func archivedDataWithRootObject(_ rootObject: AnyObject) -> NSData

    Objective-C

    + (NSData *)archivedDataWithRootObject:(id)rootObject

    Parameters

    rootObject

    The root of the object graph to archive.

    Return Value

    An NSData object containing the encoded form of the object graph whose root object is rootObject. The format of the archive is NSPropertyListBinaryFormat_v1_0.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Archives an object graph rooted at a given object by encoding it into a data object then atomically writes the resulting data object to a file at a given path, and returns a Boolean value that indicates whether the operation was successful.

    Declaration

    Swift

    class func archiveRootObject(_ rootObject: AnyObject, toFile path: String) -> Bool

    Objective-C

    + (BOOL)archiveRootObject:(id)rootObject toFile:(NSString *)path

    Parameters

    rootObject

    The root of the object graph to archive.

    path

    The path of the file in which to write the archive.

    Return Value

    YEStrue if the operation was successful, otherwise NOfalse.

    Discussion

    The format of the archive is NSPropertyListBinaryFormat_v1_0.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Instructs the receiver to construct the final data stream.

    Declaration

    Swift

    func finishEncoding()

    Objective-C

    - (void)finishEncoding

    Discussion

    No more values can be encoded after this method is called. You must call this method when finished.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • The format in which the receiver encodes its data.

    Declaration

    Swift

    var outputFormat: NSPropertyListFormat

    Objective-C

    @property NSPropertyListFormat outputFormat

    Discussion

    The available formats are NSPropertyListXMLFormat_v1_0 and NSPropertyListBinaryFormat_v1_0.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Indicates whether the receiver requires all archived classes to conform to NSSecureCoding.

    Declaration

    Swift

    func setRequiresSecureCoding(_ flag: Bool)

    Objective-C

    - (void)setRequiresSecureCoding:(BOOL)flag

    Parameters

    flag

    YEStrue if the receiver requires NSSecureCoding; NOfalse if not.

    Discussion

    If you set the receiver to require secure coding, it will throw an exception if you attempt to archive a class which does not conform to NSSecureCoding.

    Note that the getter is on the superclass, NSCoder. See NSCoder for more information about secure coding.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 6.0 and later.

  • Encodes a given Boolean value and associates it with a given key.

    Declaration

    Swift

    func encodeBool(_ boolv: Bool, forKey key: String)

    Objective-C

    - (void)encodeBool:(BOOL)boolv forKey:(NSString *)key

    Parameters

    boolv

    The value to encode.

    key

    The key with which to associate boolv. This value must not be nil.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

    See Also

    decodeBoolForKey: (NSKeyedUnarchiver)

  • Encodes a given number of bytes from a given C array of bytes and associates them with the a given key.

    Declaration

    Swift

    func encodeBytes(_ bytesp: UnsafePointer<UInt8>, length lenv: Int, forKey key: String)

    Objective-C

    - (void)encodeBytes:(const uint8_t *)bytesp length:(NSUInteger)lenv forKey:(NSString *)key

    Parameters

    bytesp

    A C array of bytes to encode.

    lenv

    The number of bytes from bytesp to encode.

    key

    The key with which to associate the encoded value. This value must not be nil.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

    See Also

    decodeBytesForKey:returnedLength: (NSKeyedUnarchiver)

  • Encodes a reference to a given object and associates it with a given key only if it has been unconditionally encoded elsewhere in the archive with encodeObject:forKey:.

    Declaration

    Swift

    func encodeConditionalObject(_ objv: AnyObject?, forKey key: String)

    Objective-C

    - (void)encodeConditionalObject:(id)objv forKey:(NSString *)key

    Parameters

    objv

    The object to encode.

    key

    The key with which to associate the encoded value. This value must not be nil.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Encodes a given double value and associates it with a given key.

    Declaration

    Swift

    func encodeDouble(_ realv: Double, forKey key: String)

    Objective-C

    - (void)encodeDouble:(double)realv forKey:(NSString *)key

    Parameters

    realv

    The value to encode.

    key

    The key with which to associate realv. This value must not be nil.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

    See Also

    decodeDoubleForKey: (NSKeyedUnarchiver)
    decodeFloatForKey: (NSKeyedUnarchiver)

  • Encodes a given float value and associates it with a given key.

    Declaration

    Swift

    func encodeFloat(_ realv: Float, forKey key: String)

    Objective-C

    - (void)encodeFloat:(float)realv forKey:(NSString *)key

    Parameters

    realv

    The value to encode.

    key

    The key with which to associate realv. This value must not be nil.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

    See Also

    decodeFloatForKey: (NSKeyedUnarchiver)
    decodeDoubleForKey: (NSKeyedUnarchiver)

  • Encodes a given int value and associates it with a given key.

    Declaration

    Swift

    func encodeInt(_ intv: Int32, forKey key: String)

    Objective-C

    - (void)encodeInt:(int)intv forKey:(NSString *)key

    Parameters

    intv

    The value to encode.

    key

    The key with which to associate intv. This value must not be nil.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

    See Also

    decodeIntForKey: (NSKeyedUnarchiver)

  • Encodes a given 32-bit integer value and associates it with a given key.

    Declaration

    Swift

    func encodeInt32(_ intv: Int32, forKey key: String)

    Objective-C

    - (void)encodeInt32:(int32_t)intv forKey:(NSString *)key

    Parameters

    intv

    The value to encode.

    key

    The key with which to associate intv. This value must not be nil.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

    See Also

    decodeInt32ForKey: (NSKeyedUnarchiver)

  • Encodes a given 64-bit integer value and associates it with a given key.

    Declaration

    Swift

    func encodeInt64(_ intv: Int64, forKey key: String)

    Objective-C

    - (void)encodeInt64:(int64_t)intv forKey:(NSString *)key

    Parameters

    intv

    The value to encode.

    key

    The key with which to associate intv. This value must not be nil.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

    See Also

    decodeInt64ForKey: (NSKeyedUnarchiver)

  • Encodes a given object and associates it with a given key.

    Declaration

    Swift

    func encodeObject(_ objv: AnyObject?, forKey key: String)

    Objective-C

    - (void)encodeObject:(id)objv forKey:(NSString *)key

    Parameters

    objv

    The value to encode. This value may be nil.

    key

    The key with which to associate objv. This value must not be nil.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

    See Also

    decodeObjectForKey: (NSKeyedUnarchiver)

  • delegate delegate Property

    The archiver’s delegate.

    Declaration

    Swift

    unowned(unsafe) var delegate: NSKeyedArchiverDelegate?

    Objective-C

    @property(assign) id< NSKeyedArchiverDelegate > delegate

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Adds a class translation mapping to NSKeyedArchiver whereby instances of of a given class are encoded with a given class name instead of their real class names.

    Declaration

    Swift

    class func setClassName(_ codedName: String?, forClass cls: AnyClass)

    Objective-C

    + (void)setClassName:(NSString *)codedName forClass:(Class)cls

    Parameters

    codedName

    The name of the class that NSKeyedArchiver uses in place of cls.

    cls

    The class for which to set up a translation mapping.

    Discussion

    When encoding, the class’s translation mapping is used only if no translation is found first in an instance’s separate translation map.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Returns the class name with which NSKeyedArchiver encodes instances of a given class.

    Declaration

    Swift

    class func classNameForClass(_ cls: AnyClass) -> String?

    Objective-C

    + (NSString *)classNameForClass:(Class)cls

    Parameters

    cls

    The class for which to determine the translation mapping.

    Return Value

    The class name with which NSKeyedArchiver encodes instances of cls. Returns nil if NSKeyedArchiver does not have a translation mapping for cls.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Adds a class translation mapping to the receiver whereby instances of of a given class are encoded with a given class name instead of their real class names.

    Declaration

    Swift

    func setClassName(_ codedName: String?, forClass cls: AnyClass)

    Objective-C

    - (void)setClassName:(NSString *)codedName forClass:(Class)cls

    Parameters

    codedName

    The name of the class that the receiver uses uses in place of cls.

    cls

    The class for which to set up a translation mapping.

    Discussion

    When encoding, the receiver’s translation map overrides any translation that may also be present in the class’s map.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Returns the class name with which the receiver encodes instances of a given class.

    Declaration

    Swift

    func classNameForClass(_ cls: AnyClass) -> String?

    Objective-C

    - (NSString *)classNameForClass:(Class)cls

    Parameters

    cls

    The class for which to determine the translation mapping.

    Return Value

    The class name with which the receiver encodes instances of cls. Returns nil if the receiver does not have a translation mapping for cls. The class’s separate translation map is not searched.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Names of exceptions that are raised by NSKeyedArchiver if there is a problem creating an archive.

    Declaration

    Swift

    let NSInvalidArchiveOperationException: String

    Objective-C

    extern NSString *NSInvalidArchiveOperationException;

    Constants

    • NSInvalidArchiveOperationException

      NSInvalidArchiveOperationException

      The name of the exception raised by NSKeyedArchiver if there is a problem creating an archive.

      Available in iOS 2.0 and later.

  • Keys that NSKeyedArchiver uses in the hierarchy of encoded objects.

    Declaration

    Swift

    let NSKeyedArchiveRootObjectKey: String

    Objective-C

    extern NSString * const NSKeyedArchiveRootObjectKey;

    Constants