NSData (NSObject) <NSCopying, NSObject, NSSecureCoding, NSMutableCopying>

Next

Overview

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.

NSData creates static data objects, and NSMutableData creates dynamic data objects. NSData andNSMutableData 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,CFDataRef. See “Toll-Free Bridging” for more information on toll-free bridging.

Tasks

Creating Data Objects

• + data
• + dataWithBytes:length:
• + dataWithBytesNoCopy:length:
• + dataWithBytesNoCopy:length:freeWhenDone:
• + dataWithContentsOfFile:
• + dataWithContentsOfFile:options:error:
• + dataWithContentsOfURL:
• + dataWithContentsOfURL:options:error:
• + dataWithData:
• – initWithBase64EncodedData:options:
• – initWithBase64EncodedString:options:
• – initWithBytes:length:
• – initWithBytesNoCopy:length:
• – initWithBytesNoCopy:length:deallocator:
• – initWithBytesNoCopy:length:freeWhenDone:
• – initWithContentsOfFile:
• – initWithContentsOfFile:options:error:
• – initWithContentsOfURL:
• – initWithContentsOfURL:options:error:
• – initWithData:
• + dataWithContentsOfMappedFile:Deprecated in OS X v10.7
• – initWithContentsOfMappedFile:Deprecated in OS X v10.7
• – initWithBase64Encoding:Deprecated in OS X v10.9

Accessing Data

• – bytes
• – description
• – enumerateByteRangesUsingBlock:
• – getBytes:length:
• – getBytes:range:
• – subdataWithRange:
• – rangeOfData:options:range:
• – getBytes:Deprecated in OS X v10.6

Base-64 Encoding

• – base64EncodedDataWithOptions:
• – base64EncodedStringWithOptions:
• – base64EncodingDeprecated in OS X v10.9

Testing Data

• – isEqualToData:
• – length

Storing Data

• – writeToFile:atomically:
• – writeToFile:options:error:
• – writeToURL:atomically:
• – writeToURL:options:error:

Class Methods

data

Creates and returns an empty data object.

+ (id)data

Return Value

An empty data object.

Discussion

This method is declared primarily for the use of mutable subclasses ofNSData.

Availability

• Available in OS X v10.0 and later.

Related Sample Code

• ClipboardViewer
• CryptoCompatibility
• Quartz Composer CommandLineTool
• Quartz Composer SQLiteQuery
• With and Without Bindings

Declared In

NSData.h

dataWithBytes:length:

Creates and returns a data object containing a given number of bytes copied from a given buffer.

+ (id)dataWithBytes:(const void *)bytes length:(NSUInteger)length

Parameters

bytes

A buffer containing data for the new object.

length

The number of bytes to copy from bytes. This value must not exceed the length of bytes.

Return Value

A data object containing length bytes copied from the buffer bytes. Returnsnil if the data object could not be created.

Availability

• Available in OS X v10.0 and later.

See Also

• + dataWithBytesNoCopy:length:
• + dataWithBytesNoCopy:length:freeWhenDone:

Related Sample Code

• From A View to A Movie
• From A View to A Picture
• QTCoreVideo301
• Quartz Composer MiniSOAP
• UDPEcho

Declared In

NSData.h

dataWithBytesNoCopy:length:

Creates and returns a data object that holds length bytes from the buffer bytes.

+ (id)dataWithBytesNoCopy:(void *)bytes length:(NSUInteger)length

Parameters

bytes

A buffer containing data for the new object. bytes must point to a memory block allocated withmalloc.

length

The number of bytes to hold from bytes. This value must not exceed the length of bytes.

Return Value

A data object that holds length bytes from the buffer bytes. Returnsnil if the data object could not be created.

Discussion

The returned object takes ownership of the bytes pointer and frees it on deallocation. Therefore, bytes must point to a memory block allocated withmalloc.

Availability

• Available in OS X v10.0 and later.

See Also

• + dataWithBytes:length:
• + dataWithBytesNoCopy:length:freeWhenDone:

Declared In

NSData.h

dataWithBytesNoCopy:length:freeWhenDone:

Creates and returns a data object that holds a given number of bytes from a given buffer.

+ (id)dataWithBytesNoCopy:(void *)bytes length:(NSUInteger)length freeWhenDone:(BOOL)freeWhenDone

