Up

NSData class reference

Authors

Andrew Kachites McCallum (mccallum@gnu.ai.mit.edu)
Richard Frith-Macdonald (richard@brainstorm.co.uk)

Version: 1.143

Date: 2004/01/30 11:30:56

Copyright: (C) 1995, 1996, 1997, 2000, 2002 Free Software Foundation, Inc.


Contents -

  1. Software documentation for the NSData class
  2. Software documentation for the NSMutableData class
  3. Software documentation for the NSData(GNUstepExtensions) category
  4. Software documentation for the NSData(GSCategories) category
  5. Software documentation for the NSMutableData(GNUstepExtensions) category

Software documentation for the NSData class

NSData : NSObject

Declared in:
Foundation/NSData.h
Conforms to:
NSCoding
NSCopying
NSMutableCopying
Standards:

Description forthcoming.

Method summary

data

+ (id) data;

Returns an empty data object.


dataWithBytes:length:

+ (id) dataWithBytes: (const void*)bytes length: (unsigned int)length;

Returns an autoreleased data object containing data copied from bytes and with the specified length. Invokes -initWithBytes:length:


dataWithBytesNoCopy:length:

+ (id) dataWithBytesNoCopy: (void*)bytes length: (unsigned int)length;

Returns an autoreleased data object encapsulating the data at bytes and with the specified length. Invokes -initWithBytesNoCopy:length:freeWhenDone: with YES


dataWithBytesNoCopy:length:freeWhenDone:

+ (id) dataWithBytesNoCopy: (void*)aBuffer length: (unsigned int)bufferSize freeWhenDone: (BOOL)shouldFree;

Returns an autoreleased data object encapsulating the data at bytes and with the specified length. Invokes -initWithBytesNoCopy:length:freeWhenDone:


dataWithContentsOfFile:

+ (id) dataWithContentsOfFile: (NSString*)path;

Returns a data object encapsulating the contents of the specified file. Invokes -initWithContentsOfFile:


dataWithContentsOfMappedFile:

+ (id) dataWithContentsOfMappedFile: (NSString*)path;

Returns a data object encapsulating the contents of the specified file mapped directly into memory. Invokes -initWithContentsOfMappedFile:


dataWithContentsOfURL:

+ (id) dataWithContentsOfURL: (NSURL*)url;

Retrieves the information at the specified url and returns an NSData instance encapsulating it.


dataWithData:

+ (id) dataWithData: (NSData*)data;

Returns an autoreleased instance initialised by copying the contents of data.


bytes

- (const void*) bytes;
Subclasses should override this method.

Returns a pointer to the data encapsulated by the receiver.


description

- (NSString*) description;

Description forthcoming.


deserializeAlignedBytesLengthAtCursor:

- (unsigned int) deserializeAlignedBytesLengthAtCursor: (unsigned int*)cursor;

Description forthcoming.


deserializeBytes:length:atCursor:

- (void) deserializeBytes: (void*)buffer length: (unsigned int)bytes atCursor: (unsigned int*)cursor;

Description forthcoming.


deserializeDataAt:ofObjCType:atCursor:context:

- (void) deserializeDataAt: (void*)data ofObjCType: (const char*)type atCursor: (unsigned int*)cursor context: (id<NSObjCTypeSerializationCallBack>)callback;

Description forthcoming.


deserializeIntAtCursor:

- (int) deserializeIntAtCursor: (unsigned int*)cursor;

Description forthcoming.


deserializeIntAtIndex:

- (int) deserializeIntAtIndex: (unsigned int)index;

Description forthcoming.


deserializeInts:count:atCursor:

- (void) deserializeInts: (int*)intBuffer count: (unsigned int)numInts atCursor: (unsigned int*)cursor;

Description forthcoming.


deserializeInts:count:atIndex:

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

Description forthcoming.


getBytes:

- (void) getBytes: (void*)buffer;

Copies the contents of the memory encapsulated by the receiver into the specified buffer. The buffer must be large enough to contain -length bytes of data... if it isn't then a crash is likely to occur.
Invokes -getBytes:range: with the range set to the whole of the receiver.


getBytes:length:

- (void) getBytes: (void*)buffer length: (unsigned int)length;

