Class: NSData

Inherits:
NSObject show all

Overview

NSData and its mutable 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.

Direct Known Subclasses

NSMutableData

Class Method Summary (collapse)

Instance Method Summary (collapse)

Methods inherited from NSObject

#!, #!=, #!~, #, #==, #===, #=~, #Rational, #__callee__, #__method__, #__send__, #__type__, `, alloc, allocWithZone:, #autoContentAccessingProxy, autoload, autoload?, autorelease_pool, #awakeAfterUsingCoder:, binding, block_given?, caller, cancelPreviousPerformRequestsWithTarget:, cancelPreviousPerformRequestsWithTarget:selector:object:, catch, class, classFallbacksForKeyedArchiver, #classForCoder, #classForKeyedArchiver, classForKeyedUnarchiver, #clone, conformsToProtocol:, #copy, copyWithZone:, #dealloc, #define_singleton_method, description, display, #doesNotRecognizeSelector:, #dup, #enum_for, #eql?, #equal?, #extend, fail, #finalize, format, #forwardInvocation:, #forwardingTargetForSelector:, framework, #freeze, #frozen?, getpass, gets, global_variables, #init, initialize, #initialize_clone, #initialize_copy, #initialize_dup, #inspect, instanceMethodForSelector:, instanceMethodSignatureForSelector:, #instance_eval, #instance_exec, #instance_of?, #instance_variable_defined?, #instance_variable_get, #instance_variable_set, #instance_variables, instancesRespondToSelector:, isSubclassOfClass:, #is_a?, iterator?, #kind_of?, lambda, load, load_bridge_support_file, load_plist, local_variables, loop, #method, #methodForSelector:, #methodSignatureForSelector:, #methods, #mutableCopy, mutableCopyWithZone:, new, #nil?, open, p, #performSelector:onThread:withObject:waitUntilDone:, #performSelector:onThread:withObject:waitUntilDone:modes:, #performSelector:withObject:afterDelay:, #performSelector:withObject:afterDelay:inModes:, #performSelectorInBackground:withObject:, #performSelectorOnMainThread:withObject:waitUntilDone:, #performSelectorOnMainThread:withObject:waitUntilDone:modes:, print, printf, #private_methods, proc, #protected_methods, #public_method, #public_methods, #public_send, putc, puts, raise, rand, readline, readlines, #replacementObjectForCoder:, #replacementObjectForKeyedArchiver:, require, resolveClassMethod:, resolveInstanceMethod:, #respond_to?, #respond_to_missing?, select, #send, setVersion:, #singleton_methods, sprintf, srand, superclass, #taint, #tainted?, #tap, test, throw, #to_plist, #to_s, trace_var, trap, #trust, #untaint, untrace_var, #untrust, #untrusted?, version

Constructor Details

This class inherits a constructor from NSObject

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class NSObject

Class Method Details

+ (Object) data

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

Returns:

  • (Object) —

    An empty data object.

+ (Object) dataWithBytes(bytes, length:length)

Creates and returns a data object containing a given number of bytes copied from a given buffer.

Parameters:

  • bytes (Object) —

    A buffer containing data for the new object.

  • length (Integer) —

    The number of bytes to copy from bytes. This value must not exceed the length of bytes.

Returns:

  • (Object) —

    A data object containing length bytes copied from the buffer bytes. Returns nil if the data object could not be created.

+ (Object) dataWithBytesNoCopy(bytes, length:length)

Creates and returns a data object that holds length bytes from the buffer bytes. The returned object takes ownership of the bytes pointer and frees it on deallocation. Therefore, bytes must point to a memory block allocated with malloc.

Parameters:

  • bytes (Object) —

    A buffer containing data for the new object. bytes must point to a memory block allocated with malloc.

  • length (Integer) —

    The number of bytes to hold from bytes. This value must not exceed the length of bytes.

Returns:

  • (Object) —

    A data object that holds length bytes from the buffer bytes. Returns nil if the data object could not be created.

