Mac Developer Library

Developer

Foundation Framework Reference NSArchiver Class Reference

Options
Deployment Target:

On This Page
Language:

NSArchiver

NSArchiver, a concrete subclass of NSCoder, provides a way to encode objects into an architecture-independent format that can be stored in a file. When you archive a graph of objects, the class information and instance variables for each object are written to the archive. NSArchiver's companion class, NSUnarchiver in NSUnarchiver Class Reference, decodes the data in an archive and creates a graph of objects equivalent to the original set. More...

Inheritance


Conforms To


Import Statement


import Foundation @import Foundation;

Availability


Available in OS X v10.0 and later.
  • Returns an archiver, initialized to encode stream and version information into a given mutable data object.

    Declaration

    Swift

    init(forWritingWithMutableData data: NSMutableData)

    Objective-C

    - (instancetype)initForWritingWithMutableData:(NSMutableData *)data

    Parameters

    data

    The mutable data object into which to write the archive. This value must not be nil.

    Return Value

    An archiver object, initialized to encode stream and version information into data.

    Discussion

    Raises an NSInvalidArgumentException if data is nil.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns a data 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 object of the object graph to archive.

    Return Value

    A data object containing the encoded form of the object graph whose root object is rootObject.

    Discussion

    This method invokes initForWritingWithMutableData: and encodeRootObject: to create a temporary archiver that encodes the object graph.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Creates a temporary instance of NSArchiver and archives an object graph by encoding it into a data object and writing the resulting data object to a specified file.

    Declaration

    Swift

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

    Objective-C

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

    Parameters

    rootObject

    The root object of the object graph to archive.

    path

    The location of the the file into which to write the archive.

    Return Value

    YEStrue if the archive was written successfully, otherwise NOfalse.

    Discussion

    This convenience method invokes archivedDataWithRootObject: to get the encoded data, and then sends that data object the message writeToFile:atomically:, using path for the first argument and YEStrue for the second.

    The archived data should be retrieved from the archive by an NSUnarchiver in NSUnarchiver Class Reference object.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Archives a given object along with all the objects to which it is connected.

    Declaration

    Swift

    func encodeRootObject(_ rootObject: AnyObject)

    Objective-C

    - (void)encodeRootObject:(id)rootObject

    Parameters

    rootObject

    The root object of the object graph to archive.

    Discussion

    If any object is encountered more than once while traversing the graph, it is encoded only once, but the multiple references to it are stored. (See Archives and Serializations Programming Guide for more information.)

    This message must not be sent more than once to a given NSArchiver object; an NSInvalidArgumentException is raised if a root object has already been encoded. If you need to encode multiple object graphs, therefore, don’t attempt to reuse an NSArchiver instance; instead, create a new one for each graph.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Conditionally archives a given object.

    Declaration

    Swift

    func encodeConditionalObject(_ object: AnyObject?)

    Objective-C

    - (void)encodeConditionalObject:(id)object

    Parameters

    object

    The object to archive.

    Discussion

    This method overrides the superclass implementation to allow object to be encoded only if it is also encoded unconditionally by another object in the object graph. Conditional encoding lets you encode one part of a graph detached from the rest. (See Archives and Serializations Programming Guide for more information.)

    This method should be invoked only from within an encodeWithCoder: method. If object is nil, the NSArchiver object encodes it unconditionally as nil. This method raises an NSInvalidArgumentException if no root object has been encoded.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • The receiver's archive data. (read-only)

    Declaration

    Swift

    var archiverData: NSMutableData { get }

    Objective-C

    @property(readonly, retain) NSMutableData *archiverData

    Discussion

    The returned data object is the same one specified as the argument to initForWritingWithMutableData:. It contains whatever data has been encoded thus far by invocations of the various encoding methods. It is safest not to invoke this method until after encodeRootObject: has returned. In other words, although it is possible for a class to invoke this method from within its encodeWithCoder: method, that method must not alter the data.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the name of the class used to archive instances of the class with a given true name.

    Declaration

    Swift

    func classNameEncodedForTrueClassName(_ trueName: String) -> String?

    Objective-C

    - (NSString *)classNameEncodedForTrueClassName:(NSString *)trueName

    Parameters

    trueName

    The real name of an encoded class.

    Return Value

    The name of the class used to archive instances of the class trueName.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Encodes a substitute name for the class with a given true name.

    Declaration

    Swift

    func encodeClassName(_ trueName: String, intoClassName inArchiveName: String)

    Objective-C

    - (void)encodeClassName:(NSString *)trueName intoClassName:(NSString *)inArchiveName

    Parameters

    trueName

    The real name of a class in the object graph being archived.

    inArchiveName

    The name of the class to use in the archive in place of trueName.

    Discussion

    Any subsequently encountered objects of class trueName are archived as instances of class inArchiveName. It is safest not to invoke this method during the archiving process (that is, within an encodeWithCoder: method). Instead, invoke it before encodeRootObject:.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Causes the receiver to treat subsequent requests to encode a given object as though they were requests to encode another given object.

    Declaration

    Swift

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

    Objective-C

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

    Parameters

    object

    An object in the object graph being archived.

    newObject

    The object with which to replace object in the archive.

    Discussion

    Both object and newObject must be valid objects.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Raised by NSArchiver if there are problems initializing or encoding.

    Declaration

    Swift

    let NSInconsistentArchiveException: NSString!

    Objective-C

    extern NSString *NSInconsistentArchiveException;

    Constants

    • NSInconsistentArchiveException

      NSInconsistentArchiveException

      The name of an exception raised by NSArchiver if there are problems initializing or encoding.

      Available in OS X v10.0 and later.

    Import Statement