CFMutableData Reference

Derived from
Framework
CoreFoundation/CoreFoundation.h
Declared in
CFData.h
Companion guides

Overview

CFMutableData manages dynamic binary data. The basic interface for managing binary data is provided by CFData. CFMutableData adds functions to modify the contents of a binary data object.

You create a mutable data object using either the CFDataCreateMutable or CFDataCreateMutableCopy function.

Bytes are added to a data object with the CFDataAppendBytes function. Bytes are removed from a data object with the CFDataDeleteBytes function.

CFMutableData is “toll-free bridged” with its Cocoa Foundation counterpart, NSMutableData. What this means is that the Core Foundation type is interchangeable in function or method calls with the bridged Foundation object. In other words, in a method where you see an NSMutableData * parameter, you can pass in a CFMutableDataRef, and in a function where you see a CFMutableDataRef parameter, you can pass in an NSMutableData instance. This also applies to concrete subclasses of NSMutableData. See “Toll-Free Bridged Types” for more information on toll-free bridging.

Functions by Task

Creating a Mutable Data Object

Accessing Data

Modifying a Mutable Data Object

Functions

CFDataAppendBytes

Appends the bytes from a byte buffer to the contents of a CFData object.

void CFDataAppendBytes (
   CFMutableDataRef theData,
   const UInt8 *bytes,
   CFIndex length
);
Parameters
theData

A CFMutableData object. If you pass an immutable CFData object, the behavior is not defined.

bytes

A pointer to the buffer of bytes to be added to theData.

length

The number of bytes in the byte buffer bytes.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
CFData.h

CFDataCreateMutable

Creates an empty CFMutableData object.

CFMutableDataRef CFDataCreateMutable (
   CFAllocatorRef allocator,
   CFIndex capacity
);
Parameters
allocator

The CFAllocator object to be used to allocate memory for the new object. Pass NULL or kCFAllocatorDefault to use the current default allocator.

capacity

The maximum number of bytes that the CFData object can contain. The CFData object starts empty and can grow to contain this number of values (and it can have less).

Pass 0 to specify that the maximum capacity is not limited. The value must not be negative.

Return Value

A CFMutableData object or NULL if there was a problem creating the object. Ownership follows the Create Rule.

Discussion

This function creates an empty (that is, content-less) CFMutableData object. You can add raw data to this object with the CFDataAppendBytes function, and thereafter you can replace and delete characters with the appropriate CFMutableData functions. If the capacity parameter is greater than 0, any attempt to add characters beyond this limit can result in undefined behavior.

Availability
  • Available in OS X v10.0 and later.
Declared In
CFData.h

CFDataCreateMutableCopy

Creates a CFMutableData object by copying another CFData object.

CFMutableDataRef CFDataCreateMutableCopy (
   CFAllocatorRef allocator,
   CFIndex capacity,
   CFDataRef theData
);
Parameters
allocator

The CFAllocator object to be used to allocate memory for the new object. Pass NULL or kCFAllocatorDefault to use the current default allocator.

capacity

The maximum number of bytes that the CFData object can contain. The CFData object starts with the same length as the original object, and can grow to contain this number of bytes.

Pass 0 to specify that the maximum capacity is not limited. If non-0, capacity must be greater than or equal to the length of theData.

theData

The CFData object to be copied.

Return Value

A CFMutableData object that has the same contents as the original object. Returns NULL if there was a problem copying the object. Ownership follows the Create Rule.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
CFData.h

CFDataDeleteBytes

Deletes the bytes in a CFMutableData object within a specified range.

void CFDataDeleteBytes (
   CFMutableDataRef theData,
   CFRange range
);
Parameters
theData

A CFMutableData object. If you pass an immutable CFData object, the behavior is not defined.

range

The range of bytes (that is, the starting byte and the number of bytes from that point) to delete from theData's byte buffer.

Availability
  • Available in OS X v10.0 and later.
Declared In
CFData.h

CFDataGetMutableBytePtr

Returns a pointer to a mutable byte buffer of a CFMutableData object.

UInt8 *CFDataGetMutableBytePtr (
   CFMutableDataRef theData
);
Parameters
theData

A CFMutableData object. If you pass an immutable CFData object, the behavior is not defined.

Return Value

A pointer to the bytes associated with theData.

Discussion

If the length of theData’s data is not zero, this function is guaranteed to return a pointer to a CFMutableData object's internal bytes. If the length of theData’s data is zero, this function may or may not return NULL dependent upon many factors related to how the object was created (moreover, in this case the function result might change between different releases and on different platforms).

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
CFData.h

CFDataIncreaseLength

Increases the length of a CFMutableData object's internal byte buffer, zero-filling the extension to the buffer.

void CFDataIncreaseLength (
   CFMutableDataRef theData,
   CFIndex extraLength
);
Parameters
theData

A CFMutableData object. If you pass an immutable CFData object, the behavior is not defined.

extraLength

The number of bytes by which to increase the byte buffer.

Discussion

This function increases the length of a CFMutableData object’s underlying byte buffer to a new size, initializing the new bytes to 0.

Availability
  • Available in OS X v10.0 and later.
Declared In
CFData.h

CFDataReplaceBytes

Replaces those bytes in a CFMutableData object that fall within a specified range with other bytes.

void CFDataReplaceBytes (
   CFMutableDataRef theData,
   CFRange range,
   const UInt8 *newBytes,
   CFIndex newLength
);
Parameters
theData

A CFMutableData object. If you pass an immutable CFData object, the behavior is not defined.

range

The range of bytes (that is, the starting byte and the number of bytes from that point) to delete from theData's byte buffer.

newBytes

A pointer to the buffer containing the replacement bytes.

newLength

The number of bytes in the byte buffer newBytes.

Availability
  • Available in OS X v10.0 and later.
Declared In
CFData.h

CFDataSetLength

Resets the length of a CFMutableData object's internal byte buffer.

void CFDataSetLength (
   CFMutableDataRef theData,
   CFIndex length
);
Parameters
theData

A CFMutableData object. If you pass an immutable CFData object, the behavior is not defined.

length

The new size of theData’s byte buffer.

Discussion

This function resets the length of a CFMutableData object’s underlying byte buffer to a new size. If that size is less than the current size, it truncates the excess bytes. If that size is greater than the current size, it zero-fills the extension to the byte buffer.

Availability
  • Available in OS X v10.0 and later.
Declared In
CFData.h

Data Types

CFMutableDataRef

A reference to a CFMutableData object.

typedef struct __CFData *CFMutableDataRef;
Availability
  • Available in OS X v10.0 and later.
Declared In
CFData.h