Parameters

bytes

A buffer containing data for the new object. If freeWhenDone is YES, bytes must point to a memory block allocated withmalloc.

length

The number of bytes to hold from bytes. This value must not exceed the length of bytes.

freeWhenDone

If YES, the returned object takes ownership of the bytes pointer and frees it on deallocation.

Return Value

A data object that holds length bytes from the buffer bytes. Returnsnil if the data object could not be created.

Availability

• Available in OS X v10.2 and later.

See Also

• + dataWithBytes:length:
• + dataWithBytesNoCopy:length:

Related Sample Code

• CocoaSpeechSynthesisExample

Declared In

NSData.h

dataWithContentsOfFile:

Creates and returns a data object by reading every byte from the file specified by a given path.

+ (id)dataWithContentsOfFile:(NSString *)path

Parameters

path

The absolute path of the file from which to read data.

Return Value

A data object by reading every byte from the file specified by path. Returnsnil if the data object could not be created.

Discussion

This method is equivalent to dataWithContentsOfFile:options:error: with no options. If you need to know what was the reason for failure, usedataWithContentsOfFile:options:error:.

A sample using this method can be found in “Working With Binary Data”.

Availability

• Available in OS X v10.0 and later.

See Also

• + dataWithContentsOfFile:options:error:
• + dataWithContentsOfMappedFile:

Related Sample Code

• CocoaSlides
• Denoise
• iSpend
• QTCoreVideo102
• QTCoreVideo202

Declared In

NSData.h

dataWithContentsOfFile:options:error:

Creates and returns a data object by reading every byte from the file specified by a given path.

+ (id)dataWithContentsOfFile:(NSString *)path options:(NSDataReadingOptions)mask error:(NSError **)errorPtr

Parameters

path

The absolute path of the file from which to read data.

mask

A mask that specifies options for reading the data. Constant components are described in“NSDataReadingOptions”.

errorPtr

If an error occurs, upon return contains an NSError object that describes the problem.

Return Value

A data object by reading every byte from the file specified by path. Returnsnil if the data object could not be created.

Availability

• Available in OS X v10.4 and later.

Declared In

NSData.h

dataWithContentsOfURL:

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

+ (id)dataWithContentsOfURL:(NSURL *)aURL

Parameters

aURL

The URL from which to read data.

Return Value

A data object containing the data from the location specified by aURL. Returnsnil if the data object could not be created.

Discussion

If you need to know what was the reason for failure, use dataWithContentsOfURL:options:error:.

Availability

• Available in OS X v10.0 and later.

See Also

• + dataWithContentsOfURL:options:error:
• – initWithContentsOfURL:

Related Sample Code

• CocoaSpeechSynthesisExample
• CryptoCompatibility
• DispatchFractal
• LightTable
• Quartz Composer MiniSOAP

Declared In

NSData.h

dataWithContentsOfURL:options:error:

Creates and returns a data object containing the data from the location specified by aURL.

+ (id)dataWithContentsOfURL:(NSURL *)aURL options:(NSDataReadingOptions)mask error:(NSError **)errorPtr

Parameters

aURL

The URL from which to read data.

mask

A mask that specifies options for reading the data. Constant components are described in“NSDataReadingOptions”.

errorPtr

If there is an error reading in the data, upon return contains an NSError object that describes the problem.

Availability

• Available in OS X v10.4 and later.

See Also

• – initWithContentsOfURL:

Related Sample Code

• CryptoCompatibility
• ZipBrowser

Declared In

NSData.h

dataWithData:

Creates and returns a data object containing the contents of another data object.

+ (id)dataWithData:(NSData *)aData

Parameters

aData

A data object.

Return Value

A data object containing the contents of aData. Returns nil if the data object could not be created.

Availability

• Available in OS X v10.0 and later.

See Also

• – initWithData:

Declared In

NSData.h

Instance Methods

base64EncodedDataWithOptions:

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

- (NSData *)base64EncodedDataWithOptions:(NSDataBase64EncodingOptions)options

Parameters

options

A mask that specifies options for Base-64 encoding the data. Possible values are given in“NSDataBase64EncodingOptions”.

Return Value