Copies length bytes of data from the memory encapsulated by the receiver into the specified buffer. The buffer must be large enough to contain length bytes of data... if it isn't then a crash is likely to occur.
Invokes -getBytes:range: with the range set to iNSMakeRange(0, length)


getBytes:range:

- (void) getBytes: (void*)buffer range: (NSRange)aRange;

Copies data from the memory encapsulated by the receiver (in the range specified by aRange) into the specified buffer.
The buffer must be large enough to contain the data... if it isn't then a crash is likely to occur.
If aRange specifies a range which does not entirely lie within the receiver, an exception is raised.


initWithBytes:length:

- (id) initWithBytes: (const void*)aBuffer length: (unsigned int)bufferSize;

Makes a copy of bufferSize bytes of data at aBuffer, and passes it to -initWithBytesNoCopy:length:freeWhenDone: with a YES argument in order to initialise the receiver. Returns the result.


initWithBytesNoCopy:length:

- (id) initWithBytesNoCopy: (void*)aBuffer length: (unsigned int)bufferSize;

Invokes -initWithBytesNoCopy:length:freeWhenDone: with the last argument set to YES. Returns the resulting initialised data object (which may not be the receiver).


initWithBytesNoCopy:length:freeWhenDone:

- (id) initWithBytesNoCopy: (void*)aBuffer length: (unsigned int)bufferSize freeWhenDone: (BOOL)shouldFree;
This is a designated initialiser for the class.
Subclasses should override this method.

Initialises the receiver.
The value of aBuffer is a pointer to something to be stored.
The value of bufferSize is the number of bytes to use.
The value of shouldFree specifies whether the receiver should attempt to free the memory pointer to by aBuffer when the receiver is deallocated ... ie. it says whether the receiver owns the memory. Supplying the wrong value here will lead to memory leaks or crashes.


initWithContentsOfFile:

- (id) initWithContentsOfFile: (NSString*)path;

Initialises the receiver with the contents of the specified file.
Returns the resulting object.
Returns nil if the file does not exist or can not be read for some reason.


initWithContentsOfMappedFile:

- (id) initWithContentsOfMappedFile: (NSString*)path;

Description forthcoming.


initWithContentsOfURL:

- (id) initWithContentsOfURL: (NSURL*)url;

Description forthcoming.


initWithData:

- (id) initWithData: (NSData*)data;

Description forthcoming.


isEqualToData:

- (BOOL) isEqualToData: (NSData*)other;

Returns a boolean value indicating if the receiver and other contain identical data (using a byte by byte comparison). Assumes that the other object is an NSData instance... may raise an exception if it isn't.


length

- (unsigned int) length;
Subclasses should override this method.

Returns the number of bytes of data encapsulated by the receiver.


subdataWithRange:

- (NSData*) subdataWithRange: (NSRange)aRange;

Returns an NSData instance encapsulating the memory from the reciever specified by the range aRange.
If aRange specifies a range which does not entirely lie within the receiver, an exception is raised.


writeToFile:atomically:

- (BOOL) writeToFile: (NSString*)path atomically: (BOOL)useAuxiliaryFile;

Writes a copy of the data encapsulated by the receiver to a file at path. If the useAuxiliaryFile flag is YES, this writes to a temporary file and then renames that to the file at path, thus ensuring that path exists and does not contain partially written data at any point.

On success returns YES, on failure returns NO.


writeToURL:atomically:

- (BOOL) writeToURL: (NSURL*)anURL atomically: (BOOL)flag;

Writes a copy of the contents of the receiver to the specified URL.


Software documentation for the NSMutableData class

NSMutableData : NSData

Declared in:
Foundation/NSData.h
Standards:

Description forthcoming.

Method summary

dataWithCapacity:

+ (id) dataWithCapacity: (unsigned int)numBytes;

Description forthcoming.


dataWithLength:

+ (id) dataWithLength: (unsigned int)length;

Description forthcoming.


appendBytes:length:

- (void) appendBytes: (const void*)aBuffer length: (unsigned int)bufferSize;

Description forthcoming.


appendData:

- (void) appendData: (NSData*)other;

Description forthcoming.


increaseLengthBy:

