Mac Developer Library

Developer

Foundation Framework Reference NSUnarchiver Class Reference

Options
Deployment Target:

On This Page
Language:

NSUnarchiver

NSUnarchiver, a concrete subclass of NSCoder, defines methods for decoding a set of Objective-C objects from an archive. Such archives are produced by objects of the NSArchiver class. More...

Inheritance


Conforms To


Import Statement


import Foundation @import Foundation;

Availability


Available in OS X v10.0 and later.
  • Returns an NSUnarchiver object initialized to read an archive from a given data object.

    Declaration

    Swift

    init?(forReadingWithData data: NSData)

    Objective-C

    - (instancetype)initForReadingWithData:(NSData *)data

    Parameters

    data

    The archive data.

    Return Value

    An NSUnarchiver object initialized to read an archive from data. Returns nil if data is not a valid archive.

    Discussion

    The method decodes the system version number that was archived in data prepares the NSUnarchiver object for a subsequent invocation of decodeObject.

    Raises an NSInvalidArgumentException if data is nil.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Decodes and returns the object archived in a given NSData object.

    Declaration

    Swift

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

    Objective-C

    + (id)unarchiveObjectWithData:(NSData *)data

    Parameters

    data

    An NSData object that contains an archive created using NSArchiver.

    Return Value

    The object, or object graph, that was archived in data. Returns nil if data cannot be unarchived.

    Discussion

    This method invokes initForReadingWithData: and decodeObject to create a temporary NSUnarchiver object that decodes the object. If the archived object is the root of a graph of objects, the entire graph is unarchived.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

    See Also

    encodeRootObject: (NSArchiver)

  • Decodes and returns the object archived in the file path.

    Declaration

    Swift

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

    Objective-C

    + (id)unarchiveObjectWithFile:(NSString *)path

    Parameters

    path

    The path to a file than contains an archive created using NSArchiver.

    Return Value

    The object, or object graph, that was archived in the file at path. Returns nil if the file at path cannot be unarchived.

    Discussion

    This convenience method reads the file by invoking the NSData method dataWithContentsOfFile: and then invokes unarchiveObjectWithData:.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • atEnd atEnd Property

    A Boolean value that indicates whether the receiver has reached the end of the encoded data while decoding. (read-only)

    Declaration

    Swift

    var atEnd: Bool { get }

    Objective-C

    @property(getter=isAtEnd, readonly) BOOL atEnd

    Discussion

    YEStrue if the receiver has reached the end of the encoded data while decoding, otherwise NOfalse.

    You can invoke this method after invoking decodeObject to discover whether the archive contains extra data following the encoded object graph. If it does, you can either ignore this anomaly or consider it an error.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.10 and later.

  • Returns the memory zone used to allocate decoded objects.

    Declaration

    Objective-C

    - (NSZone *)objectZone

    Return Value

    The memory zone used to allocate decoded objects.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

  • Sets the memory zone used to allocate decoded objects.

    Declaration

    Objective-C

    - (void)setObjectZone:(NSZone *)zone

    Parameters

    zone

    The memory zone used to allocate decoded objects.

    Discussion

    If zone is nil, or if this method is never invoked, the default zone is used, as given by NSDefaultMallocZone().

    Import Statement

    Availability

    Available in OS X v10.0 and later.

    See Also

    – objectZone

  • The system version number in effect when the archive was created. (read-only)

    Declaration

    Swift

    var systemVersion: UInt32 { get }

    Objective-C

    @property(readonly) unsigned int systemVersion

    Discussion

    This information is available as soon as the receiver has been initialized.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the name of the class used when instantiating objects whose ostensible class, according to the archived data, is a given name.

    Declaration

    Swift

    class func classNameDecodedForArchiveClassName(_ nameInArchive: String) -> String

    Objective-C

    + (NSString *)classNameDecodedForArchiveClassName:(NSString *)nameInArchive

    Parameters

    nameInArchive

    The name of a class.

    Return Value

    The name of the class used when instantiating objects whose ostensible class, according to the archived data, is nameInArchive. Returns nameInArchive if no substitute name has been specified using the class method (not the instance method) decodeClassName:asClassName:.

    Discussion

    Note that each individual instance of NSUnarchiver can be given its own class name mappings by invoking the instance method decodeClassName:asClassName:. The NSUnarchiver class has no information about these instance-specific mappings, however, so they don’t affect the return value of classNameDecodedForArchiveClassName:.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Instructs instances of NSUnarchiver to use the class with a given name when instantiating objects whose ostensible class, according to the archived data, is another given name.

    Declaration

    Swift

    class func decodeClassName(_ nameInArchive: String, asClassName trueName: String)

    Objective-C

    + (void)decodeClassName:(NSString *)nameInArchive asClassName:(NSString *)trueName

    Parameters

    nameInArchive

    The ostensible name of a class in an archive.

    trueName

    The name of the class to use when instantiating objects whose ostensible class, according to the archived data, is nameInArchive.

    Discussion

    This method enables easy conversion of unarchived data when the name of a class has changed since the archive was created.

    Note that there is also an instance method of the same name. An instance of NSUnarchiver can maintain its own mapping of class names. However, if both the class method and the instance method have been invoked using an identical value for nameInArchive, the class method takes precedence.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the name of the class that will be used when instantiating objects whose ostensible class, according to the archived data, is a given name.

    Declaration

    Swift

    func classNameDecodedForArchiveClassName(_ nameInArchive: String) -> String

    Objective-C

    - (NSString *)classNameDecodedForArchiveClassName:(NSString *)nameInArchive

    Parameters

    nameInArchive

    The ostensible name of a class in an archive.

    Return Value

    The name of the class that will be used when instantiating objects whose ostensible class, according to the archived data, is nameInArchive. Returns nameInArchive unless a substitute name has been specified using the instance method (not the class method) decodeClassName:asClassName:.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Instructs the receiver to use the class with a given name when instantiating objects whose ostensible class, according to the archived data, is another given name.

    Declaration

    Swift

    func decodeClassName(_ nameInArchive: String, asClassName trueName: String)

    Objective-C

    - (void)decodeClassName:(NSString *)nameInArchive asClassName:(NSString *)trueName

    Parameters

    nameInArchive

    The ostensible name of a class in an archive.

    trueName

    The name of the class to use when instantiating objects whose ostensible class, according to the archived data, is nameInArchive.

    Discussion

    This method enables easy conversion of unarchived data when the name of a class has changed since the archive was created.

    Note that there’s also a class method of the same name. The class method has precedence in case of conflicts.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Causes the receiver to substitute one given object for another whenever the latter is extracted from the archive.

    Declaration

    Swift

    func replaceObject(_ object: AnyObject, withObject newObject: AnyObject)

    Objective-C

    - (void)replaceObject:(id)object withObject:(id)newObject

    Parameters

    object

    The archived object to replace.

    newObject

    The object with which to replace object.

    Discussion

    newObject can be of a different class from object, and the class mappings set by classNameDecodedForArchiveClassName: and decodeClassName:asClassName: are ignored.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.