A Base-64, UTF-8 encoded data object.

Discussion

By default, no line endings are inserted.

If you specify one of the line length options (NSDataBase64Encoding64CharacterLineLength orNSDataBase64Encoding76CharacterLineLength) but don’t specify the kind of line ending to insert, the default line ending is Carriage Return + Line Feed.

Availability

• Available in OS X v10.9 and later.

Declared In

NSData.h

base64EncodedStringWithOptions:

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

- (NSString *)base64EncodedStringWithOptions:(NSDataBase64EncodingOptions)options

Parameters

options

A mask that specifies options for Base-64 encoding the data. Possible values are given in“NSDataBase64EncodingOptions”.

Return Value

A Base-64 encoded string.

Discussion

By default, no line endings are inserted.

If you specify one of the line length options (NSDataBase64Encoding64CharacterLineLength orNSDataBase64Encoding76CharacterLineLength) but don’t specify the kind of line ending to insert, the default line ending is Carriage Return + Line Feed.

Availability

• Available in OS X v10.9 and later.

Declared In

NSData.h

bytes

Returns a pointer to the receiver’s contents.

- (const void *)bytes

Return Value

A read-only pointer to the receiver’s contents.

Discussion

If the length of the receiver is 0, this method returnsnil.

Availability

• Available in OS X v10.0 and later.

See Also

• – description
• – getBytes:
• – getBytes:length:
• – getBytes:range:

Related Sample Code

• CryptoCompatibility
• Quartz Composer MiniSOAP
• Quartz Composer SQLiteQuery
• UDPEcho
• ZipBrowser

Declared In

NSData.h

description

Returns an NSString object that contains a hexadecimal representation of the receiver’s contents.

- (NSString *)description

Return Value

An NSString object that contains a hexadecimal representation of the receiver’s contents inNSData property list format.

Availability

• Available in OS X v10.0 and later.

See Also

• – bytes
• – getBytes:
• – getBytes:length:
• – getBytes:range:

Declared In

NSData.h

enumerateByteRangesUsingBlock:

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

- (void)enumerateByteRangesUsingBlock:(void (^)(const void *bytes, NSRange byteRange, BOOL *stop))block

Parameters

block

The block to apply to byte ranges in the array.

The block takes three arguments:

bytes

The bytes for the current range.

byteRange

The range of the current data bytes.

stop

A reference to a Boolean value. The block can set the value to YES to stop further processing of the data. The stop argument is an out-only argument. You should only ever set this Boolean toYES within the Block.

Discussion

The enumeration block is called once for each contiguous region of memory in the receiver (once total for a contiguousNSData object), until either all bytes have been enumerated, or thestop parameter is set to YES.

Availability

• Available in OS X v10.9 and later.

Declared In

NSData.h

getBytes:length:

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

- (void)getBytes:(void *)buffer length:(NSUInteger)length

Parameters

buffer

A buffer into which to copy data.

length

The number of bytes from the start of the receiver's data to copy to buffer.

Discussion

The number of bytes copied is the smaller of the length parameter and thelength of the data encapsulated in the object.

Availability

• Available in OS X v10.0 and later.

See Also

• – bytes
• – description
• – getBytes:
• – getBytes:range:

Related Sample Code

• QTCoreVideo301
• UDPEcho

Declared In

NSData.h

getBytes:range:

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

- (void)getBytes:(void *)buffer range:(NSRange)range

Parameters

buffer

A buffer into which to copy data.

range

The range of bytes in the receiver's data to copy to buffer. The range must lie within the range of bytes of the receiver's data.

Discussion

If range isn’t within the receiver’s range of bytes, an NSRangeException is raised.

Availability

• Available in OS X v10.0 and later.

See Also

• – bytes
• – description
• – getBytes:
• – getBytes:length:

Declared In

NSData.h

initWithBase64EncodedData:options:

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

- (id)initWithBase64EncodedData:(NSData *)base64Data options:(NSDataBase64DecodingOptions)options

Parameters

base64Data

A Base-64, UTF-8 encoded data object.

options

A mask that specifies options for Base-64 decoding the data. Possible values are given in“NSDataBase64DecodingOptions”.

Return Value

A data object containing the Base-64 decoded data. Returns nil if the data object could not be decoded.