+ (Object) dataWithBytesNoCopy(bytes, length:length, freeWhenDone:freeWhenDone)

Creates and returns a data object that holds a given number of bytes from a given buffer.

Parameters:

  • bytes (Object) —

    A buffer containing data for the new object. If freeWhenDone is YES, bytes must point to a memory block allocated with malloc.

  • length (Integer) —

    The number of bytes to hold from bytes. This value must not exceed the length of bytes.

  • freeWhenDone (Boolean) —

    If YES, the returned object takes ownership of the bytes pointer and frees it on deallocation.

Returns:

  • (Object) —

    A data object that holds length bytes from the buffer bytes. Returns nil if the data object could not be created.

+ (Object) dataWithContentsOfFile(path)

Creates and returns a data object by reading every byte from the file specified by a given path. This method is equivalent to dataWithContentsOfFile:options:error: with no options. If you need to know what was the reason for failure, use dataWithContentsOfFile:options:error:.A sample using this method can be found in “Working With Binary Data”.

Parameters:

  • path (String) —

    The absolute path of the file from which to read data.

Returns:

  • (Object) —

    A data object by reading every byte from the file specified by path. Returns nil if the data object could not be created.

+ (Object) dataWithContentsOfFile(path, options:mask, error:errorPtr)

Creates and returns a data object by reading every byte from the file specified by a given path.

Parameters:

  • path (String) —

    The absolute path of the file from which to read data.

  • mask (NSDataReadingOptions) —

    A mask that specifies options for reading the data. Constant components are described in “NSDataReadingOptions”.

  • errorPtr (Pointer) —

    If an error occurs, upon return contains an NSError object that describes the problem.

Returns:

  • (Object) —

    A data object by reading every byte from the file specified by path. Returns nil if the data object could not be created.

+ (Object) dataWithContentsOfURL(aURL)

Returns a data object containing the data from the location specified by a given URL. If you need to know what was the reason for failure, use dataWithContentsOfURL:options:error:.

Parameters:

  • aURL (NSURL) —

    The URL from which to read data.

Returns:

  • (Object) —

    A data object containing the data from the location specified by aURL. Returns nil if the data object could not be created.

+ (Object) dataWithContentsOfURL(aURL, options:mask, error:errorPtr)

Creates and returns a data object containing the data from the location specified by aURL.

Parameters:

  • aURL (NSURL) —

    The URL from which to read data.

  • mask (NSDataReadingOptions) —

    A mask that specifies options for reading the data. Constant components are described in “NSDataReadingOptions”.

  • errorPtr (Pointer) —

    If there is an error reading in the data, upon return contains an NSError object that describes the problem.

Returns:

+ (Object) dataWithData(aData)

Creates and returns a data object containing the contents of another data object.

Parameters:

  • aData (NSData) —

    A data object.

Returns:

  • (Object) —

    A data object containing the contents of aData. Returns nil if the data object could not be created.

Instance Method Details

- (Object) bytes

Returns a pointer to the receiver’s contents. If the length of the receiver is 0, this method returns nil.

Returns:

  • (Object) —

    A read-only pointer to the receiver’s contents.

- (String) description

Returns an NSString object that contains a hexadecimal representation of the receiver’s contents.

Returns:

  • (String) —

    An NSString object that contains a hexadecimal representation of the receiver’s contents in NSData property list format.

- (Object) getBytes(buffer, length:length)

Copies a number of bytes from the start of the receiver's data into a given buffer. The number of bytes copied is the smaller of the length parameter and the length of the data encapsulated in the object.

Parameters:

  • buffer (Object) —

    A buffer into which to copy data.

  • length (Integer) —

    The number of bytes from the start of the receiver's data to copy to buffer.

Returns:

- (Object) getBytes(buffer, range:range)

Copies a range of bytes from the receiver’s data into a given buffer. If range isn’t within the receiver’s range of bytes, an NSRangeException is raised.

