NSData Class Reference
| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/Foundation.framework |
| Availability | Available in iOS 2.0 and later. |
| Declared in | NSData.h |
| Companion guides | |
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 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, 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: -
– initWithBytes:length: -
– initWithBytesNoCopy:length: -
– initWithBytesNoCopy:length:freeWhenDone: -
– initWithContentsOfFile: -
– initWithContentsOfFile:options:error: -
– initWithContentsOfURL: -
– initWithContentsOfURL:options:error: -
– initWithData: -
+ dataWithContentsOfMappedFile:Deprecated in iOS 5.0 -
– initWithContentsOfMappedFile:Deprecated in iOS 5.0
Accessing Data
-
– bytes -
– description -
– getBytes:length: -
– getBytes:range: -
– subdataWithRange: -
– rangeOfData:options:range: -
– getBytes:Deprecated in iOS 4.0
Testing Data
Storing Data
Class Methods
data
Creates and returns an empty data object.
Return Value
An empty data object.
Discussion
This method is declared primarily for the use of mutable subclasses of NSData.
Availability
- Available in iOS 2.0 and later.
Declared In
NSData.hdataWithBytes:length:
Creates and returns a data object containing a given number of bytes copied from a given buffer.
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. Returns nil if the data object could not be created.
Availability
- Available in iOS 2.0 and later.
Declared In
NSData.hdataWithBytesNoCopy:length:
Creates and returns a data object that holds length bytes from the buffer bytes.
Parameters
- bytes
A buffer containing data for the new object. bytes must point to a memory block allocated with
malloc.- 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. Returns nil 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 with malloc.
Availability
- Available in iOS 2.0 and later.
Declared In
NSData.hdataWithBytesNoCopy:length:freeWhenDone:
Creates and returns a data object that holds a given number of bytes from a given buffer.
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. Returns nil if the data object could not be created.
Availability
- Available in iOS 2.0 and later.
Declared In
NSData.hdataWithContentsOfFile:
Creates and returns a data object by reading every byte from the file specified by a given 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. Returns nil 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, use dataWithContentsOfFile:options:error:.
A sample using this method can be found in “Working With Binary Data”.
Availability
- Available in iOS 2.0 and later.
Declared In
NSData.hdataWithContentsOfFile:options:error:
Creates and returns a data object by reading every byte from the file specified by a given path.
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
NSErrorobject that describes the problem.
Return Value
A data object by reading every byte from the file specified by path. Returns nil if the data object could not be created.
Availability
- Available in iOS 2.0 and later.
Declared In
NSData.hdataWithContentsOfURL:
Returns a data object containing the data from the location specified by a given URL.
Parameters
- aURL
The URL from which to read data.
Return Value
A data object containing the data from the location specified by aURL. Returns nil 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 iOS 2.0 and later.
Declared In
NSData.hdataWithContentsOfURL:options:error:
Creates and returns a data object containing the data from the location specified by aURL.
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
NSErrorobject that describes the problem.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSData.hdataWithData:
Creates and returns a data object containing the contents of another data object.
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 iOS 2.0 and later.
See Also
Declared In
NSData.hInstance Methods
bytes
Returns a pointer to the receiver’s contents.
Return Value
A read-only pointer to the receiver’s contents.
Discussion
If the length of the receiver is 0, this method returns nil.
Availability
- Available in iOS 2.0 and later.
Declared In
NSData.hdescription
Returns an NSString object that contains a hexadecimal representation of the receiver’s contents.
Return Value
An NSString object that contains a hexadecimal representation of the receiver’s contents in NSData property list format.
Availability
- Available in iOS 2.0 and later.
Declared In
NSData.hgetBytes:length:
Copies a number of bytes from the start of the receiver's data into a given buffer.
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 the length of the data encapsulated in the object.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSData.hgetBytes:range:
Copies a range of bytes from the receiver’s data into a given buffer.
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 iOS 2.0 and later.
Declared In
NSData.hinitWithBytes:length:
Returns a data object initialized by adding to it a given number of bytes of data copied from a given buffer.
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 iOS 2.0 and later.
See Also
Declared In
NSData.hinitWithBytesNoCopy:length:
Returns a data object initialized by adding to it a given number of bytes of data from a given buffer.
Parameters
- bytes
A buffer containing data for the new object. bytes must point to a memory block allocated with
malloc.- 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 with malloc.
Availability
- Available in iOS 2.0 and later.
Declared In
NSData.hinitWithBytesNoCopy:length:freeWhenDone:
Initializes a newly allocated data object by adding to it length bytes of data from the buffer bytes.
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 iOS 2.0 and later.
See Also
Declared In
NSData.hinitWithContentsOfFile:
Returns a data object initialized by reading into it the data from the file specified by a given 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 iOS 2.0 and later.
Declared In
NSData.hinitWithContentsOfFile:options:error:
Returns a data object initialized by reading into it the data from the file specified by a given path.
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
NSErrorobject 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 iOS 2.0 and later.
Declared In
NSData.hinitWithContentsOfURL:
Initializes a newly allocated data object initialized with the data from the location specified by 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 iOS 2.0 and later.
See Also
Declared In
NSData.hinitWithContentsOfURL:options:error:
Returns a data object initialized with the data from the location specified by a given URL.
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
NSErrorobject 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 iOS 2.0 and later.
Declared In
NSData.hinitWithData:
Returns a data object initialized with the contents of another data object.
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 iOS 2.0 and later.
See Also
Declared In
NSData.hisEqualToData:
Compares the receiving data object to 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, otherwise NO.
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 iOS 2.0 and later.
Declared In
NSData.hlength
Returns the number of bytes contained in the receiver.
Return Value
The number of bytes contained in the receiver.
Availability
- Available in iOS 2.0 and later.
Declared In
NSData.hrangeOfData:options:range:
Finds and returns the range of the first occurrence of the given data, within the given range, subject to given options.
Parameters
- dataToFind
The data for which to search. This value must not be
nil.Important: Raises an
NSInvalidArgumentExceptionif dataToFind isnil.- mask
A mask specifying search options. The “NSDataSearchOptions” options may be specified singly or by combining them with the C bitwise
ORoperator.- searchRange
The range within the receiver in which to search for dataToFind. If this range is not within the receiver’s range of bytes, an
NSRangeExceptionraised.
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 iOS 4.0 and later.
Declared In
NSData.hsubdataWithRange:
Returns a data object containing the receiver’s bytes that fall within the limits specified by a given 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, raises NSRangeException.
Discussion
A sample using this method can be found in “Working With Binary Data”.
Availability
- Available in iOS 2.0 and later.
Declared In
NSData.hwriteToFile:atomically:
Writes the bytes in the receiver to the file specified by a given path.
Parameters
- path
The location to which to write the receiver's bytes. If path contains a tilde (~) character, you must expand it with
stringByExpandingTildeInPathbefore 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 iOS 2.0 and later.
See Also
Declared In
NSData.hwriteToFile:options:error:
Writes the bytes in the receiver to the file specified by a given path.
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 an
NSErrorobject that describes the problem.
Return Value
YES if the operation succeeds, otherwise NO.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSData.hwriteToURL:atomically:
Writes the bytes in the receiver to the location specified by aURL.
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 and writeToFile:atomically:, except for the type of the first argument.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSData.hwriteToURL:options:error:
Writes the bytes in the receiver to the location specified by a given URL.
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 an
NSErrorobject 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 and writeToFile:options:error:, except for the type of the first argument.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSData.hConstants
NSDataReadingOptions
Options for methods used to read NSData objects.
enum {
NSDataReadingMappedIfSafe = 1UL << 0,
NSDataReadingUncached = 1UL << 1,
NSDataReadingMappedAlways = 1UL << 3,
};
typedef NSUInteger NSDataReadingOptions;
Constants
NSDataReadingMappedIfSafeA hint indicating the file should be mapped into virtual memory, if possible and safe.
Available in iOS 5.0 and later.
Declared in
NSData.h.NSDataReadingUncachedA 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 iOS 4.0 and later.
Declared in
NSData.h.NSDataReadingMappedAlwaysHint to map the file in if possible.
This takes precedence over
NSDataReadingMappedIfSafeif both are given.Available in iOS 5.0 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
NSDataReadingMappedDeprecated name for
NSDataReadingMappedIfSafe.Available in iOS 4.0 and later.
Declared in
NSData.h.NSMappedReadDeprecated name for
NSDataReadingMapped.Available in iOS 2.0 and later.
Declared in
NSData.h.NSUncachedReadDeprecated name for
NSDataReadingUncached.Available in iOS 2.0 and later.
Declared in
NSData.h.
NSDataWritingOptions
Options for methods used to write NSData objects.
enum {
NSDataWritingAtomic = 1UL << 0,
NSDataWritingWithoutOverwriting = 1UL << 1,
NSDataWritingFileProtectionNone = 0x10000000,
NSDataWritingFileProtectionComplete = 0x20000000,
NSDataWritingFileProtectionCompleteUnlessOpen = 0x30000000,
NSDataWritingFileProtectionCompleteUntilFirstUserAuthentication = 0x40000000,
NSDataWritingFileProtectionMask = 0xf0000000,
};
typedef NSUInteger NSDataWritingOptions;
Constants
NSDataWritingAtomicA 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 parameter
atomically:YES.Available in iOS 4.0 and later.
Declared in
NSData.h.NSDataWritingWithoutOverwritingHint to return prevent overwriting an existing file. Cannot be combined with
NSDataWritingAtomic.Available in iOS 6.0 and later.
Declared in
NSData.h.NSDataWritingFileProtectionNoneA hint to set the content protection attribute of the file when writing it out. In this case, the file is not stored in an encrypted format and may be accessed at boot time and while the device is unlocked.
Available in iOS 4.0 and later.
Declared in
NSData.h.NSDataWritingFileProtectionCompleteA hint to set the content protection attribute of the file when writing it out. In this case, the file is stored in an encrypted format and may be read from or written to only while the device is unlocked. At all other times, attempts to read and write the file result in failure.
Available in iOS 4.0 and later.
Declared in
NSData.h.NSDataWritingFileProtectionCompleteUnlessOpenA hint to set the content protection attribute of the file when writing it out. In this case, the file cannot be opened for reading or writing when the device is locked, although new files can be created with this class. If one of these files is open when the device is locked, reading and writing are still allowed.
Available in iOS 5.0 and later.
Declared in
NSData.h.NSDataWritingFileProtectionCompleteUntilFirstUserAuthenticationA hint to set the content protection attribute of the file when writing it out. In this case, the file can be read or written to while the device is locked, but while it is booting up, they have protection equivalent to
NSDataWritingFileProtectionComplete.Available in iOS 5.0 and later.
Declared in
NSData.h.NSDataWritingFileProtectionMaskA mask to use when determining the file protection options assigned to the data.
Available in iOS 4.0 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
NSAtomicWriteDeprecated name for
NSDataWritingAtomic.Available in iOS 2.0 and later.
Declared in
NSData.h.
NSDataSearchOptions
Options for method used to search NSData objects. These options are used with the rangeOfData:options:range: method.
enum {
NSDataSearchBackwards = 1UL << 0,
NSDataSearchAnchored = 1UL << 1
};
typedef NSUInteger NSDataSearchOptions;
Constants
NSDataSearchBackwardsSearch from the end of
NSDataobject.Available in iOS 4.0 and later.
Declared in
NSData.h.NSDataSearchAnchoredSearch is limited to start (or end, if
NSDataSearchBackwards) ofNSDataobject.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 iOS 4.0 and later.
Declared in
NSData.h.
© 2012 Apple Inc. All Rights Reserved. (Last updated: 2012-07-17)