Discussion

The default implementation of this method will reject non-alphabet characters, including line break characters. To support different encodings and ignore non-alphabet characters, specify anoptions value of NSDataBase64DecodingIgnoreUnknownCharacters.

Availability

• Available in OS X v10.9 and later.

Declared In

NSData.h

initWithBase64EncodedString:options:

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

- (id)initWithBase64EncodedString:(NSString *)base64String options:(NSDataBase64DecodingOptions)options

Parameters

base64String

A Base-64 encoded string.

options

A mask that specifies options for Base-64 decoding the data. Possible values are given in“NSDataBase64DecodingOptions”.

Return Value

A data object built by Base-64 decoding the provided string. Returnsnil if the data object could not be decoded.

Discussion

The default implementation of this method will reject non-alphabet characters, including line break characters. To support different encodings and ignore non-alphabet characters, specify anoptions value of NSDataBase64DecodingIgnoreUnknownCharacters.

Availability

• Available in OS X v10.9 and later.

Declared In

NSData.h

initWithBytes:length:

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

- (id)initWithBytes:(const void *)bytes length:(NSUInteger)length

Discussion

A data object initialized by adding to it length bytes of data copied from the buffer bytes. The returned object might be different than the original receiver.

Availability

• Available in OS X v10.0 and later.

See Also

• + dataWithBytes:length:
• – initWithBytesNoCopy:length:
• – initWithBytesNoCopy:length:freeWhenDone:

Related Sample Code

• CryptoCompatibility
• EvenBetterAuthorizationSample

Declared In

NSData.h

initWithBytesNoCopy:length:

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

- (id)initWithBytesNoCopy:(void *)bytes length:(NSUInteger)length

Parameters

bytes

A buffer containing data for the new object. bytes must point to a memory block allocated withmalloc.

length

The number of bytes to hold from bytes. This value must not exceed the length of bytes.

Return Value

A data object initialized by adding to it length bytes of data from the buffer bytes. The returned object might be different than the original receiver.

Discussion

The returned object takes ownership of the bytes pointer and frees it on deallocation. Therefore, bytes must point to a memory block allocated withmalloc.

Availability

• Available in OS X v10.0 and later.

See Also

• + dataWithBytes:length:
• – initWithBytes:length:
• – initWithBytesNoCopy:length:freeWhenDone:

Declared In

NSData.h

initWithBytesNoCopy:length:deallocator:

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.

- (id)initWithBytesNoCopy:(void *)bytes length:(NSUInteger)length deallocator:(void (^)(void *bytes, NSUInteger length))deallocator

Parameters

bytes

A buffer containing data for the new object.

length

The number of bytes to hold from bytes. This value must not exceed the length of bytes.

deallocator

A block to invoke when the resulting NSData object is deallocated.

Return Value

A data object initialized by adding to it length bytes of data from the buffer bytes. The returned object might be different than the original receiver.

Discussion

Use this method to define your own deallocation behavior for the data buffer you provide.

In order to avoid any inadvertent strong reference cycles, you should avoid capturing pointers to any objects that may in turn maintain strong references to theNSData object. This includes explicit references to self, and implicit references to self due to direct instance variable access. To make it easier to avoid these references, thedeallocator block takes two parameters, a pointer to the buffer, and its length; you should always use these values instead of trying to use references from outside the block.

Availability

• Available in OS X v10.9 and later.

Declared In

NSData.h

initWithBytesNoCopy:length:freeWhenDone:

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

- (id)initWithBytesNoCopy:(void *)bytes length:(NSUInteger)length freeWhenDone:(BOOL)flag

Parameters

bytes

A buffer containing data for the new object. If flag is YES, bytes must point to a memory block allocated withmalloc.

length

The number of bytes to hold from bytes. This value must not exceed the length of bytes.

flag

If YES, the returned object takes ownership of the bytes pointer and frees it on deallocation.

Availability

• Available in OS X v10.2 and later.

See Also

• + dataWithBytesNoCopy:length:freeWhenDone:
• – initWithBytes:length:
• – initWithBytesNoCopy:length:

Related Sample Code

• VirtualScanner

Declared In

NSData.h

initWithContentsOfFile:

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

- (id)initWithContentsOfFile:(NSString *)path