Parameters:

  • buffer (Object) —

    A buffer into which to copy data.

  • range (NSRange) —

    The range of bytes in the receiver’s data to copy to buffer. The range must lie within the range of bytes of the receiver’s data.

Returns:

- (Object) initWithBytes(bytes, length:length)

Returns a data object initialized by adding to it a given number of bytes of data copied from a given buffer. A data object initialized by adding to it length bytes of data copied from the buffer bytes. The returned object might be different than the original receiver.

Returns:

- (Object) initWithBytesNoCopy(bytes, length:length)

Returns a data object initialized by adding to it a given number of bytes of data from a given buffer. The returned object takes ownership of the bytes pointer and frees it on deallocation. Therefore, bytes must point to a memory block allocated with malloc.

Parameters:

  • bytes (Object) —

    A buffer containing data for the new object. bytes must point to a memory block allocated with malloc.

  • length (Integer) —

    The number of bytes to hold from bytes. This value must not exceed the length of bytes.

Returns:

  • (Object) —

    A data object initialized by adding to it length bytes of data from the buffer bytes. The returned object might be different than the original receiver.

- (Object) initWithBytesNoCopy(bytes, length:length, freeWhenDone:flag)

Initializes a newly allocated data object by adding to it length bytes of data from the buffer bytes.

Parameters:

  • bytes (Object) —

    A buffer containing data for the new object. If flag is YES, bytes must point to a memory block allocated with malloc.

  • length (Integer) —

    The number of bytes to hold from bytes. This value must not exceed the length of bytes.

  • flag (Boolean) —

    If YES, the returned object takes ownership of the bytes pointer and frees it on deallocation.

Returns:

- (Object) initWithContentsOfFile(path)

Returns a data object initialized by reading into it the data from the file specified by a given path. This method is equivalent to initWithContentsOfFile:options:error: with no options.

Parameters:

  • path (String) —

    The absolute path of the file from which to read data.

Returns:

  • (Object) —

    A data object initialized by reading into it the data from the file specified by path. The returned object might be different than the original receiver.

- (Object) initWithContentsOfFile(path, options:mask, error:errorPtr)

Returns a data object initialized by reading into it the data from the file specified by a given path.

Parameters:

  • path (String) —

    The absolute path of the file from which to read data.

  • mask (NSDataReadingOptions) —

    A mask that specifies options for reading the data. Constant components are described in “NSDataReadingOptions”.

  • errorPtr (Pointer) —

    If an error occurs, upon return contains an NSError object that describes the problem.

Returns:

  • (Object) —

    A data object initialized by reading into it the data from the file specified by path. The returned object might be different than the original receiver.

- (Object) initWithContentsOfURL(aURL)

Initializes a newly allocated data object initialized with the data from the location specified by aURL.

Parameters:

  • aURL (NSURL) —

    The URL from which to read data

Returns:

  • (Object) —

    An NSData object initialized with the data from the location specified by aURL. The returned object might be different than the original receiver.

- (Object) initWithContentsOfURL(aURL, options:mask, error:errorPtr)

Returns a data object initialized with the data from the location specified by a given URL.

Parameters:

  • aURL (NSURL) —

    The URL from which to read data.

  • mask (NSDataReadingOptions) —

    A mask that specifies options for reading the data. Constant components are described in “NSDataReadingOptions”.

  • errorPtr (Pointer) —

    If there is an error reading in the data, upon return contains an NSError object that describes the problem.

Returns:

  • (Object) —

    A data object initialized with the data from the location specified by aURL. The returned object might be different than the original receiver.

- (Object) initWithData(data)

Returns a data object initialized with the contents of another data object.

Parameters:

  • data (NSData) —

    A data object.

Returns:

  • (Object) —

    A data object initialized with the contents data. The returned object might be different than the original receiver.

- (Boolean) isEqualToData(otherData)

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

Parameters:

  • otherData (NSData) —

    The data object with which to compare the receiver.

