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.

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.

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.

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.

This is a designated initialiser for the class.
Subclasses must override this method.

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.

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.

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.

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.

Writes a copy of the data encapsulated by the
receiver to a file at path. If the
NSDataWritingAtomic 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.

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.

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.

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.