# NSData class reference

mccallum@gnu.ai.mit.edu
richard@brainstorm.co.uk
34468
2012-01-09 01:28:27 -0700 (Mon, 09 Jan 2012)
1995, 1996, 1997, 2000, 2002 Free Software Foundation, Inc.
Software documentation for the NSData class
Foundation/NSData.h
NSCoding
NSCopying
NSMutableCopying

Class for storing a byte array. Methods for initializing from memory a file, or the network are provided, as well as the ability to write to a file or the network. If desired, object can take over management of a pre-allocated buffer (with malloc or similar), free'ing it when deallocated.

The data buffer at any given time has a capacity, which is the size of its allocated memory area, in bytes, and a length, which is the length of data it is currently storing.

data
Returns an empty data object.
dataWithBytes:
bytes
length:
length
Returns an autoreleased data object containing data copied from bytes and with the specified length. Invokes -initWithBytes:length:
dataWithBytesNoCopy:
bytes
length:
length
Returns an autoreleased data object encapsulating the data at bytes and with the specified length. Invokes -initWithBytesNoCopy:length:freeWhenDone: with `YES`
dataWithBytesNoCopy:
aBuffer
length:
bufferSize
freeWhenDone:
shouldFree
Returns an autoreleased data object encapsulating the data at bytes and with the specified length. Invokes -initWithBytesNoCopy:length:freeWhenDone:
dataWithContentsOfFile:
path
Returns a data object encapsulating the contents of the specified file. Invokes -initWithContentsOfFile:
dataWithContentsOfMappedFile:
path
Returns a data object encapsulating the contents of the specified file mapped directly into memory. Invokes -initWithContentsOfMappedFile:
dataWithContentsOfURL:
url
Retrieves the information at the specified url and returns an NSData instance encapsulating it.
dataWithData:
data
Returns an autoreleased instance initialised by copying the contents of data.
bytes
Returns a pointer to the data encapsulated by the receiver.
description
Returns a short description of this object.
deserializeAlignedBytesLengthAtCursor:
cursor
Copies data from buffer starting from cursor. Deprecated. Use [-getBytes:] and related methods instead.
deserializeBytes:
buffer
length:
bytes
atCursor:
cursor
Copies data from buffer starting from cursor. Deprecated. Use [-getBytes:] and related methods instead.
deserializeDataAt:
data
ofObjCType:
type
atCursor:
cursor
context:
callback
Description forthcoming.
deserializeIntAtCursor:
cursor
Retrieve an int from this data, which is assumed to be in network (big-endian) byte order. Cursor refers to byte position.
deserializeIntAtIndex:
index
Retrieve an int from this data, which is assumed to be in network (big-endian) byte order. Index refers to byte position.
deserializeInts:
intBuffer
count:
numInts
atCursor:
cursor
Retrieve ints from intBuffer, which is assumed to be in network (big-endian) byte order. Count refers to number of ints, but index refers to byte position.
deserializeInts:
intBuffer
count:
numInts
atIndex:
index
Retrieve ints from intBuffer, which is assumed to be in network (big-endian) byte order. Count refers to number of ints, but index refers to byte position.
getBytes:
buffer
Copies the contents of the memory encapsulated by the receiver into the specified buffer. The buffer must be large enough to contain -length bytes of data... if it isn't then a crash is likely to occur.
Invokes -getBytes:range: with the range set to the whole of the receiver.
getBytes:
buffer
length:
length
Copies length bytes of data from the memory encapsulated by the receiver into the specified buffer. The buffer must be large enough to contain length bytes of data... if it isn't then a crash is likely to occur.
If length is greater than the size of the receiver, only the available bytes are copied.
getBytes:
buffer
range:
aRange
Copies data from the memory encapsulated by the receiver (in the range specified by aRange) into the specified buffer.
The buffer must be large enough to contain the data... if it isn't then a crash is likely to occur.
If aRange specifies a range which does not entirely lie within the receiver, an exception is raised.
initWithBytes:
aBuffer
length:
bufferSize
Makes a copy of bufferSize bytes of data at aBuffer, and passes it to -initWithBytesNoCopy:length:freeWhenDone: with a `YES` argument in order to initialise the receiver. Returns the result.
initWithBytesNoCopy:
aBuffer
length:
bufferSize
Invokes -initWithBytesNoCopy:length:freeWhenDone: with the last argument set to `YES`. Returns the resulting initialised data object (which may not be the receiver).
initWithBytesNoCopy:
aBuffer
length:
bufferSize
freeWhenDone:
shouldFree
Initialises the receiver.
The value of aBuffer is a pointer to something to be stored.
The value of bufferSize is the number of bytes to use.
The value of shouldFree specifies whether the receiver should attempt to free the memory pointer to by aBuffer when the receiver is deallocated ... ie. it says whether the receiver owns the memory. Supplying the wrong value here will lead to memory leaks or crashes.
initWithContentsOfFile:
path
Initialises the receiver with the contents of the specified file.
Returns the resulting object.
Returns `nil` if the file does not exist or can not be read for some reason.
initWithContentsOfMappedFile:
path
Initialize with data pointing to contents of file at path. Bytes are only "swapped in" as needed. File should not be moved or deleted for the life of this object.
initWithContentsOfURL:
url
Initialize with data pointing to contents of URL, which will be retrieved immediately in a blocking manner.
initWithData:
data
Initializes by copying data's bytes into a new buffer.
isEqualToData:
other
Returns a boolean value indicating if the receiver and other contain identical data (using a byte by byte comparison). Assumes that the other object is an NSData instance... may raise an exception if it isn't.
length
Returns the number of bytes of data encapsulated by the receiver.
subdataWithRange:
aRange
Returns an NSData instance encapsulating the memory from the receiver specified by the range aRange.
If aRange specifies a range which does not entirely lie within the receiver, an exception is raised.
writeToFile:
path
atomically:
useAuxiliaryFile

