iOS Developer Library

Developer

Foundation Framework Reference NSKeyedUnarchiver Class Reference

Options
Deployment Target:

On This Page
Language:

NSKeyedUnarchiver

Inheritance


Conforms To


Import Statement


Swift

import Foundation

Objective-C

@import Foundation;

Availability


Available in iOS 2.0 and later.

NSKeyedUnarchiver, a concrete subclass of NSCoder, defines methods for decoding a set of named objects (and scalar values) from a keyed archive. Such archives are produced by instances of the NSKeyedArchiver class.

A keyed archive is encoded as a hierarchy of objects. Each object in the hierarchy serves as a namespace into which other objects are encoded. The objects available for decoding are restricted to those that were encoded within the immediate scope of a particular object. Objects encoded elsewhere in the hierarchy, whether higher than, lower than, or parallel to this particular object, are not accessible. In this way, the keys used by a particular object to encode its instance variables need to be unique only within the scope of that object.

If you invoke one of the decode... methods of this class using a key that does not exist in the archive, a non-positive value is returned. This value varies by decoded type. For example, if a key does not exist in an archive, decodeBoolForKey: returns NOfalse, decodeIntForKey: returns 0, and decodeObjectForKey: returns nil.

NSKeyedUnarchiver supports limited type coercion. A value encoded as any type of integer, whether a standard int or an explicit 32-bit or 64-bit integer, can be decoded using any of the integer decode methods. Likewise, a value encoded as a float or double can be decoded as either a float or a double value. If an encoded value is too large to fit within the coerced type, the decoding method throws an NSRangeException. Further, when trying to coerce a value to an incompatible type, for example decoding an int as a float, the decoding method throws an NSInvalidUnarchiveOperationException.

  • Initializes the receiver for decoding an archive previously encoded by NSKeyedArchiver.

    Declaration

    Swift

    init(forReadingWithData data: NSData)

    Objective-C

    - (instancetype)initForReadingWithData:(NSData *)data

    Parameters

    data

    An archive previously encoded by NSKeyedArchiver.

    Return Value

    An NSKeyedUnarchiver object initialized for for decoding data.

    Discussion

    When you finish decoding data, you should invoke finishDecoding.

    This method throws an exception if data is not a valid archive.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Decodes and returns the object graph previously encoded by NSKeyedArchiver and stored in a given NSData object.

    Declaration

    Swift

    class func unarchiveObjectWithData(_ data: NSData) -> AnyObject?

    Objective-C

    + (id)unarchiveObjectWithData:(NSData *)data

    Parameters

    data

    An object graph previously encoded by NSKeyedArchiver.

    Return Value

    The object graph previously encoded by NSKeyedArchiver and stored in data.

    Discussion

    This method raises an NSInvalidArchiveOperationException if data is not a valid archive.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Decodes and returns the object graph previously encoded by NSKeyedArchiver written to the file at a given path.

    Declaration

    Swift

    class func unarchiveObjectWithFile(_ path: String) -> AnyObject?

    Objective-C

    + (id)unarchiveObjectWithFile:(NSString *)path

    Parameters

    path

    A path to a file that contains an object graph previously encoded by NSKeyedArchiver.

    Return Value

    The object graph previously encoded by NSKeyedArchiver written to the file path. Returns nil if there is no file at path.

    Discussion

    This method raises an NSInvalidArgumentException if the file at path does not contain a valid archive.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Indicates whether the receiver requires all unarchived 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 unarchive a class which does not conform to NSSecureCoding.

    The secure coding requirement for NSKeyedUnarchiver is designed to be set once at the top level and remain on. Once enabled, attempting to call setRequiresSecureCoding: with a value of NOfalse will throw an exception. This is to prevent classes from selectively turning secure coding off.

    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.

  • Returns a Boolean value that indicates whether the archive contains a value for a given key within the current decoding scope.

    Declaration

    Swift

    func containsValueForKey(_ key: String) -> Bool

    Objective-C

    - (BOOL)containsValueForKey:(NSString *)key

    Parameters

    key

    A key in the archive within the current decoding scope. key must not be nil.

    Return Value

    YEStrue if the archive contains a value for key within the current decoding scope, otherwise NOfalse.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Decodes a Boolean value associated with a given key.

    Declaration

    Swift

    func decodeBoolForKey(_ key: String) -> Bool

    Objective-C

    - (BOOL)decodeBoolForKey:(NSString *)key

    Parameters

    key

    A key in the archive within the current decoding scope. key must not be nil.

    Return Value

    The Boolean value associated with the key key. Returns NOfalse if key does not exist.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

    See Also

    encodeBool:forKey: (NSKeyedArchiver)

  • Decodes a stream of bytes associated with a given key.

    Declaration

    Swift

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

    Objective-C

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

    Parameters

    key

    A key in the archive within the current decoding scope. key must not be nil.

    lengthp

    Upon return, contains the number of bytes returned.

    Return Value

    The stream of bytes associated with the key key. Returns NULL if key does not exist.

    Discussion

    The returned value is a pointer to a temporary buffer owned by the receiver. The buffer goes away with the unarchiver, not the containing autorelease pool block. You must copy the bytes into your own buffer if you need the data to persist beyond the life of the receiver.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

    See Also

    encodeBytes:length:forKey: (NSKeyedArchiver)

  • Decodes a double-precision floating-point value associated with a given key.

    Declaration

    Swift

    func decodeDoubleForKey(_ key: String) -> Double

    Objective-C

    - (double)decodeDoubleForKey:(NSString *)key

    Parameters

    key

    A key in the archive within the current decoding scope. key must not be nil.

    Return Value

    The double-precision floating-point value associated with the key key. Returns 0.0 if key does not exist.

    Discussion

    If the archived value was encoded as single-precision, the type is coerced.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

    See Also

    encodeDouble:forKey: (NSKeyedArchiver)
    encodeFloat:forKey: (NSKeyedArchiver)

  • Decodes a single-precision floating-point value associated with a given key.

    Declaration

    Swift

    func decodeFloatForKey(_ key: String) -> Float

    Objective-C

    - (float)decodeFloatForKey:(NSString *)key

    Parameters

    key

    A key in the archive within the current decoding scope. key must not be nil.

    Return Value

    The single-precision floating-point value associated with the key key. Returns 0.0 if key does not exist.

    Discussion

    If the archived value was encoded as double precision, the type is coerced, loosing precision. If the archived value is too large for single precision, the method raises an NSRangeException.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

    See Also

    encodeFloat:forKey: (NSKeyedArchiver)
    encodeDouble:forKey: (NSKeyedArchiver)

  • Decodes an integer value associated with a given key.

    Declaration

    Swift

    func decodeIntForKey(_ key: String) -> Int32

    Objective-C

    - (int)decodeIntForKey:(NSString *)key

    Parameters

    key

    A key in the archive within the current decoding scope. key must not be nil.

    Return Value

    The integer value associated with the key key. Returns 0 if key does not exist.

    Discussion

    If the archived value was encoded with a different size but is still an integer, the type is coerced. If the archived value is too large to fit into the default size for an integer, the method raises an NSRangeException.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

    See Also

    encodeInt:forKey: (NSKeyedArchiver)

  • Decodes a 32-bit integer value associated with a given key.

    Declaration

    Swift

    func decodeInt32ForKey(_ key: String) -> Int32

    Objective-C

    - (int32_t)decodeInt32ForKey:(NSString *)key

    Parameters

    key

    A key in the archive within the current decoding scope. key must not be nil.

    Return Value

    The 32-bit integer value associated with the key key. Returns 0 if key does not exist.

    Discussion

    If the archived value was encoded with a different size but is still an integer, the type is coerced. If the archived value is too large to fit into a 32-bit integer, the method raises an NSRangeException.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

    See Also

    encodeInt32:forKey: (NSKeyedArchiver)

  • Decodes a 64-bit integer value associated with a given key.

    Declaration

    Swift

    func decodeInt64ForKey(_ key: String) -> Int64

    Objective-C

    - (int64_t)decodeInt64ForKey:(NSString *)key

    Parameters

    key

    A key in the archive within the current decoding scope. key must not be nil.

    Return Value

    The 64-bit integer value associated with the key key. Returns 0 if key does not exist.

    Discussion

    If the archived value was encoded with a different size but is still an integer, the type is coerced.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

    See Also

    encodeInt64:forKey: (NSKeyedArchiver)

  • Decodes and returns an object associated with a given key.

    Declaration

    Swift

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

    Objective-C

    - (id)decodeObjectForKey:(NSString *)key

    Parameters

    key

    A key in the archive within the current decoding scope. key must not be nil.

    Return Value

    The object associated with the key key. Returns nil if key does not exist, or if the value for key is nil.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

    See Also

    encodeObject:forKey: (NSKeyedArchiver)

  • Tells the receiver that you are finished decoding objects.

    Declaration

    Swift

    func finishDecoding()

    Objective-C

    - (void)finishDecoding

    Discussion

    Invoking this method allows the receiver to notify its delegate and to perform any final operations on the archive. Once this method is invoked, the receiver cannot decode any further values.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Adds a class translation mapping to NSKeyedUnarchiver whereby objects encoded with a given class name are decoded as instances of a given class instead.

    Declaration

    Swift

    class func setClass(_ cls: AnyClass?, forClassName codedName: String)

    Objective-C

    + (void)setClass:(Class)cls forClassName:(NSString *)codedName

    Parameters

    cls

    The class with which to replace instances of the class named codedName.

    codedName

    The ostensible name of a class in an archive.

    Discussion

    When decoding, 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 from which NSKeyedUnarchiver instantiates an encoded object with a given class name.

    Declaration

    Swift

    class func classForClassName(_ codedName: String) -> AnyClass?

    Objective-C

    + (Class)classForClassName:(NSString *)codedName

    Parameters

    codedName

    The ostensible name of a class in an archive.

    Return Value

    The class from which NSKeyedUnarchiver instantiates an object encoded with the class name codedName. Returns nil if NSKeyedUnarchiver does not have a translation mapping for codedName.

    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 objects encoded with a given class name are decoded as instances of a given class instead.

    Declaration

    Swift

    func setClass(_ cls: AnyClass?, forClassName codedName: String)

    Objective-C

    - (void)setClass:(Class)cls forClassName:(NSString *)codedName

    Parameters

    cls

    The class with which to replace instances of the class named codedName.

    codedName

    The ostensible name of a class in an archive.

    Discussion

    When decoding, the receiver’s translation map overrides any translation that may also be present in the class’s map (see setClass:forClassName:).

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Returns the class from which the receiver instantiates an encoded object with a given class name.

    Declaration

    Swift

    func classForClassName(_ codedName: String) -> AnyClass?

    Objective-C

    - (Class)classForClassName:(NSString *)codedName

    Parameters

    codedName

    The name of a class.

    Return Value

    The class from which the receiver instantiates an encoded object with the class name codedName. Returns nil if the receiver does not have a translation mapping for codedName.

    Discussion

    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 NSKeyedUnarchiver if there is a problem extracting an archive.

    Declaration

    Swift

    let NSInvalidUnarchiveOperationException: String

    Objective-C

    NSString *NSInvalidUnarchiveOperationException;

    Constants

    • NSInvalidUnarchiveOperationException

      NSInvalidUnarchiveOperationException

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

      Available in iOS 2.0 and later.