Parameters

path

The absolute path of the file from which to read data.

Return Value

A data object initialized by reading into it the data from the file specified by path. The returned object might be different than the original receiver.

Discussion

This method is equivalent to initWithContentsOfFile:options:error: with no options.

Availability

• Available in OS X v10.0 and later.

See Also

• + dataWithContentsOfFile:
• – initWithContentsOfMappedFile:

Declared In

NSData.h

initWithContentsOfFile:options:error:

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

- (id)initWithContentsOfFile:(NSString *)path options:(NSDataReadingOptions)mask error:(NSError **)errorPtr

Parameters

path

The absolute path of the file from which to read data.

mask

A mask that specifies options for reading the data. Constant components are described in“NSDataReadingOptions”.

errorPtr

If an error occurs, upon return contains an NSError object that describes the problem.

Return Value

A data object initialized by reading into it the data from the file specified by path. The returned object might be different than the original receiver.

Availability

• Available in OS X v10.4 and later.

See Also

• + dataWithContentsOfFile:options:error:

Declared In

NSData.h

initWithContentsOfURL:

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

- (id)initWithContentsOfURL:(NSURL *)aURL

Parameters

aURL

The URL from which to read data

Return Value

An NSData object initialized with the data from the location specified by aURL. The returned object might be different than the original receiver.

Availability

• Available in OS X v10.0 and later.

See Also

• + dataWithContentsOfURL:

Declared In

NSData.h

initWithContentsOfURL:options:error:

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

- (id)initWithContentsOfURL:(NSURL *)aURL options:(NSDataReadingOptions)mask error:(NSError **)errorPtr

Parameters

aURL

The URL from which to read data.

mask

A mask that specifies options for reading the data. Constant components are described in“NSDataReadingOptions”.

errorPtr

If there is an error reading in the data, upon return contains an NSError object that describes the problem.

Return Value

A data object initialized with the data from the location specified by aURL. The returned object might be different than the original receiver.

Availability

• Available in OS X v10.4 and later.

See Also

• + dataWithContentsOfURL:options:error:

Declared In

NSData.h

initWithData:

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

- (id)initWithData:(NSData *)data

Parameters

data

A data object.

Return Value

A data object initialized with the contents data. The returned object might be different than the original receiver.

Availability

• Available in OS X v10.0 and later.

See Also

• + dataWithData:

Declared In

NSData.h

isEqualToData:

Compares the receiving data object to otherData.

- (BOOL)isEqualToData:(NSData *)otherData

Parameters

otherData

The data object with which to compare the receiver.

Return Value

YES if the contents of otherData are equal to the contents of the receiver, otherwiseNO.

Discussion

Two data objects are equal if they hold the same number of bytes, and if the bytes at the same position in the objects are the same.

Availability

• Available in OS X v10.0 and later.

Declared In

NSData.h

length

Returns the number of bytes contained in the receiver.

- (NSUInteger)length

Return Value

The number of bytes contained in the receiver.

Availability

• Available in OS X v10.0 and later.

Related Sample Code

• CryptoCompatibility
• Quartz Composer MiniSOAP
• Quartz Composer SQLiteQuery
• UDPEcho
• ZipBrowser

Declared In

NSData.h

rangeOfData:options:range:

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

- (NSRange)rangeOfData:(NSData *)dataToFind options:(NSDataSearchOptions)mask range:(NSRange)searchRange

Parameters

dataToFind

The data for which to search. This value must not be nil.

Important: Raises an NSInvalidArgumentException if dataToFind is nil.

mask

A mask specifying search options. The “NSDataSearchOptions” options may be specified singly or by combining them with the C bitwiseOR operator.

searchRange

The range within the receiver in which to search for dataToFind. If this range is not within the receiver’s range of bytes, anNSRangeException raised.

Return Value

An NSRange structure giving the location and length of dataToFind within searchRange, modulo the options in mask. The range returned is relative to the start of the searched data, not the passed-in search range. Returns{NSNotFound, 0} if dataToFind is not found or is empty (@"").

Availability

• Available in OS X v10.6 and later.

Declared In

NSData.h

subdataWithRange:

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

- (NSData *)subdataWithRange:(NSRange)range

Parameters

range

