[Documentation] Add doc comments for NSKeyedArchiver (#842)
diff --git a/Foundation/NSKeyedArchiver.swift b/Foundation/NSKeyedArchiver.swift
index 0bd7b1a..45a8028 100644
--- a/Foundation/NSKeyedArchiver.swift
+++ b/Foundation/NSKeyedArchiver.swift
@@ -9,7 +9,9 @@
import CoreFoundation
-// Archives created using the class method archivedRootDataWithObject used this key for the root object in the hierarchy of encoded objects. The NSKeyedUnarchiver class method unarchiveObjectWithData: will look for this root key as well. You can also use it as the key for the root object in your own archives.
+/// Archives created using the class method `archivedData(withRootObject:)` use this key
+/// for the root object in the hierarchy of encoded objects. The `NSKeyedUnarchiver` class method
+/// `unarchiveObject(with:)` looks for this root key as well.
public let NSKeyedArchiveRootObjectKey: String = "root"
internal let NSKeyedArchiveNullObjectReference = _NSKeyedArchiverUID(value: 0)
@@ -34,7 +36,29 @@
NSNumber.self
]
+/// `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 `NSKeyedArchiver` object can write the archive data to a file or to a
+/// mutable-data object (an instance of `NSMutableData`) that you provide.
open class NSKeyedArchiver : NSCoder {
+
struct ArchiverFlags : OptionSet {
let rawValue : UInt
@@ -67,7 +91,12 @@
private var _classes : Dictionary<String, _NSKeyedArchiverUID> = [:]
private var _cache : Array<_NSKeyedArchiverUID> = []
+ /// The archiver’s delegate.
open weak var delegate: NSKeyedArchiverDelegate?
+
+ /// The format in which the receiver encodes its data.
+ ///
+ /// The available formats are `xml` and `binary`.
open var outputFormat = PropertyListSerialization.PropertyListFormat.binary {
willSet {
if outputFormat != PropertyListSerialization.PropertyListFormat.xml &&
@@ -77,6 +106,13 @@
}
}
+ /// Returns an `NSData` object containing the encoded form of the object graph
+ /// whose root object is given.
+ ///
+ /// - Parameter rootObject: The root of the object graph to archive.
+ /// - Returns: 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`.
open class func archivedData(withRootObject rootObject: Any) -> Data {
let data = NSMutableData()
let keyedArchiver = NSKeyedArchiver(forWritingWith: data)
@@ -87,6 +123,14 @@
return data._swiftObject
}
+ /// 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.
+ ///
+ /// - Parameters:
+ /// - rootObject: The root of the object graph to archive.
+ /// - path: The path of the file in which to write the archive.
+ /// - Returns: `true` if the operation was successful, otherwise `false`.
open class func archiveRootObject(_ rootObject: Any, toFile path: String) -> Bool {
var fd : Int32 = -1
var auxFilePath : String
@@ -135,6 +179,12 @@
super.init()
}
+ /// Returns the archiver, initialized for encoding an archive into a given a mutable-data object.
+ ///
+ /// When you finish encoding data, you must invoke `finishEncoding()` at which point data
+ /// is filled. The format of the archive is `NSPropertyListBinaryFormat_v1_0`.
+ ///
+ /// - Parameter data: The mutable-data object into which the archive is written.
public convenience init(forWritingWith data: NSMutableData) {
self.init(output: data)
}
@@ -162,8 +212,12 @@
return __CFBinaryPlistWriteToStream(plist, self._stream) > 0
}
-
- /// If encoding has not yet finished, then invoking this property will call finishEncoding and return the data. If you initialized the keyed archiver with a specific mutable data instance, then it will be returned from this property after finishEncoding is called.
+ /// Returns the encoded data for the archiver.
+ ///
+ /// If encoding has not yet finished, invoking this property calls `finishEncoding()`
+ /// and returns the data. If you initialized the keyed archiver with a specific
+ /// mutable data instance, then that data is returned by the property after
+ /// `finishEncoding()` is called.
open var encodedData: Data {
if !_flags.contains(.finishedEncoding) {
@@ -173,6 +227,9 @@
return (_stream as! NSData)._swiftObject
}
+ /// Instructs the archiver to construct the final data stream.
+ ///
+ /// No more values can be encoded after this method is called. You must call this method when finished.
open func finishEncoding() {
if _flags.contains(ArchiverFlags.finishedEncoding) {
return
@@ -209,6 +266,15 @@
}
}
+ /// Adds a class translation mapping to `NSKeyedArchiver` whereby instances of a given
+ /// class are encoded with a given class name instead of their real class names.
+ ///
+ /// When encoding, the class’s translation mapping is used only if no translation
+ /// is found first in an instance’s separate translation map.
+ ///
+ /// - 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.
open class func setClassName(_ codedName: String?, for cls: AnyClass) {
let clsName = String(describing: type(of: cls))
_classNameMapLock.synchronized {
@@ -216,6 +282,15 @@
}
}
+ /// Adds a class translation mapping to `NSKeyedArchiver` whereby instances of a given
+ /// class are encoded with a given class name instead of their real class names.
+ ///
+ /// When encoding, the receiver’s translation map overrides any translation
+ /// that may also be present in the class’s map.
+ ///
+ /// - Parameters:
+ /// - codedName: The name of the class that the archiver uses in place of `cls`.
+ /// - cls: The class for which to set up a translation mapping.
open func setClassName(_ codedName: String?, for cls: AnyClass) {
let clsName = String(describing: type(of: cls))
_classNameMap[clsName] = codedName
@@ -581,10 +656,21 @@
_encodeObject(object, forKey: nil, conditional: true)
}
+ /// Encodes a given object and associates it with a given key.
+ ///
+ /// - Parameters:
+ /// - objv: The value to encode.
+ /// - key: The key with which to associate `objv`.
open override func encode(_ objv: Any?, forKey key: String) {
_encodeObject(objv, forKey: key, conditional: false)
}
+ /// 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 `encode(_:forKey:)`.
+ ///
+ /// - Parameters:
+ /// - objv: The object to encode.
+ /// - key: The key with which to associate the encoded value.
open override func encodeConditionalObject(_ objv: Any?, forKey key: String) {
_encodeObject(objv, forKey: key, conditional: true)
}
@@ -683,27 +769,57 @@
}
}
+ /// Encodes a given Boolean value and associates it with a given key.
+ ///
+ /// - Parameters:
+ /// - boolv: The value to encode.
+ /// - key: The key with which to associate `boolv`.
open override func encode(_ boolv: Bool, forKey key: String) {
_encodeValue(NSNumber(value: boolv), forKey: key)
}
+ /// Encodes a given 32-bit integer value and associates it with a given key.
+ ///
+ /// - Parameters:
+ /// - intv: The value to encode.
+ /// - key: The key with which to associate `intv`.
open override func encode(_ intv: Int32, forKey key: String) {
_encodeValue(NSNumber(value: intv), forKey: key)
}
+ /// Encodes a given 64-bit integer value and associates it with a given key.
+ ///
+ /// - Parameters:
+ /// - intv: The value to encode.
+ /// - key: The key with which to associate `intv`.
open override func encode(_ intv: Int64, forKey key: String) {
_encodeValue(NSNumber(value: intv), forKey: key)
}
+ /// Encodes a given float value and associates it with a given key.
+ ///
+ /// - Parameters:
+ /// - realv: The value to encode.
+ /// - key: The key with which to associate `realv`.
open override func encode(_ realv: Float, forKey key: String) {
_encodeValue(NSNumber(value: realv), forKey: key)
}
+ /// Encodes a given double value and associates it with a given key.
+ ///
+ /// - Parameters:
+ /// - realv: The value to encode.
+ /// - key: The key with which to associate `realv`.
open override func encode(_ realv: Double, forKey key: String) {
_encodeValue(NSNumber(value: realv), forKey: key)
}
+ /// Encodes a given integer value and associates it with a given key.
+ ///
+ /// - Parameters:
+ /// - intv: The value to encode.
+ /// - key: The key with which to associate `intv`.
open override func encode(_ intv: Int, forKey key: String) {
_encodeValue(NSNumber(value: intv), forKey: key)
}
@@ -713,6 +829,13 @@
encode(data._nsObject)
}
+ /// Encodes a given number of bytes from a given C array of bytes and associates
+ /// them with the a given 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.
open override func encodeBytes(_ bytesp: UnsafePointer<UInt8>?, length lenv: Int, forKey key: String) {
// this encodes the data inline
let data = NSData(bytes: bytesp, length: lenv)
@@ -737,14 +860,10 @@
_encodeValue(objectRefs._bridgeToObjectiveC(), forKey: key)
}
- /**
- Enables secure coding support on this keyed archiver. You do not need to enable
- secure coding on the archiver to enable secure coding on the unarchiver. Enabling
- secure coding on the archiver is a way for you to be sure that all classes that
- are encoded conform with NSSecureCoding (it will throw an exception if a class
- which does not NSSecureCoding is archived). Note that the getter is on the superclass,
- NSCoder. See NSCoder for more information about secure coding.
- */
+ /// Indicates whether the archiver requires all archived classes to conform to `NSSecureCoding`.
+ ///
+ /// If you set the receiver to require secure coding, it will cause a fatal error
+ /// if you attempt to archive a class which does not conform to `NSSecureCoding`.
open override var requiresSecureCoding: Bool {
get {
return _flags.contains(ArchiverFlags.requiresSecureCoding)
@@ -758,8 +877,11 @@
}
}
- // During encoding, the coder first checks with the coder's
- // own table, then if there was no mapping there, the class's.
+ /// Returns the class name with which `NSKeyedArchiver` encodes instances of a given class.
+ ///
+ /// - Parameter cls: The class for which to determine the translation mapping.
+ /// - Returns: The class name with which `NSKeyedArchiver` encodes instances of `cls`.
+ /// Returns `nil` if `NSKeyedArchiver` does not have a translation mapping for `cls`.
open class func classNameForClass(_ cls: AnyClass) -> String? {
let clsName = String(reflecting: cls)
var mappedClass : String?
@@ -771,6 +893,12 @@
return mappedClass
}
+ /// Returns the class name with which the archiver encodes instances of a given class.
+ ///
+ /// - Parameter cls: The class for which to determine the translation mapping.
+ /// - Returns: The class name with which the receiver encodes instances of cls.
+ /// Returns `nil` if the archiver does not have a translation
+ /// mapping for `cls`. The class’s separate translation map is not searched.
open func classNameForClass(_ cls: AnyClass) -> String? {
let clsName = String(reflecting: cls)
return _classNameMap[clsName]
@@ -793,34 +921,62 @@
}
+/// The `NSKeyedArchiverDelegate` protocol defines the optional methods implemented
+/// by delegates of `NSKeyedArchiver` objects.
public protocol NSKeyedArchiverDelegate : class {
- // Informs the delegate that the object is about to be encoded. The delegate
- // either returns this object or can return a different object to be encoded
- // instead. The delegate can also fiddle with the coder state. If the delegate
- // returns nil, nil is encoded. This method is called after the original object
- // may have replaced itself with replacementObject(for:).
- // This method is not called for an object once a replacement mapping has been
- // setup for that object (either explicitly, or because the object has previously
- // been encoded). This is also not called when nil is about to be encoded.
- // This method is called whether or not the object is being encoded conditionally.
+ /// Informs the delegate that `object` is about to be encoded.
+ ///
+ /// This method is called after the original object may have replaced itself
+ /// with `replacementObject(for:)`.
+ ///
+ /// This method is called whether or not the object is being encoded conditionally.
+ ///
+ /// This method is not called for an object once a replacement mapping has been set up
+ /// for that object (either explicitly, or because the object has previously been encoded).
+ /// This method is also not called when `nil` is about to be encoded.
+ ///
+ /// - Parameters:
+ /// - archiver: The archiver that invoked the method.
+ /// - object: The object that is about to be encoded.
+ /// - Returns: Either object or a different object to be encoded in its stead.
+ /// The delegate can also modify the coder state. If the delegate
+ /// returns `nil`, `nil` is encoded.
func archiver(_ archiver: NSKeyedArchiver, willEncode object: Any) -> Any?
- // Informs the delegate that the given object has been encoded. The delegate
- // might restore some state it had fiddled previously, or use this to keep
- // track of the objects which are encoded. The object may be nil. Not called
- // for conditional objects until they are really encoded (if ever).
+ /// Informs the delegate that a given object has been encoded.
+ ///
+ /// The delegate might restore some state it had modified previously,
+ /// or use this opportunity to keep track of the objects that are encoded.
+ ///
+ /// This method is not called for conditional objects until they are actually encoded (if ever).
+ ///
+ /// - Parameters:
+ /// - archiver: The archiver that invoked the method.
+ /// - object: The object that has been encoded.
func archiver(_ archiver: NSKeyedArchiver, didEncode object: Any?)
- // Informs the delegate that the newObject is being substituted for the
- // object. This is also called when the delegate itself is doing/has done
- // the substitution. The delegate may use this method if it is keeping track
- // of the encoded or decoded objects.
+ /// Informs the delegate that one given object is being substituted for another given object.
+ ///
+ /// This method is called even when the delegate itself is doing, or has done,
+ /// the substitution. The delegate may use this method if it is keeping track
+ /// of the encoded or decoded objects.
+ ///
+ /// - Parameters:
+ /// - archiver: The archiver that invoked the method.
+ /// - object: The object being replaced in the archive.
+ /// - newObject: The object replacing `object` in the archive.
func archiver(_ archiver: NSKeyedArchiver, willReplace object: Any?, withObject newObject: Any?)
- // Notifies the delegate that encoding is about to finish.
+
+ /// Notifies the delegate that encoding is about to finish.
+ ///
+ /// - Parameter archiver: The archiver that invoked the method.
func archiverWillFinish(_ archiver: NSKeyedArchiver)
- // Notifies the delegate that encoding has finished.
+
+ /// Notifies the delegate that encoding has finished.
+ ///
+ /// - Parameter archiver: The archiver that invoked the method.
func archiverDidFinish(_ archiver: NSKeyedArchiver)
}
