HFByteArray Class Reference

The principal Model class for HexFiend's MVC architecture. More...

Inheritance diagram for HFByteArray:

HFAttributedByteArray HFBTreeByteArray HFFullMemoryByteArray

List of all members.

Public Member Functions

Accessing raw data
(unsigned long long) - length
(void) - copyBytes:range:
Accessing byte slices
Methods to access the byte slices underlying the HFByteArray.

(NSArray *) - byteSlices
(NSEnumerator *) - byteSliceEnumerator
(HFByteSlice *) - sliceContainingByteAtIndex:beginningOffset:
Modifying the byte array
Methods to modify the given byte array.

(void) - insertByteSlice:inRange:
(void) - insertByteArray:inRange:
(void) - deleteBytesInRange:
(HFByteArray *) - subarrayWithRange:
Write locking and generation count
Methods to lock and query the lock that prevents writes.

(void) - incrementChangeLockCounter
(void) - decrementChangeLockCounter
(BOOL) - changesAreLocked
(void) - incrementGenerationOrRaiseIfLockedForSelector:
(NSUInteger) - changeGenerationCount
(unsigned long long) - indexOfBytesEqualToBytes:inRange:searchingForwards:trackingProgress:

Detailed Description

HFByteArray implements the Model portion of HexFiend.framework. It is logically a mutable, resizable array of bytes, with a 64 bit length. It is somewhat analagous to a 64 bit version of NSMutableData, except that it is designed to enable efficient (faster than O(n)) implementations of insertion and deletion.

HFByteArray, being an abstract class, will raise an exception if you attempt to instantiate it directly. For most uses, instantiate HFBTreeByteArray instead, with the usual [[class alloc] init].

HFByteArray also exposes itself as an array of HFByteSlices, which are logically immutable arrays of bytes. which is useful for operations such as file saving that need to access the underlying byte slices.

HFByteArray contains a generation count, which is incremented whenever the HFByteArray changes (to allow caches to be implemented on top of it). It also includes the notion of locking: a locked HFByteArray will raise an exception if written to, but it may still be read.

ByteArrays have the usual threading restrictions for non-concurrent data structures. It is safe to read an HFByteArray concurrently from multiple threads. It is not safe to read an HFByteArray while it is being modified from another thread, nor is it safe to modify one simultaneously from two threads.

HFByteArray is an abstract class. It will raise an exception if you attempt to instantiate it directly. The principal concrete subclass is HFBTreeByteArray.

Member Function Documentation

- (unsigned long long) length  

Returns the length of the HFByteArray as a 64 bit unsigned long long. This is an abstract method that concrete subclasses must override.

- (void) copyBytes: (unsigned char *)  dst
range: (HFRange range 

Copies a range of bytes into a buffer. This is an abstract method that concrete subclasses must override.

- (NSArray *) byteSlices  

Returns the contents of the receiver as an array of byte slices. This is an abstract method that concrete subclasses must override.

- (NSEnumerator *) byteSliceEnumerator  

Returns an NSEnumerator representing the byte slices of the receiver. This is implemented as enumerating over the result of -byteSlices, but subclasses can override this to be more efficient.

- (HFByteSlice *) sliceContainingByteAtIndex: (unsigned long long)  offset
beginningOffset: (unsigned long long *)  actualOffset 

Returns the byte slice containing the byte at the given index, and the actual offset of this slice.

- (void) insertByteSlice: (HFByteSlice *)  slice
inRange: (HFRange lrange 

Insert an HFByteSlice in the given range. The maximum value of the range must not exceed the length of the subarray. The length of the given slice is not required to be equal to length of the range - in other words, this method may change the length of the receiver. This is an abstract method that concrete subclasses must override.

- (void) insertByteArray: (HFByteArray *)  array
inRange: (HFRange lrange 

Insert an HFByteArray in the given range. This is implemented via calling insertByteSlice:inRange: with the byte slices from the given byte array.

- (void) deleteBytesInRange: (HFRange range  

Delete bytes in the given range. This is implemented on the base class by creating an empty byte array and inserting it in the range to be deleted, via insertByteSlice:inRange:.

- (HFByteArray *) subarrayWithRange: (HFRange range  

Returns a new HFByteArray containing the given range. This is an abstract method that concrete subclasses must override.

- (void) incrementChangeLockCounter  

Increment the change lock. Until the change lock reaches 0, all modifications to the receiver will raise an exception.

- (void) decrementChangeLockCounter  

Decrement the change lock. If the change lock reaches 0, modifications will be allowed again.

- (BOOL) changesAreLocked  

Query if the changes are locked. This method is KVO compliant.

- (void) incrementGenerationOrRaiseIfLockedForSelector: (SEL)  sel  

Increments the generation count, unless the receiver is locked, in which case it raises an exception. All subclasses of HFByteArray should call this method at the beginning of any overridden method that may modify the receiver.

sel The selector that would modify the receiver (e.g. deleteBytesInRange:). This is usually _cmd.

- (NSUInteger) changeGenerationCount  

Return the change generation count. Every change to the ByteArray increments this by one or more. This can be used for caching layers on top of HFByteArray, to known when to expire their cache.

- (unsigned long long) indexOfBytesEqualToBytes: (HFByteArray *)  findBytes
inRange: (HFRange range
searchingForwards: (BOOL)  forwards
trackingProgress: (HFProgressTracker *)  progressTracker 

Searches the receiver for a byte array matching findBytes within the given range, and returns the index that it was found. This is a concrete method on HFByteArray.

findBytes The HFByteArray containing the data to be found (the needle to the receiver's haystack).
range The range of the receiver in which to search. The end of the range must not exceed the receiver's length.
forwards If this is YES, then the first match within the range is returned. Otherwise the last is returned.
progressTracker An HFProgressTracker to allow progress reporting and cancelleation for the search operation.
The index in the receiver of bytes equal to findBytes, or ULLONG_MAX if the byte array was not found (or the operation was cancelled)

The documentation for this class was generated from the following file:

Generated on Thu Dec 8 10:06:35 2011 for HexFiend by  doxygen 1.5.9