NSData

Inherits From: NSObject

Conforms To: NSCoding, NSCopying, NSMutableCopying NSObject (NSObject)

Declared In: Foundation/NSData.h

Class Description

The NSData class declares the programmatic interface to objects that contain data in the form of bytes. NSData objects hold a static collection of bytes; NSData's subclass, NSMutableData, defines objects that hold modifiable data. These two classes provide an object-oriented approach to memory allocation, a facility that in procedural programming is accessed through functions like malloc(). Furthermore, these classes take advantage of operating system primitives when allocating large blocks of memory.

NSData's two primitive methodsbytes and lengthprovide the basis for all the other methods in its interface. The bytes method returns a pointer to the bytes contained in the data object. length returns the number of bytes contained in the data object.

NSData and NSMutableData objects are commonly used to hold the contents of a file. The methods dataWithContentsOfFile: and dataWithContentsOfMappedFile: return objects that represent a file's contents. The writeToFile:atomically: method enables you to write the contents of a data object to a file.

NSData provides access methods for copying bytes from a data object into a buffer. Use getBytes: to copy the entire contents of the object or getBytes:length: to copy a subset, starting with the first byte. getBytes:range: copies a range of bytes from a starting point within the bytes themselves. You can also return a data object that contains a subset of the bytes in another data object by using the subdataWithRange: method. Or, you can use the description method to return an NSString representation of the bytes in a data object.

For determining if two data objects are equal, NSData provides the isEqualToData: method, which does a byte-for-byte comparison.

Allocating and Initializing an NSData Object

• + (id)allocWithZone:(NSZone *)zone Creates and returns an uninitialized object from zone.
• + (id)data Creates and returns an empty object. This method is declared primarily for mutable subclasses of NSData.
• + (id)dataWithBytes:(const void *)bytes Creates and returns an object containing length bytes length:(unsigned int)length of data copied from the buffer bytes.
• + (id)dataWithBytesNoCopy:(void *)bytes Creates and returns an object containing length bytes length:(unsigned int)length from the buffer bytes.
• + (id)dataWithContentsOfFile:(NSString *)path Creates and returns an object by reading data from the file specified by path.
• + (id)dataWithContentsOfMappedFile:(NSString *)path Creates and returns an object whose contents come from the mapped file path, assuming mapped files are available on the underlying operating system. If mapped files are not available, this method is identical to dataWithContentsOfFile:.
• - (id)initWithBytes:(const void *)bytes Initializes a newly allocated NSData object by putting in it length:(unsigned int)length length bytes of data copied from the buffer bytes.
• - (id)initWithBytesNoCopy:(void *)bytes Initializes a newly allocated NSData object by putting in it length:(unsigned int)length length bytes of data from the buffer bytes.
• - (id)initWithContentsOfFile:(NSString *)path Initializes a newly allocated NSData object by reading into it the data from the file specified by path.
• - (id)initWithContentsOfMappedFile:(NSString *)path Initializes a newly allocated NSData object to contain the data residing in the mapped file path, assuming mapped files are available on the underlying operating system. If mapped files are not available, this method is identical to initWithContentsOfFile:.
• - (id)initWithData:(NSData *)data Initializes a newly allocated NSData object by placing in it the contents of another NSData object, data.

• - (const void *)bytes Returns a pointer to the object's contents. This method returns read-only access to the data.
• - (NSString *)description Returns an NSString object that contains a hexadecimal representation of the the receiver's contents.
• - (void)getBytes:(void *)buffer Copies the receiver's contents into buffer.
• - (void)getBytes:(void *)buffer Copies length bytes of the receiver's contents into buffer. length:(unsigned int)length
• - (void)getBytes:(void *)buffer Copies into buffer the portion of the receiver's contents range:(NSRange)aRange within aRange. Raises an NSRangeException if aRange is not within the range of the receiver's data.
• - (NSData *)subdataWithRange:(NSRange)aRange Returns an object containing a copy of the receiver's bytes that fall within the limits specified by aRange. Raises an NSRangeException if aRange is not within the range of the receiver's data.

• - (BOOL)isEqualToData:(NSData *)other Compares the receiving object to other. If the contents of other are equal to the contents of the receiver, this method returns YES. If not, it returns NO.
• - (unsigned int)length Returns the number of bytes contained in the receiver.

• - (BOOL)writeToFile:(NSString *)path Writes the bytes in the receiving object to the file specified atomically:(BOOL)useAuxiliaryFile by path. If useAuxiliaryFile is YES, the data is written to a backup file and then, assuming no errors occur, the backup file is renamed atomically to the intended file name.

• - (unsigned int)deserializeAlignedBytesLengthAtCursor:(unsigned int*)cursor Returns the length of the serialized bytes at the location referenced by cursor. If the bytes have been page-aligned, it also obtains the relevant hole information and adjusts the cursor. An invocation of this method must have a corresponding serializeAlignedBytesLength: invocation.
• - (void)deserializeBytes:(void *)buffer Deserializes bytes number of bytes in the buffer pointed length:(unsigned int)bytes at by buffer, places them internally starting at cursor, atCursor:(unsigned int*)cursor and advances the cursor.
• - (void)deserializeDataAt:(void *)data Deserializes the data pointed at by cursor, interpreting it ofObjCType:(const char *)type by the Objective C type specifier type and writing it atCursor:(unsigned int*)cursor to the memory location referenced by data. If the data context:(id <NSObjCTypeSerializationCallBack>) element is an object other than an instance of callback NSDictionary, NSArray, NSString, or NSData, a callback from object callback can provide further definition of the object. All Objective C types are currently supported except union and void *. Pointers refer to a single item.
• - (int)deserializeIntAtCursor:(unsigned int*)cursor Deserializes and returns the integer encoded at cursor. Also advances the cursor.
• - (int)deserializeIntAtIndex:(unsigned int)index Deserializes and returns the integer encoded at offset index. Does not advance the cursor.
• - (void)deserializeInts:(int *)intBuffer Deserializes numInts integers encoded at the location count:(unsigned int)numInts referenced by cursor and puts them in the buffer atCursor:(unsigned int*)cursor intBuffer. Also advances the cursor.
• - (void)deserializeInts:(int *)intBuffer Deserializes numInts integers encoded at offset index count:(unsigned int)numInts and puts them in the buffer intBuffer. Does not advance atIndex:(unsigned int)index the cursor.