Up

# NSData class reference

### Authors

Andrew Kachites McCallum (`mccallum@gnu.ai.mit.edu`)
Richard Frith-Macdonald (`richard@brainstorm.co.uk`)

Date: Generated at 2025-02-13 06:02:40 +0000

Copyright: (C) 1995 Free Software Foundation, Inc.

### Contents -

1. Software documentation for the NSData class
2. Software documentation for the NSMutableData class
3. Software documentation for the NSData(GNUstepExtensions) category
4. Software documentation for the NSMutableData(GNUstepExtensions) category

# Software documentation for the NSData class

## NSData : NSObject

> 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

- +dataWithSharedBytes:length:
- +dataWithShmID:length:
- -deserializeTypeTag:andCrossRef:atCursor:
- +data
- +dataWithBytes:length:
- +dataWithBytesNoCopy:length:
- +dataWithBytesNoCopy:length:freeWhenDone:
- +dataWithContentsOfFile:
- +dataWithContentsOfMappedFile:
- +dataWithContentsOfURL:
- +dataWithData:
- -base64EncodedDataWithOptions:
- -base64EncodedStringWithOptions:
- -bytes
- -description
- -deserializeAlignedBytesLengthAtCursor:
- -deserializeBytes:length:atCursor:
- -deserializeDataAt:ofObjCType:atCursor:context:
- -deserializeIntAtCursor:
- -deserializeIntAtIndex:
- -deserializeInts:count:atCursor:
- -deserializeInts:count:atIndex:
- -getBytes:
- -getBytes:length:
- -getBytes:range:
- -initWithBase64EncodedData:options:
- -initWithBase64EncodedString:options:
- -initWithBytes:length:
- -initWithBytesNoCopy:length:
- -initWithBytesNoCopy:length:deallocator:
- -initWithBytesNoCopy:length:freeWhenDone:
- -initWithContentsOfFile:
- -initWithContentsOfMappedFile:
- -initWithContentsOfURL:
- -initWithData:
- -isEqualToData:
- -length
- -rangeOfData:options:range:
- -subdataWithRange:
- -writeToFile:atomically:
- -writeToFile:options:error:
- -writeToURL:atomically:
- -writeToURL:options:error:

### data

+ (id) data;
Availability: OpenStep
Returns an empty data object.

### dataWithBytes: length:

