Copyright ã1994 by NeXT Computer, Inc.  All Rights Reserved.

NSBTreeCursor

Inherits From:	NSObject 

Conforms To:	NSObject (NSObject)

Declared In:	Foundation/NSByteStore.h 

Class Description

An NSBTreeCursor provides access to the keys and values stored in an NSBTreeBlock. It's essentially a pointer into the NSBTreeBlock's key space, and may be positioned by key to perform operations on the value stored at a given location. 

An NSBTreeCursor works with a single NSBTreeBlock, but several NSBTreeCursors may access the same NSBTreeBlock and be positioned independently without conflict. See the NSBTreeBlock class specification for more information on concurrent access with multiple NSBTreeCursors.

Positioning the Cursor and Accessing Data

NSBTreeCursor contains methods that walk through the key/value pairs in the NSBTreeBlock. The method moveCursorToFirstKey will point the cursor to the first key in the key space, and you can use moveCursorToNextKey to essentially walk through all of the keys in the NSBTreeBlock. To point the cursor at a specific key/value pair, use moveCursorToKey:. This method returns YES if it finds the key and NO if it does not. If moveCursorToKey: returns NO, it still points the cursor at that key. For example, suppose the keys into the key space are integer IDs divisible by 10, and you call moveCursorToKey: with 54 as the key. (In reality, keys must be NSData objects, but to make this example more clear, it uses integers.) There is no key 54, so moveCursorToKey: returns NO, but the cursor points to where key 54 would be if it existed. A subsequent call to moveCursorToNextKey would point the cursor at key 60. The method isOnKey tells you if the cursor is pointing to a valid key.

To insert a key/value pair into the NSBTreeBlock, you take advantage of the moveCursorToKey: method's return value. Send moveCursorToKey: with the key you want to insert. If if returns NO, send writeValue: with the value you want to insert. The key/value pair will be inserted.

A cursor at a position with no key can't access a value there. If the cursor is asked to access a value anyway, it has two options: try to find a value or indicate that it can't access one. Where it makes sense, a cursor should try to find a value by sliding forward in the key space to the next actual key. When this isn't possible or desirable, the cursor should indicate that it can't find or access a value, by raising the NSBTreeNoValueException exception. In the previous example, if the cursor is asked to retrieve the information at key 54, the cursor will slide forward and return the information at key 60. At this point, you can use the cursorKey method to find out which key the cursor is pointing to. cursorKey will return 60 to let you know that the cursor has slid forward.

A cursor cannot write inside (with the method writeValue:range:) or remove the value (with the method removeValue) at a location where there is no key. Since there is no value, and since writing into part of a value or removing it would change data that the programmer probably doesn't want altered (namely, the value for the next actual key), the NSBTreeCursor will indicate that there is no value to write into by raising the NSBTreeNoValueException exception.

Working With the NSByteStore

Since NSBTreeBlock is an NSByteStore client, the transaction model of NSByteStore applies to changes made to the contents of an NSBTreeBlock. In particular, you must send the commitTransaction message to the NSByteStore to have changes to the NSBTreeBlock take effect (and be flushed to disk for a file-based store). If an NSBTreeBlock is used on a strictly read-only basis, transaction management can be ignored. 

After an abortTransaction, a cursor may be pointing to a key that no longer exists. Therefore, you must reposition each cursor using one of the moveCursor... methods after an abortTransaction.

Creating and Initializing a New NSBTreeCursor Instance 

+ (NSBTreeCursor *)bTreeCursorWithBTree:(NSBTreeBlock *)aBTree
	Returns a new NSBTreeCursor instance and associates it with the aBTree object.

- (id)initWithBTree:(NSBTreeBlock *)aBTree	Initializes a newly allocated NSBTreeCursor instance and associates it with the aBTree object.

Obtaining Information about the NSBTreeBlock

- (NSBTreeBlock *)btree	Returns the NSBTreeBlock with which the NSBTreeCursor is associated.

Positioning the Cursor

- (BOOL)moveCursorToFirstKey	Positions the cursor at the first key in the key space.

- (BOOL)moveCursorToLastKey	Positions the cursor at the last key in the key space.

- (BOOL)moveCursorToNextKey	Positions the cursor at the next key in the key space. If the cursor is at the last key, it does not move.

- (BOOL)moveCursorToPreviousKey	Positions the cursor at the previous key in the key space. If the cursor is at the first key, it does not move.

- (BOOL)moveCursorToKey:(NSData *)key	Positions the cursor at key. 

-(BOOL)isOnKey	Returns YES if the cursor matched a key on the last operation.

Accessing the Data

- (NSData *)cursorKey	Returns the key that the cursor is pointing to.

- (NSData *)cursorValue	Returns the value associated with the key that the cursor is pointing to.

- (NSData *)cursorValueWithRange:(NSRange)range
	Returns a portion, specified by range, of the value associated with the key that the cursor is pointing to.

Changing the Data in the NSBTreeBlock

- (BOOL)writeValue:(NSData *)value	Replaces the value associated with the key that the cursor is pointing to, if the key exists. If the key does not exist, it creates a new key/value pair using the key that the cursor is currently pointing to and value as the value. This method returns YES if it inserted a new key/value pair and NO if it overwrote an existing value.

- (void)writeValue:(NSData *)value 	Replaces a portion, starting at index, of the value associated 
atIndex:(unsigned)index		with the key that the cursor is pointing to. If the key does not exist, the NSBTreeNoValueException exception is raised.

- (void)removeValue	Deletes the key/value pair from the NSBTreeBlock. If the key/value pair already does not exist, the NSBTreeNoValueException exception is raised.