Developer Documentation
PATH  Mac OS X Documentation > Foundation Reference: Java


[Previous] [Class List] [Next]

NSData


Inherits from: NSObject
Package: com.apple.yellow.foundation
Implements: NSCoding NSCopying NSMutableCopying NSObject (NSObject)

Class at a Glance


An NSData object stores immutable data in the form of bytes.

Principal Attributes


Creation



NSData Creates a data object.

Commonly Used Methods



length Returns the number of bytes contained by the data object.

Primitive Methods



bytes Returns a pointer to the data object's contents.
length Returns the number of bytes contained by the data object.




Class Description


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 Kit objects. NSData creates static data objects, and NSMutableData creates dynamic data objects. They're 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.

Data objects can wrap data of any size. When the data size is more than a few memory pages, the object uses virtual memory management. A data object can also wrap pre-existing data, regardless of how the data was allocated. The object contains no information about the data itself (such as its type); the responsibility for deciding how to use the data lies with the client. In particular, it will not handle byte-order swapping when distributed between big-endian and little-endian machines. For typed data, use NSValue.

Data objects provide an operating system-independent way to benefit from copy-on-write memory. The copy-on-write technique means that when data is copied through a virtual memory copy, an actual copy of the data is not made until there is an attempt to modify it.

NSData and NSMutableData implement the NSCopying and NSMutableCopying interfaces, making it convenient to convert between efficient, read-only data objects and mutable data objects.

NSData's two primitive methods- bytesbytes and length-provide the basis for all of the other methods in the interface. The bytesbytes method returns a pointer to the bytes contained in the data object. length returns the number of bytes contained in the data object.

To extract a data object that contains a subset of the bytes in another data object, use the subdataWithRange method. To determine if two data objects are equal, use the isEqualToData method, which does a byte-for-byte comparison.

The writeToURL method lets you write the contents of a data object to a location on the Internet.


Adopted Protocols


NSCoding
- encodeWithCoder:
- initWithCoder:

Method Types


Constructors
NSData
Accessing data
bytes
subdataWithRange
Testing data
isEqualToData
length
Storing data
writeToURL

Constructors


NSData

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

Creates a data object with length bytes from the buffer bytes, starting at start .

public NSData(byte[] bytes)

Creates a data object with all the data in the buffer bytes.

public NSData(java.io.File aFile)

Creates a data object with the data from the file specified by aFile.

public NSData()

Creates an empty data object. This method is declared primarily for the use of mutable subclasses of NSData.

public NSData(java.net.URL aURL)

Creates a data object with the data from the location specified by aURL.

public NSData(NSData aData)

Creates a data object containing the contents of another data object, aData.

Static Methods



dataWithContentsOfMappedFile

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

Creates and returns a data object from the mapped file specified by file. 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

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

Returns a byte array of length bytes from the data object's contents starting at start.



isEqualToData

public boolean isEqualToData (NSData otherData)

Compares the receiving data object to otherData. 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

public int length()

Returns the number of bytes contained in the receiver.



subdataWithRange

public NSData subdataWithRange(NSRange range)

Returns a data object containing a copy of the receiver's bytes that fall within the limits specified by range. If range isn't within the receiver's range of bytes, an NSRangeException is thrown.

For example, the following code excerpt initializes a data object, data2, to contain a sub-range 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

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

Writes the bytes in the receiver to the location specified by aURL. If flag is true, the data is written to a backup file and then, assuming no errors occur, the backup file is renamed to the specified name. Otherwise, the data is written directly to the specified location. If flag is true and the location doesn't support atomic writing, the method fails and nothing is written.

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




[Previous] [Next]