iOS Developer Library

Developer

Foundation Framework Reference NSMutableData Class Reference

Options
Deployment Target:

On This Page
Language:

NSMutableData

Inheritance


Conforms To


Import Statement


Swift

import Foundation

Objective-C

@import Foundation;

Availability


Available in iOS 2.0 and later.

NSMutableData (and its superclass NSData) provide data objects, object-oriented wrappers for byte buffers. Data objects let simple allocated buffers (that is, data with no embedded pointers) take on the behavior of Foundation objects. They are typically used for data storage and are also useful in Distributed Objects applications, where data contained in data objects can be copied or moved between applications. NSData creates static data objects, and NSMutableData creates dynamic data objects. You can easily convert one type of data object to the other with the initializer that takes an NSData object or an NSMutableData object as an argument.

The following NSData methods change when used on a mutable data object:

When called, the bytes are immediately copied and then the buffer is freed.

NSMutableData is “toll-free bridged” with its Core Foundation counterpart, CFDataRef. See Toll-Free Bridging for more information on toll-free bridging.

  • Creates and returns an NSMutableData object capable of holding the specified number of bytes.

    Declaration

    Objective-C

    + (instancetype)dataWithCapacity:(NSUInteger)aNumItems

    Parameters

    aNumItems

    The number of bytes the new data object can initially contain.

    Return Value

    A new NSMutableData object capable of holding aNumItems bytes.

    Discussion

    This method doesn’t necessarily allocate the requested memory right away. Mutable data objects allocate additional memory as needed, so aNumItems simply establishes the object’s initial capacity. When it does allocate the initial memory, though, it allocates the specified amount. This method sets the length of the data object to 0.

    If the capacity specified in aNumItems is greater than four memory pages in size, this method may round the amount of requested memory up to the nearest full page.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

  • Creates and returns an NSMutableData object containing a given number of zeroed bytes.

    Declaration

    Objective-C

    + (instancetype)dataWithLength:(NSUInteger)length

    Parameters

    length

    The number of bytes the new data object initially contains.

    Return Value

    A new NSMutableData object of length bytes, filled with zeros.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

  • Returns an initialized NSMutableData object capable of holding the specified number of bytes.

    Declaration

    Swift

    init?(capacity capacity: Int)

    Objective-C

    - (instancetype)initWithCapacity:(NSUInteger)capacity

    Parameters

    capacity

    The number of bytes the data object can initially contain.

    Return Value

    An initialized NSMutableData object capable of holding capacity bytes.

    Discussion

    This method doesn’t necessarily allocate the requested memory right away. Mutable data objects allocate additional memory as needed, so aNumItems simply establishes the object’s initial capacity. When it does allocate the initial memory, though, it allocates the specified amount. This method sets the length of the data object to 0.

    If the capacity specified in aNumItems is greater than four memory pages in size, this method may round the amount of requested memory up to the nearest full page.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Initializes and returns an NSMutableData object containing a given number of zeroed bytes.

    Declaration

    Swift

    init?(length length: Int)

    Objective-C

    - (instancetype)initWithLength:(NSUInteger)length

    Parameters

    length

    The number of bytes the object initially contains.

    Return Value

    An initialized NSMutableData object containing length zeroed bytes.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • length length Property

    The number of bytes contained in the mutable data object.

    Declaration

    Swift

    var length: Int

    Objective-C

    @property NSUInteger length

    Discussion

    The mutable data object’s length parameter is read-writeable. You can set this parameter to expand or truncate the number of bytes contained by the data object. If the mutable data object is expanded, the additional bytes are filled with zeros.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 8.0 and later.

  • Increases the length of the receiver by a given number of bytes.

    Declaration

    Swift

    func increaseLengthBy(_ extraLength: Int)

    Objective-C

    - (void)increaseLengthBy:(NSUInteger)extraLength

    Parameters

    extraLength

    The number of bytes by which to increase the receiver's length.

    Discussion

    The additional bytes are all set to 0.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

    See Also

    length

  • A pointer to the data contained by the mutable data object. (read-only)

    Declaration

    Swift

    var mutableBytes: UnsafeMutablePointer<Void> { get }

    Objective-C

    @property(readonly) void *mutableBytes

    Discussion

    If the length of the receiver’s data is not zero, this property is guaranteed to contain a pointer to the object's internal bytes. If the length of receiver’s data is zero, this property may or may not contain NULL dependent upon many factors related to how the object was created (moreover, in this case the method result might change between different releases).

    A sample using this method can be found in Working With Mutable Binary Data.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

    See Also

    – bytes

  • Appends to the receiver a given number of bytes from a given buffer.

    Declaration

    Swift

    func appendBytes(_ bytes: UnsafePointer<Void>, length length: Int)

    Objective-C

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

    Parameters

    bytes

    A buffer containing data to append to the receiver's content.

    length

    The number of bytes from bytes to append.

    Discussion

    A sample using this method can be found in Working With Mutable Binary Data.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

    See Also

    – appendData:

  • Appends the content of another NSData object to the receiver.

    Declaration

    Swift

    func appendData(_ otherData: NSData)

    Objective-C

    - (void)appendData:(NSData *)otherData

    Parameters

    otherData

    The data object whose content is to be appended to the contents of the receiver.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Replaces with a given set of bytes a given range within the contents of the receiver.

    Declaration

    Swift

    func replaceBytesInRange(_ range: NSRange, withBytes bytes: UnsafePointer<Void>)

    Objective-C

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

    Parameters

    range

    The range within the receiver's contents to replace with bytes. The range must not exceed the bounds of the receiver.

    bytes

    The data to insert into the receiver's contents.

    Discussion

    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.

    A sample using this method is given in Working With Mutable Binary Data.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Replaces with a given set of bytes a given range within the contents of the receiver.

    Declaration

    Swift

    func replaceBytesInRange(_ range: NSRange, withBytes replacementBytes: UnsafePointer<Void>, length replacementLength: Int)

    Objective-C

    - (void)replaceBytesInRange:(NSRange)range withBytes:(const void *)replacementBytes length:(NSUInteger)replacementLength

    Parameters

    range

    The range within the receiver's contents to replace with bytes. The range must not exceed the bounds of the receiver.

    replacementBytes

    The data to insert into the receiver's contents.

    replacementLength

    The number of bytes to take from replacementBytes.

    Discussion

    If the length of range is not equal to replacementLength, the receiver is resized to accommodate the new bytes. Any bytes past range in the receiver are shifted to accommodate the new bytes. You can therefore pass NULL for replacementBytes and 0 for replacementLength to delete bytes in the receiver in the range range. You can also replace a range (which might be zero-length) with more bytes than the length of the range, which has the effect of insertion (or “replace some and insert more”).

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Replaces with zeroes the contents of the receiver in a given range.

    Declaration

    Swift

    func resetBytesInRange(_ range: NSRange)

    Objective-C

    - (void)resetBytesInRange:(NSRange)range

    Parameters

    range

    The range within the contents of the receiver to be replaced by zeros. The range must not exceed the bounds of the receiver.

    Discussion

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Replaces the entire contents of the receiver with the contents of another data object.

    Declaration

    Swift

    func setData(_ aData: NSData)

    Objective-C

    - (void)setData:(NSData *)aData

    Parameters

    aData

    The data object whose content replaces that of the receiver.

    Discussion

    As part of its implementation, this method calls replaceBytesInRange:withBytes:.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.