- (void) increaseLengthBy: (unsigned int)extraLength;

Description forthcoming.


initWithCapacity:

- (id) initWithCapacity: (unsigned int)capacity;

Description forthcoming.


initWithLength:

- (id) initWithLength: (unsigned int)length;

Description forthcoming.


mutableBytes

- (void*) mutableBytes;

Returns a pointer to the data storage of the receiver.
Modifications to the memory pointed to by this pointer will change the contents of the object. It is important that your code should not try to modify the memory beyond the number of bytes given by the -length method.

NB. if the object is released, or any method that changes its size or content is called, then the pointer previously returned by this method may cease to be valid.

This is a 'primitive' method... you need to implement it if you write a subclass of NSMutableData.


replaceBytesInRange:withBytes:

- (void) replaceBytesInRange: (NSRange)aRange withBytes: (const void*)bytes;

Replaces the bytes of data in the specified range with a copy of the new bytes supplied.
If the location of the range specified lies beyond the end of the data ( [self length] < range.location) then a range exception is raised.
Otherwise, if the range specified extends beyond the end of the data, then the size of the data is increased to accomodate the new bytes.


replaceBytesInRange:withBytes:length:

- (void) replaceBytesInRange: (NSRange)aRange withBytes: (const void*)bytes length: (unsigned int)length;

Replace the content of the receiver which lies in aRange with the specified length of data from the buffer pointed to by bytes.
The size of the receiver is adjusted to allow for the change.


resetBytesInRange:

- (void) resetBytesInRange: (NSRange)aRange;

Description forthcoming.


serializeAlignedBytesLength:

- (void) serializeAlignedBytesLength: (unsigned int)length;

Description forthcoming.


serializeDataAt:ofObjCType:context:

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

Description forthcoming.


serializeInt:

- (void) serializeInt: (int)value;

Description forthcoming.


serializeInt:atIndex:

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

Description forthcoming.


serializeInts:count:

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

Description forthcoming.


serializeInts:count:atIndex:

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

Description forthcoming.


setData:

- (void) setData: (NSData*)data;

Description forthcoming.


setLength:

- (void) setLength: (unsigned int)size;

Sets the length of the NSMutableData object. If the length is increased, the newly allocated data area is filled with zero bytes.

This is a 'primitive' method... you need to implement it if you write a subclass of NSMutableData.


Software documentation for the NSData(GNUstepExtensions) category

NSData(GNUstepExtensions)

Declared in:
Foundation/NSData.h
Standards:

Description forthcoming.

Method summary

dataWithSharedBytes:length:

+ (id) dataWithSharedBytes: (const void*)bytes length: (unsigned int)length;

Description forthcoming.


dataWithShmID:length:

+ (id) dataWithShmID: (int)anID length: (unsigned int)length;

Description forthcoming.


deserializeTypeTag:andCrossRef:atCursor:

- (void) deserializeTypeTag: (unsigned char*)tag andCrossRef: (unsigned int*)ref atCursor: (unsigned int*)cursor;

Description forthcoming.


Software documentation for the NSData(GSCategories) category

NSData(GSCategories)

Declared in:
Foundation/NSData.h
Standards:

Description forthcoming.

Method summary

hexadecimalRepresentation

- (NSString*) hexadecimalRepresentation;

Description forthcoming.


initWithHexadecimalRepresentation:

- (id) initWithHexadecimalRepresentation: (NSString*)string;

Description forthcoming.


md5Digest

- (NSData*) md5Digest;

Description forthcoming.


Software documentation for the NSMutableData(GNUstepExtensions) category

NSMutableData(GNUstepExtensions)

Declared in:
Foundation/NSData.h
Standards:

Description forthcoming.

Method summary

capacity

- (unsigned int) capacity;

Description forthcoming.


serializeTypeTag:

- (void) serializeTypeTag: (unsigned char)tag;

Description forthcoming.


serializeTypeTag:andCrossRef:

- (void) serializeTypeTag: (unsigned char)tag andCrossRef: (unsigned int)xref;

Description forthcoming.


setCapacity:

- (id) setCapacity: (unsigned int)newCapacity;

Description forthcoming.


shmID

- (int) shmID;

Description forthcoming.



Up