Copyright ã1994 by NeXT Computer, Inc.  All Rights Reserved.

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 methodsÐbytes and lengthÐprovide 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.

Accessing 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.

Querying a Data Object

- (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.

Storing Data

- (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.

Deserializing Data

- (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.