PATH  Documentation > Mac OS X > Foundation Reference: Objective-C



Table of Contents

NSMutableData


Inherits from:
NSData : NSObject
Conforms to:
NSCoding
NSCopying
NSMutableCopying (NSData)
NSObject (NSObject)
Declared in:
Foundation/NSData.h
Foundation/NSSerialization.h



Class at a Glance


An NSMutableData object stores mutable data in the form of bytes.

Principal Attributes


Creation



+ dataWithCapacity: Returns an NSMutableData with enough allocated memory to hold a specified number of bytes.
+ dataWithLength: Returns an NSMutableData that contains a specified number of zero-filled bytes.

Primitive Methods



- mutableBytes A pointer to the bytes in the NSMutableData object.
- setLength: Replaces a range of bytes in the NSMutableData object.




Class Description


The NSMutableData class declares the programmatic interface to an object that contains modifiable data in the form of bytes. NSMutableData's two primitive methods- mutableBytes and setLength:-provide the basis for all of the other methods in its interface. The mutableBytes method returns a pointer for writing into the bytes contained in the mutable data object. setLength: allows you to truncate or extend the length of a mutable data object.

increaseLengthBy: also allows you to change the length of a mutable data object.

The appendBytes:length: and appendData: methods let you append bytes or the contents of another data object to a mutable data object. You can replace a range of bytes in a mutable data object with zeros (using the resetBytesInRange: method), or with different bytes (using the replaceBytesInRange:withBytes: method).




Method Types


Creating an NSMutableData
+ dataWithCapacity:
+ dataWithLength:
- initWithCapacity:
- initWithLength:
Adjusting capacity
- increaseLengthBy:
- setLength:
Accessing data
- mutableBytes
Adding data
- appendBytes:length:
- appendData:
Serializing data
- serializeAlignedBytesLength:
- serializeDataAt:ofObjCType:context:
- serializeInt:
- serializeInt:atIndex:
- serializeInts:count:
- serializeInts:count:atIndex:
Modifying data
- replaceBytesInRange:withBytes:
- resetBytesInRange:
- setData:


Class Methods



dataWithCapacity:

+ (id)dataWithCapacity:(unsigned)aNumItems

Creates and returns an NSMutableData object, initially allocating enough memory to hold aNumItems objects. Mutable data objects allocate additional memory as needed, so aNumItems simply establishes the object's initial capacity.

This method doesn't necessarily allocate its memory at the time of method invocation. When it does allocate its memory, though, it initially allocates the specified amount.

See Also: + dataWithLength:, - initWithCapacity:, - initWithLength:



dataWithLength:

+ (id)dataWithLength:(unsigned)length

Creates an autoreleased, mutable data object of length bytes, filled with zeros.

See Also: + dataWithCapacity:, - initWithCapacity:, - initWithLength:




Instance Methods



appendBytes:length:

- (void)appendBytes:(const void *)bytes length:(unsigned)length

Appends length bytes to the receiver from the buffer bytes.

This excerpt copies the bytes in data2 into aBuffer, and then appends aBuffer to data1.

NSMutableData *data1, *data2;
NSString *firstString =  @"ABCD"; 
NSString *secondString = @"EFGH"; 
unsigned char *aBuffer;
unsigned len;
	
data1 = [NSMutableData dataWithBytes:[firstString cString]
        length:[firstString cStringLength]];
data2 = [NSMutableData dataWithBytes:[secondString cString]
        length:[secondString cStringLength]];
	
len = [data2 length];
aBuffer = malloc(len);
	
[data2 getBytes:aBuffer];
[data1 appendBytes:aBuffer length:len];

The final value of data1 is the series of ASCII characters "ABCDEFGH".

See Also: - appendData:



appendData:

- (void)appendData:(NSData *)otherData

Appends the contents of a data object otherData to the receiver.

See Also: - appendBytes:length:



increaseLengthBy:

- (void)increaseLengthBy:(unsigned)extraLength

Increases the length of the receiver by extraLength. The additional bytes are all set to zero.

See Also: - setLength:



initWithCapacity:

- (id)initWithCapacity:(unsigned)capacity

Initializes a newly allocated mutable data object, giving it enough memory to hold capacity bytes. Sets the length of the data object to 0. Returns self.

See Also: + dataWithCapacity:, - initWithLength:



initWithLength:

- (id)initWithLength:(unsigned)length

Initializes a newly allocated mutable data object, giving it enough memory to hold length bytes. Fills the object with zeros up to length. Returns self.

See Also: + dataWithCapacity:, - dataWithLength:, - initWithCapacity:



mutableBytes

- (void *)mutableBytes

Returns a pointer to the receiver's data.

In the following code example, mutableBytes is used to return a pointer to the bytes in data2. The bytes in data2 are then overwritten with the contents of data1.

