Up
Authors
- Andrew Kachites McCallum (
mccallum@gnu.ai.mit.edu
)
-
- Richard Frith-Macdonald (
richard@brainstorm.co.uk
)
-
Version: 38803
Date: 2015-07-16 02:44:15 -0600 (Thu, 16 Jul 2015)
Copyright: (C) 1995-2015 Free Software Foundation, Inc.
- Declared in:
- Foundation/NSData.h
- Conforms to:
- NSCoding
- NSCopying
- NSMutableCopying
Availability: OpenStep
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.
Method summary
+ (id)
data;
Availability: OpenStep
Returns an empty data object.
+ (id)
dataWithBytes: (const void*)bytes
length: (
NSUInteger)length;
Availability: OpenStep
Returns an autoreleased data object containing data
copied from
bytes and with the specified
length. Invokes
-initWithBytes:length:
+ (id)
dataWithBytesNoCopy: (void*)bytes
length: (
NSUInteger)length;
Availability: OpenStep
+ (id)
dataWithBytesNoCopy: (void*)aBuffer
length: (
NSUInteger)bufferSize
freeWhenDone: (BOOL)shouldFree;
Availability: MacOS-X 10.0.0
+ (id)
dataWithContentsOfFile: (
NSString*)path;
Availability: OpenStep
+ (id)
dataWithContentsOfMappedFile: (
NSString*)path;
Availability: OpenStep
+ (id)
dataWithContentsOfURL: (
NSURL*)url;
Availability: MacOS-X 10.0.0
Retrieves the information at the specified
url and returns an NSData instance
encapsulating it.
+ (id)
dataWithData: (
NSData*)data;
Availability: OpenStep
Returns an autoreleased instance initialised by
copying the contents of data.
- (const void*)
bytes;
Availability: OpenStep
Subclasses
must override this method.
Returns a pointer to the data encapsulated by the
receiver.
- (
NSString*)
description;
Availability: OpenStep
Returns a short description of
this object.
- (unsigned int)
deserializeAlignedBytesLengthAtCursor: (unsigned int*)cursor;
Availability: OpenStep
Copies data from buffer starting from
cursor.
Deprecated. Use
[-getBytes:]
and related methods instead.
- (void)
deserializeBytes: (void*)buffer
length: (unsigned int)bytes
atCursor: (unsigned int*)cursor;
Availability: OpenStep
Copies data from
buffer starting from
cursor.
Deprecated. Use
[-getBytes:]
and related methods instead.
- (void)
deserializeDataAt: (void*)data
ofObjCType: (const char*)type
atCursor: (unsigned int*)cursor
context: (id<
NSObjCTypeSerializationCallBack>)callback;
Availability: OpenStep
Description forthcoming.
- (int)
deserializeIntAtCursor: (unsigned int*)cursor;
Availability: OpenStep
Retrieve an int from this data,
which is assumed to be in network (big-endian) byte
order. Cursor refers to byte position.
- (int)
deserializeIntAtIndex: (unsigned int)index;
Availability: OpenStep
Retrieve an int from this data,
which is assumed to be in network (big-endian) byte
order. Index refers to byte position.
- (void)
deserializeInts: (int*)intBuffer
count: (unsigned int)numInts
atCursor: (unsigned int*)cursor;
Availability: OpenStep
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.
- (void)
deserializeInts: (int*)intBuffer
count: (unsigned int)numInts
atIndex: (unsigned int)index;
Availability: OpenStep
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.
- (void)
getBytes: (void*)buffer;
Availability: OpenStep
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.
- (void)
getBytes: (void*)buffer
length: (
NSUInteger)length;
Availability: OpenStep
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.
- (void)
getBytes: (void*)buffer
range: (
NSRange)aRange;
Availability: OpenStep
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.
- (id)
initWithBytes: (const void*)aBuffer
length: (
NSUInteger)bufferSize;
Availability: OpenStep
- (id)
initWithBytesNoCopy: (void*)aBuffer
length: (
NSUInteger)bufferSize;
Availability: OpenStep
- (id)
initWithBytesNoCopy: (void*)aBuffer
length: (
NSUInteger)bufferSize
freeWhenDone: (BOOL)shouldFree;
Availability: MacOS-X 10.0.0
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.
- (id)
initWithContentsOfFile: (
NSString*)path;
Availability: OpenStep
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.
- (id)
initWithContentsOfMappedFile: (
NSString*)path;
Availability: OpenStep
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.
- (id)
initWithContentsOfURL: (
NSURL*)url;
Availability: MacOS-X 10.0.0
Initialize with data pointing to contents of
URL, which will be retrieved immediately in a blocking
manner.
- (id)
initWithData: (
NSData*)data;
Availability: OpenStep
Initializes by copying data's bytes into a new
buffer.
- (BOOL)
isEqualToData: (
NSData*)other;
Availability: OpenStep
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.
- (
NSUInteger)
length;
Availability: OpenStep
Subclasses
must override this method.
Returns the number of bytes of data encapsulated by
the receiver.
- (
NSData*)
subdataWithRange: (
NSRange)aRange;
Availability: OpenStep
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.
- (BOOL)
writeToFile: (
NSString*)path
atomically: (BOOL)useAuxiliaryFile;
Availability: OpenStep
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
.
- (BOOL)
writeToFile: (
NSString*)path
options: (
NSUInteger)writeOptionsMask
error: (
NSError**)errorPtr;
Availability: MacOS-X 10.4.0
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.
On success returns YES
, on failure
returns NO
.
- (BOOL)
writeToURL: (
NSURL*)anURL
atomically: (BOOL)flag;
Availability: MacOS-X 10.0.0
Writes a copy of the contents of the receiver to the
specified URL.
- (BOOL)
writeToURL: (
NSURL*)url
options: (
NSUInteger)writeOptionsMask
error: (
NSError**)errorPtr;
Availability: MacOS-X 10.4.0
Writes a copy of the contents of the receiver to the
specified URL.
- Declared in:
- Foundation/NSData.h
Availability: OpenStep
Mutable version of
NSData
. Methods are provided for appending and replacing bytes
in the buffer, which will be grown as needed.
Method summary
+ (id)
dataWithCapacity: (
NSUInteger)numBytes;
Availability: OpenStep
New instance with buffer of given numBytes
with length of valid data set to zero. Note that
capacity will be automatically increased as
necessary.
+ (id)
dataWithLength: (
NSUInteger)length;
Availability: OpenStep
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.
- (void)
appendBytes: (const void*)aBuffer
length: (
NSUInteger)bufferSize;
Availability: OpenStep
Appends bufferSize bytes from
aBuffer to data, increasing capacity if
necessary.
- (void)
appendData: (
NSData*)other;
Availability: OpenStep
Copies and appends data from other to
data, increasing capacity if necessary.
- (void)
increaseLengthBy: (
NSUInteger)extraLength;
Availability: OpenStep
Increases buffer length by given number of bytes,
filling the new space with zeros.
- (id)
initWithCapacity: (
NSUInteger)capacity;
Availability: OpenStep
This is a designated initialiser for the class.
Initialize with buffer capable of holding size
bytes. The length of valid data is initially set to
zero.
- (id)
initWithLength: (
NSUInteger)length;
Availability: OpenStep
Initialize with buffer of capacity equal to
length, and with the length of
valid data set to length. Data is set to
zero.
- (void*)
mutableBytes;
Availability: OpenStep
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.
- (void)
replaceBytesInRange: (
NSRange)aRange
withBytes: (const void*)bytes;
Availability: OpenStep
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.
- (void)
replaceBytesInRange: (
NSRange)aRange
withBytes: (const void*)bytes
length: (
NSUInteger)length;
Availability: MacOS-X 10.0.0
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.
- (void)
resetBytesInRange: (
NSRange)aRange;
Availability: OpenStep
Set bytes in aRange to 0.
- (void)
serializeAlignedBytesLength: (unsigned int)length;
Availability: OpenStep
Does not act as the name suggests. Instead, serializes
length itself as an int
into buffer.
- (void)
serializeDataAt: (const void*)data
ofObjCType: (const char*)type
context: (id<
NSObjCTypeSerializationCallBack>)callback;
Availability: OpenStep
Description forthcoming.
- (void)
serializeInt: (int)value;
Availability: OpenStep
Serialize an int into this
object's data buffer, swapping it to network
(big-endian) byte order first.
- (void)
serializeInt: (int)value
atIndex: (unsigned int)index;
Availability: OpenStep
Serialize an int into this
object's data buffer at index
(replacing anything there currently), swapping
it to network (big-endian) byte order first.
- (void)
serializeInts: (int*)intBuffer
count: (unsigned int)numInts;
Availability: OpenStep
Serialize one or more ints into this object's
data buffer, swapping them to network (big-endian)
byte order first.
- (void)
serializeInts: (int*)intBuffer
count: (unsigned int)numInts
atIndex: (unsigned int)index;
Availability: OpenStep
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.
- (void)
setData: (
NSData*)data;
Availability: OpenStep
Replaces contents of buffer with contents of
data's buffer, increasing or shrinking capacity to
match.
- (void)
setLength: (
NSUInteger)size;
Availability: OpenStep
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.
- Declared in:
- Foundation/NSData.h
Availability: Not in OpenStep/MacOS-X
Provides some shared-memory extensions to
NSData
.
Method summary
+ (id)
dataWithSharedBytes: (const void*)bytes
length: (
NSUInteger)length;
Availability: Not in OpenStep/MacOS-X
New instance with given bytes in shared
memory.
+ (id)
dataWithShmID: (int)anID
length: (
NSUInteger)length;
Availability: Not in OpenStep/MacOS-X
New instance with given shared memory ID.
- (void)
deserializeTypeTag: (unsigned char*)tag
andCrossRef: (unsigned int*)ref
atCursor: (unsigned int*)cursor;
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
- Declared in:
- Foundation/NSData.h
Availability: Not in OpenStep/MacOS-X
Provides some additional methods to
NSData
.
Method summary
- (
NSUInteger)
capacity;
Availability: Not in OpenStep/MacOS-X
Returns current capacity of data buffer.
- (void)
serializeTypeTag: (unsigned char)tag;
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
- (void)
serializeTypeTag: (unsigned char)tag
andCrossRef: (unsigned int)xref;
Availability: Not in OpenStep/MacOS-X
Description forthcoming.
- (id)
setCapacity: (
NSUInteger)newCapacity;
Availability: Not in OpenStep/MacOS-X
Sets current capacity of data buffer. Unlike
-setLength:
, this will shrink the buffer if requested.
- (int)
shmID;
Availability: Not in OpenStep/MacOS-X
Return shared memory ID, if using one, else -1.
Up