The range in the receiver from which to get the data. The range must not exceed the bounds of the receiver.

Return Value

A data object containing the receiver’s bytes that fall within the limits specified by range. If range isn’t within the receiver’s range of bytes, raisesNSRangeException.

Discussion

A sample using this method can be found in “Working With Binary Data”.

Availability

• Available in OS X v10.0 and later.

Related Sample Code

• CryptoCompatibility

Declared In

NSData.h

writeToFile:atomically:

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

- (BOOL)writeToFile:(NSString *)path atomically:(BOOL)flag

Parameters

path

The location to which to write the receiver's bytes. If path contains a tilde (~) character, you must expand it withstringByExpandingTildeInPath before invoking this method.

atomically

If YES, the data is written to a backup file, and then—assuming no errors occur—the backup file is renamed to the name specified by path; otherwise, the data is written directly to path.

Return Value

YES if the operation succeeds, otherwise NO.

Availability

• Available in OS X v10.0 and later.

See Also

• – writeToURL:atomically:

Related Sample Code

• CameraBrowser
• ImageKitDemo

Declared In

NSData.h

writeToFile:options:error:

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

- (BOOL)writeToFile:(NSString *)path options:(NSDataWritingOptions)mask error:(NSError **)errorPtr

Parameters

path

The location to which to write the receiver's bytes.

mask

A mask that specifies options for writing the data. Constant components are described in“NSDataWritingOptions”.

errorPtr

If there is an error writing out the data, upon return contains anNSError object that describes the problem.

Return Value

YES if the operation succeeds, otherwise NO.

Availability

• Available in OS X v10.4 and later.

See Also

• – writeToURL:options:error:

Related Sample Code

• From A View to A Movie
• From A View to A Picture

Declared In

NSData.h

writeToURL:atomically:

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

- (BOOL)writeToURL:(NSURL *)aURL atomically:(BOOL)atomically

Parameters

aURL

The location to which to write the receiver's bytes. Only file:// URLs are supported.

atomically

If YES, the data is written to a backup location, and then—assuming no errors occur—the backup location is renamed to the name specified by aURL; otherwise, the data is written directly to aURL. atomically is ignored if aURL is not of a type the supports atomic writes.

Return Value

YES if the operation succeeds, otherwise NO.

Discussion

Since at present only file:// URLs are supported, there is no difference between this method andwriteToFile:atomically:, except for the type of the first argument.

Availability

• Available in OS X v10.0 and later.

See Also

• – writeToFile:atomically:

Related Sample Code

• AnimatedTableView

Declared In

NSData.h

writeToURL:options:error:

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

- (BOOL)writeToURL:(NSURL *)aURL options:(NSDataWritingOptions)mask error:(NSError **)errorPtr

Parameters

aURL

The location to which to write the receiver's bytes.

mask

A mask that specifies options for writing the data. Constant components are described in“NSDataWritingOptions”.

errorPtr

If there is an error writing out the data, upon return contains anNSError object that describes the problem.

Return Value

YES if the operation succeeds, otherwise NO.

Discussion

Since at present only file:// URLs are supported, there is no difference between this method andwriteToFile:options:error:, except for the type of the first argument.

Availability

• Available in OS X v10.4 and later.

See Also

• – writeToFile:options:error:

Related Sample Code

• Cache
• ClipboardViewer
• Sandboxing with NSXPCConnection

Declared In

NSData.h

Constants

NSDataReadingOptions

Options for methods used to read NSData objects.

enum {

   NSDataReadingMappedIfSafe = 1UL << 0,

   NSDataReadingUncached = 1UL << 1,

   NSDataReadingMappedAlways = 1UL << 3,

};

typedef NSUInteger NSDataReadingOptions;

Constants

NSDataReadingMappedIfSafe

A hint indicating the file should be mapped into virtual memory, if possible and safe.

Available in OS X v10.7 and later.

Declared in NSData.h.

NSDataReadingUncached

A hint indicating the file should not be stored in the file-system caches.

For data being read once and discarded, this option can improve performance.

Available in OS X v10.6 and later.

Declared in NSData.h.

NSDataReadingMappedAlways

Hint to map the file in if possible.

This takes precedence over NSDataReadingMappedIfSafe if both are given.

