| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/Foundation.framework |
| Availability | Available in Mac OS X v10.0 and later. |
| Declared in | NSData.h |
| Companion guides | |
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.
Using 32-bit Cocoa, the size of the data is subject to a theoretical 2GB limit (in practice, because memory will be used by other objects this limit will be smaller); using 64-bit Cocoa, the size of the data is subject to a theoretical limit of about 8EB (in practice, the limit should not be a factor).
NSData is “toll-free bridged” with its Core Foundation counterpart, CFData Reference. This means that the Core Foundation type is interchangeable in function or method calls with the bridged Foundation object. Therefore, in a method where you see an NSData * parameter, you can pass a CFDataRef, and in a function where you see a CFDataRef parameter, you can pass an NSData instance (you cast one type to the other to suppress compiler warnings). This also applies to your concrete subclasses of NSData. See Interchangeable Data Types for more information on toll-free bridging.
+ data
+ dataWithBytes:length:
+ dataWithBytesNoCopy:length:
+ dataWithBytesNoCopy:length:freeWhenDone:
+ dataWithContentsOfFile:
+ dataWithContentsOfFile:options:error:
+ dataWithContentsOfMappedFile:
+ dataWithContentsOfURL:
+ dataWithContentsOfURL:options:error:
+ dataWithData:
– initWithBytes:length:
– initWithBytesNoCopy:length:
– initWithBytesNoCopy:length:freeWhenDone:
– initWithContentsOfFile:
– initWithContentsOfFile:options:error:
– initWithContentsOfMappedFile:
– initWithContentsOfURL:
– initWithContentsOfURL:options:error:
– initWithData:
– bytes
– description
– getBytes:length:
– getBytes:range:
– subdataWithRange:
– rangeOfData:options:range:
– getBytes: Deprecated in Mac OS X v10.6
Creates and returns an empty data object.
+ (id)data
An empty data object.
This method is declared primarily for the use of mutable subclasses of NSData.
NSData.hCreates and returns a data object containing a given number of bytes copied from a given buffer.
+ (id)dataWithBytes:(const void *)bytes length:(NSUInteger)length
A buffer containing data for the new object.
The number of bytes to copy from bytes. This value must not exceed the length of bytes.
A data object containing length bytes copied from the buffer bytes. Returns nil if the data object could not be created.
NSData.hCreates and returns a data object that holds length bytes from the buffer bytes.
+ (id)dataWithBytesNoCopy:(void *)bytes length:(NSUInteger)length
A buffer containing data for the new object. bytes must point to a memory block allocated with malloc.
The number of bytes to hold from bytes. This value must not exceed the length of bytes.
A data object that holds length bytes from the buffer bytes. Returns nil if the data object could not be created.
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.
NSData.hCreates 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
A buffer containing data for the new object. If freeWhenDone is YES, bytes must point to a memory block allocated with malloc.
The number of bytes to hold from bytes. This value must not exceed the length of bytes.
If YES, the returned object takes ownership of the bytes pointer and frees it on deallocation.
A data object that holds length bytes from the buffer bytes. Returns nil if the data object could not be created.
NSData.hCreates and returns a data object by reading every byte from the file specified by a given path.
+ (id)dataWithContentsOfFile:(NSString *)path
The absolute path of the file from which to read data.
A data object by reading every byte from the file specified by path. Returns nil if the data object could not be created.
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”.
NSData.hCreates 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
The absolute path of the file from which to read data.
A mask that specifies options for reading the data. Constant components are described in “NSDataReadingOptions”.
If an error occurs, upon return contains an NSError object that describes the problem.
A data object by reading every byte from the file specified by path. Returns nil if the data object could not be created.
NSData.hCreates and returns a data object from the mapped file specified by path.
+ (id)dataWithContentsOfMappedFile:(NSString *)path
The absolute path of the file from which to read data.
A data object from the mapped file specified by path. Returns nil if the data object could not be created.
Because of file mapping restrictions, this method should only be used if the file is guaranteed to exist for the duration of the data object’s existence. It is generally safer to use the dataWithContentsOfFile: method.
This methods assumes mapped files are available from the underlying operating system. A mapped file uses virtual memory techniques to avoid copying pages of the file into memory until they are actually needed.
NSData.hReturns a data object containing the data from the location specified by a given URL.
+ (id)dataWithContentsOfURL:(NSURL *)aURL
The URL from which to read data.
A data object containing the data from the location specified by aURL. Returns nil if the data object could not be created.
If you need to know what was the reason for failure, use dataWithContentsOfURL:options:error:.
NSData.hCreates and returns a data object containing the data from the location specified by aURL.
+ (id)dataWithContentsOfURL:(NSURL *)aURL options:(NSDataReadingOptions)mask error:(NSError **)errorPtr
The URL from which to read data.
A mask that specifies options for reading the data. Constant components are described in “NSDataReadingOptions”.
If there is an error reading in the data, upon return contains an NSError object that describes the problem.
NSData.hCreates and returns a data object containing the contents of another data object.
+ (id)dataWithData:(NSData *)aData
A data object.
A data object containing the contents of aData. Returns nil if the data object could not be created.
NSData.hReturns a pointer to the receiver’s contents.
- (const void *)bytes
A read-only pointer to the receiver’s contents.
If the length of the receiver is 0, this method returns nil.
NSData.hReturns an NSString object that contains a hexadecimal representation of the receiver’s contents.
- (NSString *)description
An NSString object that contains a hexadecimal representation of the receiver’s contents in NSData property list format.
NSData.hCopies a number of bytes from the start of the receiver's data into a given buffer.
- (void)getBytes:(void *)buffer length:(NSUInteger)length
A buffer into which to copy data.
The number of bytes from the start of the receiver's data to copy to buffer.
The number of bytes copied is the smaller of the length parameter and the length of the data encapsulated in the object.
NSData.hCopies a range of bytes from the receiver’s data into a given buffer.
- (void)getBytes:(void *)buffer range:(NSRange)range
A buffer into which to copy data.
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.
If range isn’t within the receiver’s range of bytes, an NSRangeException is raised.
NSData.hReturns 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
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.
NSData.hReturns 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
A buffer containing data for the new object. bytes must point to a memory block allocated with malloc.
The number of bytes to hold from bytes. This value must not exceed the length of bytes.
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.
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.
NSData.hInitializes 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
A buffer containing data for the new object. If flag is YES, bytes must point to a memory block allocated with malloc.
The number of bytes to hold from bytes. This value must not exceed the length of bytes.
If YES, the returned object takes ownership of the bytes pointer and frees it on deallocation.
NSData.hReturns a data object initialized by reading into it the data from the file specified by a given path.
- (id)initWithContentsOfFile:(NSString *)path
The absolute path of the file from which to read data.
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.
This method is equivalent to initWithContentsOfFile:options:error: with no options.
NSData.hReturns 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
The absolute path of the file from which to read data.
A mask that specifies options for reading the data. Constant components are described in “NSDataReadingOptions”.
If an error occurs, upon return contains an NSError object that describes the problem.
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.
NSData.hReturns a data object initialized by reading into it the mapped file specified by a given path.
- (id)initWithContentsOfMappedFile:(NSString *)path
The absolute path of the file from which to read data.
A data object initialized by reading into it the mapped file specified by path. The returned object might be different than the original receiver.
NSData.hInitializes a newly allocated data object initialized with the data from the location specified by aURL.
- (id)initWithContentsOfURL:(NSURL *)aURL
The URL from which to read data
An NSData object initialized with the data from the location specified by aURL. The returned object might be different than the original receiver.
NSData.hReturns 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
The URL from which to read data.
A mask that specifies options for reading the data. Constant components are described in “NSDataReadingOptions”.
If there is an error reading in the data, upon return contains an NSError object that describes the problem.
A data object initialized with the data from the location specified by aURL. The returned object might be different than the original receiver.
NSData.hReturns a data object initialized with the contents of another data object.
- (id)initWithData:(NSData *)data
A data object.
A data object initialized with the contents data. The returned object might be different than the original receiver.
NSData.hCompares the receiving data object to otherData.
- (BOOL)isEqualToData:(NSData *)otherData
The data object with which to compare the receiver.
YES if the contents of otherData are equal to the contents of the receiver, otherwise NO.
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.
NSData.hReturns the number of bytes contained in the receiver.
- (NSUInteger)length
The number of bytes contained in the receiver.
NSData.hFinds 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
The data for which to search. This value must not be nil.
Important: Raises an NSInvalidArgumentException if dataToFind is nil.
A mask specifying search options. The “NSDataSearchOptions” options may be specified singly or by combining them with the C bitwise OR operator.
The range within the receiver in which to search for dataToFind. If this range is not within the receiver’s range of bytes, an NSRangeException raised.
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 (@"").
NSData.hReturns a data object containing a copy of the receiver’s bytes that fall within the limits specified by a given range.
- (NSData *)subdataWithRange:(NSRange)range
The range in the receiver from which to copy bytes. The range must not exceed the bounds of the receiver.
A data object containing a copy of the receiver’s bytes that fall within the limits specified by range.
If range isn’t within the receiver’s range of bytes, an NSRangeException is raised.
A sample using this method can be found in “Working With Binary Data”.
NSData.hWrites the bytes in the receiver to the file specified by a given path.
- (BOOL)writeToFile:(NSString *)path atomically:(BOOL)flag
The location to which to write the receiver's bytes. If path contains a tilde (~) character, you must expand it with stringByExpandingTildeInPath before invoking this method.
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.
YES if the operation succeeds, otherwise NO.
NSData.hWrites the bytes in the receiver to the file specified by a given path.
- (BOOL)writeToFile:(NSString *)path options:(NSDataWritingOptions)mask error:(NSError **)errorPtr
The location to which to write the receiver's bytes.
A mask that specifies options for writing the data. Constant components are described in “NSDataWritingOptions”.
If there is an error writing out the data, upon return contains an NSError object that describes the problem.
YES if the operation succeeds, otherwise NO.
NSData.hWrites the bytes in the receiver to the location specified by aURL.
- (BOOL)writeToURL:(NSURL *)aURL atomically:(BOOL)atomically
The location to which to write the receiver's bytes. Only file:// URLs are supported.
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.
YES if the operation succeeds, otherwise NO.
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.
NSData.hWrites the bytes in the receiver to the location specified by a given URL.
- (BOOL)writeToURL:(NSURL *)aURL options:(NSDataWritingOptions)mask error:(NSError **)errorPtr
The location to which to write the receiver's bytes.
A mask that specifies options for writing the data. Constant components are described in “NSDataWritingOptions”.
If there is an error writing out the data, upon return contains an NSError object that describes the problem.
YES if the operation succeeds, otherwise NO.
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.
NSData.hOptions for methods used to read NSData objects.
enum {
NSDataReadingMapped = 1UL << 0,
NSDataReadingUncached = 1UL << 1
NSMappedRead = NSDataReadingMapped,
NSUncachedRead = NSDataReadingUncached
};
typedef NSUInteger NSDataReadingOptions;
NSDataReadingMappedA hint indicating the file should be mapped into virtual memory, if possible.
Available in Mac OS X v10.6 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 Mac OS X v10.6 and later.
Declared in NSData.h.
NSMappedReadDeprecated name for NSDataReadingMapped. (Deprecated. Please use NSDataReadingMapped instead.)
Available in Mac OS X v10.4 and later.
Declared in NSData.h.
NSUncachedReadDeprecated name for NSDataReadingUncached. (Deprecated. Please use NSDataReadingUncached instead.)
Available in Mac OS X v10.4 and later.
Declared in NSData.h.
Options for methods used to write NSData objects.
enum {
NSDataWritingAtomic = 1UL << 0
NSAtomicWrite = NSDataWritingAtomic
};
typedef NSUInteger NSDataWritingOptions;
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 Mac OS X v10.6 and later.
Declared in NSData.h.
NSAtomicWriteDeprecated constant. (Deprecated. Use NSDataWritingAtomic instead.)
Available in Mac OS X v10.4 and later.
Declared in NSData.h.
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;
NSDataSearchBackwardsSearch from the end of NSData object.
Available in Mac OS X v10.6 and later.
Declared in NSData.h.
NSDataSearchAnchoredSearch is limited to start (or end, if NSDataSearchBackwards) of NSData 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 Mac OS X v10.6 and later.
Declared in NSData.h.
Last updated: 2010-05-11