Writes a copy of the data encapsulated by the receiver to a file at path. If the useAuxiliaryFile flag is `YES`, this writes to a temporary file and then renames that to the file at path, thus ensuring that path exists and does not contain partially written data at any point.

On success returns `YES`, on failure returns `NO`.

writeToFile:
path
options:
writeOptionsMask
error:
errorPtr

Writes a copy of the data encapsulated by the receiver to a file at path. If the NSAtomicWrite option is set, this writes to a temporary file and then renames that to the file at path, thus ensuring that path exists and does not contain partially written data at any point.

On success returns `YES`, on failure returns `NO`.

writeToURL:
anURL
atomically:
flag
Writes a copy of the contents of the receiver to the specified URL.
writeToURL:
url
options:
writeOptionsMask
error:
errorPtr
Writes a copy of the contents of the receiver to the specified URL.
Software documentation for the NSMutableData class
Foundation/NSData.h
Mutable version of NSData . Methods are provided for appending and replacing bytes in the buffer, which will be grown as needed.
dataWithCapacity:
numBytes
New instance with buffer of given numBytes with length of valid data set to zero. Note that capacity will be automatically increased as necessary.
dataWithLength:
length
New instance with buffer of capacity and valid data size equal to given length in bytes. The buffer contents are set to zero. The length of valid data is set to zero. Note that buffer will be automatically increased as necessary.
appendBytes:
aBuffer
length:
bufferSize
Appends bufferSize bytes from aBuffer to data, increasing capacity if necessary.
appendData:
other
Copies and appends data from other to data, increasing capacity if necessary.
increaseLengthBy:
extraLength
Increases buffer length by given number of bytes, filling the new space with zeros.
initWithCapacity:
capacity
Initialize with buffer capable of holding size bytes. The length of valid data is initially set to zero.
initWithLength:
length
Initialize with buffer of capacity equal to length, and with the length of valid data set to length. Data is set to zero.
mutableBytes

Returns a pointer to the data storage of the receiver.
Modifications to the memory pointed to by this pointer will change the contents of the object. It is important that your code should not try to modify the memory beyond the number of bytes given by the `-length` method.

NB. if the object is released, or any method that changes its size or content is called, then the pointer previously returned by this method may cease to be valid.

This is a 'primitive' method... you need to implement it if you write a subclass of NSMutableData.

replaceBytesInRange:
aRange
withBytes:
bytes
Replaces the bytes of data in the specified range with a copy of the new bytes supplied.
If the location of the range specified lies beyond the end of the data ( `[self length] < range.location`) then a range exception is raised.
Otherwise, if the range specified extends beyond the end of the data, then the size of the data is increased to accommodate the new bytes.
replaceBytesInRange:
aRange
withBytes:
bytes
length:
length
Replace the content of the receiver which lies in aRange with the specified length of data from the buffer pointed to by bytes.
The size of the receiver is adjusted to allow for the change.
resetBytesInRange:
aRange
Set bytes in aRange to 0.
serializeAlignedBytesLength:
length
Does not act as the name suggests. Instead, serializes length itself as an int into buffer.
serializeDataAt:
data
ofObjCType:
type
context:
callback
Description forthcoming.
serializeInt:
value
Serialize an int into this object's data buffer, swapping it to network (big-endian) byte order first.
serializeInt:
value
atIndex:
index
Serialize an int into this object's data buffer at index (replacing anything there currently), swapping it to network (big-endian) byte order first.
serializeInts:
intBuffer
count:
numInts
Serialize one or more ints into this object's data buffer, swapping them to network (big-endian) byte order first.
serializeInts:
intBuffer
count:
numInts
atIndex:
index
Serialize one or more ints into this object's data buffer at index (replacing anything there currently), swapping them to network (big-endian) byte order first.
setData:
data
Replaces contents of buffer with contents of data's buffer, increasing or shrinking capacity to match.
setLength:
size

Sets the length of the NSMutableData object. If the length is increased, the newly allocated data area is filled with zero bytes.

This is a 'primitive' method... you need to implement it if you write a subclass of NSMutableData.

Software documentation for the NSData(GNUstepExtensions) category
Foundation/NSData.h
Provides some shared-memory extensions to NSData .
dataWithSharedBytes:
bytes
length:
length
New instance with given bytes in shared memory.
dataWithShmID:
anID
length:
length
New instance with given shared memory ID.
deserializeTypeTag:
tag
andCrossRef:
ref
atCursor:
cursor
Description forthcoming.
Software documentation for the NSMutableData(GNUstepExtensions) category
Foundation/NSData.h
Provides some additional methods to NSData .
capacity
Returns current capacity of data buffer.
serializeTypeTag:
tag
Description forthcoming.
serializeTypeTag:
tag
andCrossRef:
xref
Description forthcoming.
setCapacity:
newCapacity
Sets current capacity of data buffer. Unlike -setLength: , this will shrink the buffer if requested.
shmID
Return shared memory ID, if using one, else -1.