Returns:

  • (Boolean) —

    YES if the contents of otherData are equal to the contents of the receiver, otherwise NO.

- (Integer) length

Returns the number of bytes contained in the receiver.

Returns:

  • (Integer) —

    The number of bytes contained in the receiver.

- (NSRange) rangeOfData(dataToFind, options:mask, range:searchRange)

Finds and returns the range of the first occurrence of the given data, within the given range, subject to given options.

Parameters:

  • dataToFind (NSData) —

    The data for which to search. This value must not be nil.Important: Raises an NSInvalidArgumentException if dataToFind is nil.

  • mask (NSDataSearchOptions) —

    A mask specifying search options. The “NSDataSearchOptions” options may be specified singly or by combining them with the C bitwise OR operator.

  • searchRange (NSRange) —

    The range within the receiver in which to search for dataToFind. If this range is not within the receiver’s range of bytes, an NSRangeException raised.

Returns:

  • (NSRange) —

    An NSRange structure giving the location and length of dataToFind within searchRange, modulo the options in mask. The range returned is relative to the start of the searched data, not the passed-in search range. Returns 0 if dataToFind is not found or is empty (@“”).

- (NSData) subdataWithRange(range)

Returns a data object containing a copy of the receiver’s bytes that fall within the limits specified by a given range. If range isn’t within the receiver’s range of bytes, an NSRangeException is raised.A sample using this method can be found in “Working With Binary Data”.

Parameters:

  • range (NSRange) —

    The range in the receiver from which to copy bytes. The range must not exceed the bounds of the receiver.

Returns:

  • (NSData) —

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

- (String) to_str

returns a String object created using the receiver's internal storage.

Returns:

- (Boolean) writeToFile(path, atomically:flag)

Writes the bytes in the receiver to the file specified by a given path.

Parameters:

  • path (String) —

    The location to which to write the receiver’s bytes. If path contains a tilde (~) character, you must expand it with stringByExpandingTildeInPath before invoking this method.

  • atomically (Boolean) —

    If YES, the data is written to a backup file, and then—assuming no errors occur—the backup file is renamed to the name specified by path; otherwise, the data is written directly to path.

Returns:

  • (Boolean) —

    YES if the operation succeeds, otherwise NO.

- (Boolean) writeToFile(path, options:mask, error:errorPtr)

Writes the bytes in the receiver to the file specified by a given path.

Parameters:

  • path (String) —

    The location to which to write the receiver’s bytes.

  • mask (NSDataWritingOptions) —

    A mask that specifies options for writing the data. Constant components are described in “NSDataWritingOptions”.

  • errorPtr (Pointer) —

    If there is an error writing out the data, upon return contains an NSError object that describes the problem.

Returns:

  • (Boolean) —

    YES if the operation succeeds, otherwise NO.

- (Boolean) writeToURL(aURL, atomically:atomically)

Writes the bytes in the receiver to the location specified by aURL. Since at present only file:// URLs are supported, there is no difference between this method and writeToFile:atomically:, except for the type of the first argument.

Parameters:

  • aURL (NSURL) —

    The location to which to write the receiver’s bytes. Only file:// URLs are supported.

  • atomically (Boolean) —

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

Returns:

  • (Boolean) —

    YES if the operation succeeds, otherwise NO.

- (Boolean) writeToURL(aURL, options:mask, error:errorPtr)

Writes the bytes in the receiver to the location specified by a given URL. Since at present only file:// URLs are supported, there is no difference between this method and writeToFile:options:error:, except for the type of the first argument.

Parameters:

  • aURL (NSURL) —

    The location to which to write the receiver’s bytes.

  • mask (NSDataWritingOptions) —

    A mask that specifies options for writing the data. Constant components are described in “NSDataWritingOptions”.

  • errorPtr (Pointer) —

    If there is an error writing out the data, upon return contains an NSError object that describes the problem.

Returns:

  • (Boolean) —

    YES if the operation succeeds, otherwise NO.