Next Page > Hide TOC

NSData

Class at a Glance

An NSData object stores immutable data in the form of bytes. The size of the data is subject to a 2GB limit.

Principal Attributes

• A count of the number of bytes in the data object

• The sequence of bytes contained in the data object

Creation

NSData

Creates a data object.

Commonly Used Methods

length

Returns the number of bytes contained by the data object.

Primitive Methods

length

Returns the number of bytes contained by the data object.

Overview

NSData and its subclass NSMutableData 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. NSData creates static data objects, and NSMutableData creates dynamic data objects. NSData and NSMutableData 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.

The mutable subclass of NSData is NSMutableData.

Tasks

Constructors

• NSData

Creating Data Objects

• dataWithContentsOfMappedFile

Accessing Data

• bytes
• subdataWithRange

Testing Data

• isEqualToData
• length

Storing Data

• writeToURL

Static Methods

dataWithContentsOfMappedFile

Creates and returns a data object from the mapped file specified by file.

public static NSData dataWithContentsOfMappedFile(java.io.File file)

Discussion

Returns null if the data object could not be creates. Because of file mapping restrictions, this method should only be used if the file is guaranteed to exist for the duration of the data object’s existence.

This methods assumes mapped files are available from the underlying operating system. A mapped file uses virtual memory techniques to avoid copying pages of the file into memory until they are actually needed.

Instance Methods

bytes

Returns a byte array of length bytes from the receiver’s contents starting at start.

public byte[] bytes(int start, int length)

isEqualToData

Compares the receiving data object to otherData.

public boolean isEqualToData(NSData otherData)

Discussion

If the contents of otherData are equal to the contents of the receiver, this method returns true. If not, it returns false. Two data objects are equal if they hold the same number of bytes, and if the bytes at the same position in the objects are the same.

length

Returns the number of bytes contained in the receiver.

public int length()

subdataWithRange

Returns a data object containing a copy of the receiver’s bytes that fall within the limits specified by range.

public NSData subdataWithRange(NSRange range)

Discussion

If range isn’t within the receiver’s range of bytes, a RangeException is thrown.

For example, the following code excerpt initializes a data object, data2, to contain a subrange of data1:

String myString = "ABCDEFG";

range = new NSRange(2,4);

NSData data1 = new NSData(myString.getBytes());

NSData data2 = data1.subdataWithRange(range);

The result of this excerpt is that data2 contains “CDEF”.

writeToURL

Writes the bytes in the receiver to the location specified by aURL.

public boolean writeToURL(java.net.URL aURL, boolean atomically)

Discussion

If atomically is true, the data is written to a backup location, and then, assuming no errors occur, the backup location is renamed to the specified name. Otherwise, the data is written directly to the specified location. atomically is ignored if aURL is not of a type the supports atomic writes.

This method returns true if the operation succeeds; otherwise, it returns false.

Next Page > Hide TOC