NSMutableData *data1, *data2;
NSString *myString = @"string for data1"; 
NSString *yourString = @"string for data2"; 
unsigned char *firstBuffer, secondBuffer[20];

/* initialize data1, data2, and secondBuffer... */
data1 = [NSMutableData dataWithBytes:[myString cString]
        length:[myString length]];
data2 = [NSMutableData dataWithBytes:[yourString cString]
        length:[yourString length]];
	
[data2 getBytes:secondBuffer];
NSLog(@"data2 before: \"%s\"\n", (char *)secondBuffer);
	
firstBuffer = [data2 mutableBytes];
[data1 getBytes:firstBuffer];
NSLog(@"data1: \"%s\"\n", (char *)firstBuffer);
	
[data2 getBytes:secondBuffer];
NSLog(@"data2 after: \"%s\"\n", (char *)secondBuffer);

This is the output from the above code example:

Oct  3 15:59:51 [1113] data2 before: "string for data2" Oct  3 15:59:51 [1113] data1: "string for data1" Oct  3 15:59:51 [1113] data2 after: "string for data1"



replaceBytesInRange:withBytes:

- (void)replaceBytesInRange:(NSRange)range withBytes:(const void *)bytes

Specifies a range within the contents of a mutable data object to be replaced by bytes. If the location of range isn't within the receiver's range of bytes, an NSRangeException is raised. The receiver is resized to accommodate the new bytes, if necessary.

In the following code excerpt, a range of bytes in data1 is replaced by the bytes in data2.

NSMutableData *data1, *data2;
NSString *myString = @"Liz and John"; 
NSString *yourString = @"Larry"; 
unsigned len;
unsigned char *aBuffer;
NSRange range = {8, [yourString cStringLength]}; 
	
data1 = [NSMutableData dataWithBytes:[myString cString]
        length:[myString cStringLength]];
	
data2 = [NSMutableData dataWithBytes:[yourString cString]
        length:[yourString cStringLength]];
	
len = [data2 length];
aBuffer = malloc(len);
[data2 getBytes:aBuffer];
[data1 replaceBytesInRange:range withBytes:aBuffer];

The contents of data1 changes from "Liz and John" to "Liz and Larry".

See Also: - resetBytesInRange:



resetBytesInRange:

- (void)resetBytesInRange:(NSRange)range

Specifies a range within the contents of a mutable data object to be replaced by zeros. If the location of range isn't within the receiver's range of bytes, an NSRangeException is raised. The receiver is resized to accommodate the new bytes, if necessary.

See Also: - replaceBytesInRange:withBytes:



serializeAlignedBytesLength:

- (void)serializeAlignedBytesLength:(unsigned)length

Appends the bytes of length to the end of the receiver. This method may add extra filler bytes to increase the efficiency of deserializing subsequent data. Use of this method is optional; you can invoke serializeInt: instead. However, if you use this method, you should match its use by invoking deserializeAlignedBytesLengthAtCursor: to read the bytes of length later.



serializeDataAt:ofObjCType:context:

- (void)serializeDataAt:(const void *)data ofObjCType:(const char *)type context:(id <NSObjCTypeSerializationCallBack>)callback

Appends a sequence of bytes, specified by data, to the receiver. The bytes are formatted according to the Objective-C type code given in type. If type specifies an object, callback is used to serialize the object pointed to by data; in such a case, callback must itself be an object that conforms to the NSObjCTypeSerializationCallBack protocol. If type does not specify an object, callback can be nil.

For information on creating an Objective-C type code suitable for type, see the description of the @encode() compiler directive in Object-Oriented Programming and the Objective-C Language.

See Also: - deserializeDataAt:ofObjCType:atCursor:context: (NSData)



serializeInt:

- (void)serializeInt:(int)value

Appends the bytes of value to the end of the receiver.

See Also: - serializeAlignedBytesLength:



serializeInt:atIndex:

- (void)serializeInt:(int)value atIndex:(unsigned)index

Replaces the bytes of an integer at location index in the receiver with the bytes of value.

See Also: - replaceBytesInRange:withBytes:



serializeInts:count:

- (void)serializeInts:(int *)intBuffer count:(unsigned)numInts

Appends the bytes of numInts integers in intBuffer to the receiver.

See Also: - serializeInt:



serializeInts:count:atIndex:

- (void)serializeInts:(int *)intBuffer count:(unsigned)numInts atIndex:(unsigned)index

Replaces the bytes of numInts integers currently in the receiver with numInts integers in intBuffer.

See Also: - replaceBytesInRange:withBytes:



setData:

- (void)setData:(NSData *)aData

Replaces the entire contents of the receiver with the contents of aData. As part of its implementation, this method calls replaceBytesInRange:withBytes:.



setLength:

- (void)setLength:(unsigned)length

Extends or truncates a mutable data object to length. If the mutable data object is extended, the additional bytes are filled with zero.

See Also: - increaseLengthBy:




Table of Contents