+ (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:

### dataWithBytesNoCopy: length:

+ (id) dataWithBytesNoCopy: (void*)bytes length: (NSUInteger)length;
Availability: OpenStep
Returns an autoreleased data object encapsulating the data at bytes and with the specified length. Invokes -initWithBytesNoCopy:length:freeWhenDone: with `YES`

### dataWithBytesNoCopy: length: freeWhenDone:

+ (id) dataWithBytesNoCopy: (void*)aBuffer length: (NSUInteger)bufferSize freeWhenDone: (BOOL)shouldFree;
Availability: MacOS-X 10.0.0
Returns an autoreleased data object encapsulating the data at bytes and with the specified length. Invokes -initWithBytesNoCopy:length:freeWhenDone:

### dataWithContentsOfFile:

+ (id) dataWithContentsOfFile: (NSString*)path;
Availability: OpenStep
Returns a data object encapsulating the contents of the specified file. Invokes -initWithContentsOfFile:

### dataWithContentsOfMappedFile:

+ (id) dataWithContentsOfMappedFile: (NSString*)path;
Availability: OpenStep
Returns a data object encapsulating the contents of the specified file mapped directly into memory. Invokes -initWithContentsOfMappedFile:

### dataWithContentsOfURL:

+ (id) dataWithContentsOfURL: (NSURL*)url;
Availability: MacOS-X 10.0.0
Retrieves the information at the specified url and returns an NSData instance encapsulating it.

### dataWithData:

+ (id) dataWithData: (NSData*)data;
Availability: OpenStep
Returns an autoreleased instance initialised by copying the contents of data.

### base64EncodedDataWithOptions:

- (NSData*) base64EncodedDataWithOptions: (NSDataBase64EncodingOptions)options;
Availability: MacOS-X 10.9.0
Description forthcoming.

### base64EncodedStringWithOptions:

- (NSString*) base64EncodedStringWithOptions: (NSDataBase64EncodingOptions)options;
Availability: MacOS-X 10.9.0
Description forthcoming.

### bytes

- (const void*) bytes;
Availability: OpenStep
Subclasses must override this method.
Returns a pointer to the data encapsulated by the receiver.

### description

- (NSString*) description;
Availability: OpenStep
Returns a short description of this object.

### deserializeAlignedBytesLengthAtCursor:

- (unsigned int) deserializeAlignedBytesLengthAtCursor: (unsigned int*)cursor;
Availability: OpenStep
Copies data from buffer starting from cursor. Deprecated. Use [-getBytes:] and related methods instead.

### deserializeBytes: length: atCursor:

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

### deserializeDataAt: ofObjCType: atCursor: context:

- (void) deserializeDataAt: (void*)data ofObjCType: (const char*)type atCursor: (unsigned int*)cursor context: (id<NSObjCTypeSerializationCallBack>)callback;
Availability: OpenStep
Description forthcoming.

### deserializeIntAtCursor:

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

### deserializeIntAtIndex:

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

### deserializeInts: count: atCursor:

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

### deserializeInts: count: atIndex:

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

### getBytes:

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

### getBytes: length:

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

### getBytes: range:

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

### initWithBase64EncodedData: options:

- (id) initWithBase64EncodedData: (NSData*)base64Data options: (NSDataBase64DecodingOptions)options;
Availability: MacOS-X 10.9.0
Description forthcoming.

### initWithBase64EncodedString: options:

- (id) initWithBase64EncodedString: (NSString*)base64String options: (NSDataBase64DecodingOptions)options;
Availability: MacOS-X 10.9.0
Description forthcoming.

### initWithBytes: length:

- (id) initWithBytes: (const void*)aBuffer length: (NSUInteger)bufferSize;
Availability: OpenStep
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: length:

- (id) initWithBytesNoCopy: (void*)aBuffer length: (NSUInteger)bufferSize;
Availability: OpenStep
Invokes -initWithBytesNoCopy:length:freeWhenDone: with the last argument set to `YES`. Returns the resulting initialised data object (which may not be the receiver).

### initWithBytesNoCopy: length: deallocator:

- (instancetype) initWithBytesNoCopy: (void*)bytes length: (NSUInteger)length deallocator: (GSDataDeallocatorBlock)deallocBlock;
Availability: MacOS-X 10.9.0
Subclasses must override this method.
Initialize the receiver to hold memory pointed to by bytes without copying. When the receiver is deallocated, the memory will be freed using the user supplied deallocBlock. Note that passing a block that (either directly or indirectly) holds a strong reference the receiver will cause a retain cycle.

### initWithBytesNoCopy: length: freeWhenDone:

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

### initWithContentsOfFile:

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

### initWithContentsOfMappedFile:

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

### initWithContentsOfURL:

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

### initWithData:

- (id) initWithData: (NSData*)data;
Availability: OpenStep
Initializes by copying data's bytes into a new buffer.

### isEqualToData:

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

### length

- (NSUInteger) length;
Availability: OpenStep
Subclasses must override this method.
Returns the number of bytes of data encapsulated by the receiver.

### rangeOfData: options: range:

- (NSRange) rangeOfData: (NSData*)dataToFind options: (NSDataSearchOptions)mask range: (NSRange)searchRange;
Availability: MacOS-X 10.6.0
Finds and returns the range of the first occurrence of the given data, within the given range, subject to given options.

### subdataWithRange:

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

### writeToFile: atomically:

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

### writeToFile: options: error:

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

### writeToURL: atomically:

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

### writeToURL: options: error:

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

# Software documentation for the NSMutableData class

## NSMutableData : NSData

> 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

- -capacity
- -serializeTypeTag:
- -serializeTypeTag:andCrossRef:
- -setCapacity:
- -shmID
- +dataWithCapacity:
- +dataWithLength:
- -appendBytes:length:
- -appendData:
- -increaseLengthBy:
- -initWithCapacity:
- -initWithLength:
- -mutableBytes
- -replaceBytesInRange:withBytes:
- -replaceBytesInRange:withBytes:length:
- -resetBytesInRange:
- -serializeAlignedBytesLength:
- -serializeDataAt:ofObjCType:context:
- -serializeInt:
- -serializeInt:atIndex:
- -serializeInts:count:
- -serializeInts:count:atIndex:
- -setData:
- -setLength:

### dataWithCapacity:

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

### dataWithLength:

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

### appendBytes: length:

- (void) appendBytes: (const void*)aBuffer length: (NSUInteger)bufferSize;
Availability: OpenStep
Appends bufferSize bytes from aBuffer to data, increasing capacity if necessary.

### appendData:

- (void) appendData: (NSData*)other;
Availability: OpenStep
Copies and appends data from other to data, increasing capacity if necessary.

### increaseLengthBy:

- (void) increaseLengthBy: (NSUInteger)extraLength;
Availability: OpenStep
Increases buffer length by given number of bytes, filling the new space with zeros.

### initWithCapacity:

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

### initWithLength:

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

### mutableBytes

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

### replaceBytesInRange: withBytes:

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

### replaceBytesInRange: withBytes: length:

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

### resetBytesInRange:

- (void) resetBytesInRange: (NSRange)aRange;
Availability: OpenStep
Set bytes in aRange to 0.

### serializeAlignedBytesLength:

- (void) serializeAlignedBytesLength: (unsigned int)length;
Availability: OpenStep
Does not act as the name suggests. Instead, serializes length itself as an int into buffer.

### serializeDataAt: ofObjCType: context:

- (void) serializeDataAt: (const void*)data ofObjCType: (const char*)type context: (id<NSObjCTypeSerializationCallBack>)callback;
Availability: OpenStep
Description forthcoming.

### serializeInt:

- (void) serializeInt: (int)value;
Availability: OpenStep
Serialize an int into this object's data buffer, swapping it to network (big-endian) byte order first.

### serializeInt: atIndex:

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

### serializeInts: count:

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

### serializeInts: count: atIndex:

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

### setData:

- (void) setData: (NSData*)data;
Availability: OpenStep
Replaces contents of buffer with contents of data's buffer, increasing or shrinking capacity to match.

### setLength:

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

# Software documentation for the NSData(GNUstepExtensions) category

## NSData(GNUstepExtensions)

> Declared in:
>   Foundation/NSData.h

Availability: Not in OpenStep/MacOS-X
Provides some shared-memory extensions to NSData .
Method summary

- +dataWithSharedBytes:length:
- +dataWithShmID:length:
- -deserializeTypeTag:andCrossRef:atCursor:

### dataWithSharedBytes: length:

+ (id) dataWithSharedBytes: (const void*)bytes length: (NSUInteger)length;
Availability: Not in OpenStep/MacOS-X
New instance with given bytes in shared memory.

### dataWithShmID: length:

+ (id) dataWithShmID: (int)anID length: (NSUInteger)length;
Availability: Not in OpenStep/MacOS-X
New instance with given shared memory ID.

### deserializeTypeTag: andCrossRef: atCursor:

- (void) deserializeTypeTag: (unsigned char*)tag andCrossRef: (unsigned int*)ref atCursor: (unsigned int*)cursor;
Availability: Not in OpenStep/MacOS-X
Description forthcoming.

# Software documentation for the NSMutableData(GNUstepExtensions) category

## NSMutableData(GNUstepExtensions)

> Declared in:
>   Foundation/NSData.h

Availability: Not in OpenStep/MacOS-X
Provides some additional methods to NSData .
Method summary

- -capacity
- -serializeTypeTag:
- -serializeTypeTag:andCrossRef:
- -setCapacity:
- -shmID

### capacity

- (NSUInteger) capacity;
Availability: Not in OpenStep/MacOS-X
Returns current capacity of data buffer.

### serializeTypeTag:

- (void) serializeTypeTag: (unsigned char)tag;
Availability: Not in OpenStep/MacOS-X
Description forthcoming.

### serializeTypeTag: andCrossRef:

- (void) serializeTypeTag: (unsigned char)tag andCrossRef: (unsigned int)xref;
Availability: Not in OpenStep/MacOS-X
Description forthcoming.

### setCapacity:

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

### shmID

- (int) shmID;
Availability: Not in OpenStep/MacOS-X
Return shared memory ID, if using one, else -1.

Up