Available in OS X v10.7 and later.

Declared in NSData.h.

NSDataBase64EncodingOptions

Options for methods used to Base-64 encode data.

enum {

   NSDataBase64Encoding64CharacterLineLength = 1UL << 0,

   NSDataBase64Encoding76CharacterLineLength = 1UL << 1,

   NSDataBase64EncodingEndLineWithCarriageReturn = 1UL << 4,

   NSDataBase64EncodingEndLineWithLineFeed = 1UL << 5,

};

typedef NSUInteger NSDataBase64EncodingOptions;

Constants

NSDataBase64Encoding64CharacterLineLength

Set the maximum line length to 64 characters, after which a line ending is inserted.

Available in OS X v10.9 and later.

Declared in NSData.h.

NSDataBase64Encoding76CharacterLineLength

Set the maximum line length to 76 characters, after which a line ending is inserted.

Available in OS X v10.9 and later.

Declared in NSData.h.

NSDataBase64EncodingEndLineWithCarriageReturn

When a maximum line length is set, specify that the line ending to insert should include a carriage return.

Available in OS X v10.9 and later.

Declared in NSData.h.

NSDataBase64EncodingEndLineWithLineFeed

When a maximum line length is set, specify that the line ending to insert should include a line feed.

Available in OS X v10.9 and later.

Declared in NSData.h.

NSDataBase64DecodingOptions

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

enum {

   NSDataBase64DecodingIgnoreUnknownCharacters = 1UL << 0

};

typedef NSUInteger NSDataBase64DecodingOptions;

Constants

NSDataBase64DecodingIgnoreUnknownCharacters

Modify the decoding algorithm so that it ignores unknown non-Base-64 bytes, including line ending characters.

Available in OS X v10.9 and later.

Declared in NSData.h.

Legacy Reading Options

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

enum {

   NSDataReadingMapped = NSDataReadingMappedIfSafe,

   NSMappedRead = NSDataReadingMapped,

   NSUncachedRead = NSDataReadingUncached

};

Constants

NSDataReadingMapped

Deprecated name for NSDataReadingMappedIfSafe.

Available in OS X v10.6 and later.

Declared in NSData.h.

NSMappedRead

Deprecated name for NSDataReadingMapped.

Available in OS X v10.4 and later.

Declared in NSData.h.

NSUncachedRead

Deprecated name for NSDataReadingUncached.

Available in OS X v10.4 and later.

Declared in NSData.h.

NSDataWritingOptions

Options for methods used to write NSData objects.

enum {

   NSDataWritingAtomic = 1UL << 0,

   NSDataWritingWithoutOverwriting = 1UL << 1,

};

typedef NSUInteger NSDataWritingOptions;

Constants

NSDataWritingAtomic

A hint to write data to an auxiliary file first and then exchange the files. This option is equivalent to using a write method taking the parameteratomically:YES.

Available in OS X v10.6 and later.

Declared in NSData.h.

NSDataWritingWithoutOverwriting

Hint to return prevent overwriting an existing file. Cannot be combined withNSDataWritingAtomic.

Available in OS X v10.8 and later.

Declared in NSData.h.

Legacy Writing Options

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

enum {

   NSAtomicWrite = NSDataWritingAtomic

};

Constants

NSAtomicWrite

Deprecated name for NSDataWritingAtomic.

Available in OS X v10.4 and later.

Declared in NSData.h.

NSDataSearchOptions

Options for method used to search NSData objects. These options are used with therangeOfData:options:range: method.

enum {

   NSDataSearchBackwards = 1UL << 0,

   NSDataSearchAnchored = 1UL << 1

};

typedef NSUInteger NSDataSearchOptions;

Constants

NSDataSearchBackwards

Search from the end of NSData object.

Available in OS X v10.6 and later.

Declared in NSData.h.

NSDataSearchAnchored

Search is limited to start (or end, if NSDataSearchBackwards) ofNSData object.

This option performs searching only on bytes at the beginning or end of the range. No match at the beginning or end means nothing is found, even if a matching sequence of bytes occurs elsewhere in the data object.

Available in OS X v10.6 and later.

Declared in NSData.h.

Next

Copyright © 2013 Apple Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2013-09-18

Provide Feedback