Class

NSData

NSData and its mutable subclass NSMutableData provide data objects, object-oriented wrappers for byte buffers. Data objects let simple allocated buffers (that is, data with no embedded pointers) take on the behavior of Foundation objects.

Overview

NSData creates static data objects, and NSMutableData creates dynamic data objects. NSData and NSMutableData are typically used for data storage and are also useful in Distributed Objects applications, where data contained in data objects can be copied or moved between applications.

The size of the data is subject to a theoretical limit of about 8 ExaBytes (in practice, the limit should not be a factor).

NSData is “toll-free bridged” with its Core Foundation counterpart, CFData. See Toll-Free Bridging for more information on toll-free bridging.

Saving Data

The NSData class and its subclasses provide methods to quickly and easily save their contents to disk. To minimize the risk of data loss, these methods provide the option of saving the data atomically. Atomic writes guarantee that the data is either saved in its entirety, or it fails completely. The atomic write begins by writing the data to a temporary file. If this write succeeds, then the method moves the temporary file to its final location.

While atomic write operations minimize the risk of data loss due to corrupt or partially-written files, they may not be appropriate when writing to a temporary directory, the user’s home directory or other publicly accessible directories. Any time you work with a publicly accessible file, you should treat that file as an untrusted and potentially dangerous resource. An attacker may compromise or corrupt these files. The attacker can also replace the files with hard or symbolic links, causing your write operations to overwrite or corrupt other system resources.

Avoid using the write(to:atomically:) method (and the related methods) when working inside a publicly accessible directory. Instead initialize an FileHandle object with an existing file descriptor and use the NSFileHandle methods to securely write the file.

For more information, see Securing File Operations in Secure Coding Guide.

Nested Types

NSDataReadingOptions

Options for methods used to read NSData objects.

NSDataBase64EncodingOptions

Options for methods used to Base-64 encode data.

NSDataBase64DecodingOptions

Options to modify the decoding algorithm used to decode Base-64 encoded NSData objects.

NSDataWritingOptions

Options for methods used to write NSData objects.

NSDataSearchOptions

Options for method used to search NSData objects. These options are used with the range(of:options:in:) method.

Symbols

Creating Data Objects

class func dataWithContentsOfMappedFile(String)

Creates and returns a data object from the mapped file specified by path.

Deprecated
init?(base64Encoded: Data, options: NSData.Base64DecodingOptions = [])

Returns a data object initialized with the given Base-64 encoded data.

init?(base64Encoded: String, options: NSData.Base64DecodingOptions = [])

Returns a data object initialized with the given Base-64 encoded string.

init(bytes: UnsafeRawPointer?, length: Int)

Returns a data object initialized by adding to it a given number of bytes of data copied from a given buffer.

init(bytesNoCopy: UnsafeMutableRawPointer, length: Int)

Returns a data object initialized by adding to it a given number of bytes of data from a given buffer.

init(bytesNoCopy: UnsafeMutableRawPointer, length: Int, deallocator: (UnsafeMutableRawPointer, Int) -> Void)? = nil)

Returns a data object initialized by adding to it a given number of bytes of data from a given buffer, with a custom deallocator block.

init(bytesNoCopy: UnsafeMutableRawPointer, length: Int, freeWhenDone: Bool)

Initializes a newly allocated data object by adding to it length bytes of data from the buffer bytes.

init?(contentsOfFile: String)

Returns a data object initialized by reading into it the data from the file specified by a given path.

init(contentsOfFile: String, options: NSData.ReadingOptions = [])

Returns a data object initialized by reading into it the data from the file specified by a given path.

init?(contentsOfMappedFile: String)

Returns a data object initialized by reading into it the mapped file specified by a given path.

Deprecated
init?(contentsOf: URL)

Initializes a newly allocated data object initialized with the data from the location specified by aURL.

init(contentsOf: URL, options: NSData.ReadingOptions = [])

Returns a data object initialized with the data from the location specified by a given URL.

init(data: Data)

Returns a data object initialized with the contents of another data object.

Accessing Data

var bytes: UnsafeRawPointer

A pointer to the receiver’s contents.

var description: String

A string that contains a hexadecimal representation of the object’s contents in a property list format.

func enumerateBytes((UnsafeRawPointer, NSRange, UnsafeMutablePointer<ObjCBool>) -> Void)

Enumerate through each range of bytes in the data object using a block.

func getBytes(UnsafeMutableRawPointer)

Copies a data object’s contents into a given buffer.

Deprecated
func getBytes(UnsafeMutableRawPointer, length: Int)

Copies a number of bytes from the start of the receiver's data into a given buffer.

func getBytes(UnsafeMutableRawPointer, range: NSRange)

Copies a range of bytes from the receiver’s data into a given buffer.

func subdata(with: NSRange)

Returns a data object containing the receiver’s bytes that fall within the limits specified by a given range.

func range(of: Data, options: NSData.SearchOptions = [], in: NSRange)

Finds and returns the range of the first occurrence of the given data, within the given range, subject to given options.

Base-64 Encoding

func base64EncodedData(options: NSData.Base64EncodingOptions = [])

Create a Base-64, UTF-8 encoded NSData from the receiver's contents using the given options.

func base64EncodedString(options: NSData.Base64EncodingOptions = [])

Create a Base-64 encoded NSString from the receiver's contents using the given options.

Testing Data

func isEqual(to: Data)

Compares the receiving data object to otherData.

var length: Int

The number of bytes contained by the data object.

Storing Data

func write(toFile: String, atomically: Bool)

Writes the bytes in the receiver to the file specified by a given path.

func write(toFile: String, options: NSData.WritingOptions = [])

Writes the bytes in the receiver to the file specified by a given path.

func write(to: URL, atomically: Bool)

Writes the bytes in the receiver to the location specified by aURL.

func write(to: URL, options: NSData.WritingOptions = [])

Writes the bytes in the receiver to the location specified by a given URL.

Constants

ReadingOptions

Options for methods used to read NSData objects.

Base64EncodingOptions

Options for methods used to Base-64 encode data.

Base64DecodingOptions

Options to modify the decoding algorithm used to decode Base-64 encoded NSData objects.

Legacy Reading Options

Deprecated names for reading options. Do not use these names, use the new replacements instead.

WritingOptions

Options for methods used to write NSData objects.

Legacy Writing Options

Deprecated names for writing options. Do not use these names, use the new replacements instead.

SearchOptions

Options for method used to search NSData objects. These options are used with the range(of:options:in:) method.