This is NSBTreeCursor.rtf in view mode; [Download] [Up]
paperh18648 margl-907 margr0 margt0 margb0 fi0 ri0 ql sb0 f1 fs24 Copyright f3 'e3f1 1994 by NeXT Computer, Inc. All Rights Reserved.
s4 li100 fi0 ri1007 ql f0 b fs36 fs100
fs36 NSBTreeCursor
pard s11 li2872 fi-2771 ri1007 ql tx2872 f1 b0 fs28 fs48
fs28 f0 b fs24 Inherits From:tab b0 fs28 f1 NSObject
fs20
fs28 s6 f0 b fs24 Conforms To:tab b0 fs28 f1 NSObject (NSObject)
fs20
fs28 s7 f0 b fs24 Declared In:tab b0 fs28 f1 Foundation/NSByteStore.h
fs20
fs28 pard s16 li100 fi0 ri1007 ql f0 b fs28 fs20
fs28 Class Description
fs14
fs28 pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 f1 b0 fs2
fs28 An NSBTreeCursor provides access to the keys and values stored in an NSBTreeBlock. It'27s essentially a pointer into the NSBTreeBlock'27s key space, and may be positioned by key to perform operations on the value stored at a given location.
fs16
fs28 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.
fs16
fs28 pard s15 li477 fi0 ri1007 ql f0 b fs24 fs4
fs24 Positioning the Cursor and Accessing Data
pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 f1 b0 fs28 fs16
fs28 NSBTreeCursor contains methods that walk through the key/value pairs in the NSBTreeBlock. The method b moveCursorToFirstKeyb0 will point the cursor to the first key in the key space, and you can use b moveCursorToNextKeyb0 to essentially walk through all of the keys in the NSBTreeBlock. To point the cursor at a specific key/value pair, use b moveCursorToKey:b0 . This method returns YES if it finds the key and NO if it does not. If b moveCursorToKey:b0 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 b moveCursorToKey:b0 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 b moveCursorToKey:b0 returns NO, but the cursor points to where key 54 would be if it existed. A subsequent call to b moveCursorToNextKeyb0 would point the cursor at key 60. The method b isOnKeyb0 tells you if the cursor is pointing to a valid key.
fs16
fs28 To insert a key/value pair into the NSBTreeBlock, you take advantage of the b moveCursorToKey:b0 method'27s return value. Send b moveCursorToKey:b0 with the key you want to insert. If if returns NO, send b writeValue:b0 with the value you want to insert. The key/value pair will be inserted.
fs16
fs28 A cursor at a position with no key can'27t 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'27t 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'27t possible or desirable, the cursor should indicate that it can'27t 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 b cursorKeyb0 method to find out which key the cursor is pointing to. b cursorKeyb0 will return 60 to let you know that the cursor has slid forward.
fs16
fs28 A cursor cannot write inside (with the method b writeValue:range:b0 ) or remove the value (with the method b removeValueb0 ) 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'27t 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.
fs16
fs28 pard s15 li477 fi0 ri1007 ql f0 b fs24 fs4
fs24 Working With the NSByteStore
pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 f1 b0 fs28 fs16
fs28 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 b commitTransactionb0 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.
fs16
fs28 After an b abortTransactionb0 , a cursor may be pointing to a key that no longer exists. Therefore, you must reposition each cursor using one of the b moveCursor...b0 methods after an b abortTransactionb0 .
fs16
fs28 pard s16 li100 fi0 ri1007 ql f0 b fs24
fs28 Creating and Initializing a New NSBTreeCursor Instance
fs14
fs28 pard s8 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 + (NSBTreeCursor *)b bTreeCursorWithBTree:b0 (NSBTreeBlock *)i aBTrei0 e
s9 li7030 fi-6553 fi-5796 tab Returns a new NSBTreeCursor instance and associates it with the i aBTreei0 object.
s8 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 {f3 -} (id)b initWithBTree:b0 (NSBTreeBlock *)i aBTreei0 tab Initializes a newly allocated NSBTreeCursor instance and associates it with the i aBTreei0 object.
pard s16 li100 fi0 ri1007 ql f0 b fs48
fs28 Obtaining Information about the NSBTreeBlock
fs14
fs28 pard s8 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 {f3 -} (NSBTreeBlock *)b btreeb0 tab Returns the NSBTreeBlock with which the NSBTreeCursor is associated.
pard s16 li100 fi0 ri1007 ql f0 b fs48
fs28 Positioning the Cursor
fs14
fs28 pard s8 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 {f3 -} (BOOL)b moveCursorToFirstKeyb0 tab Positions the cursor at the first key in the key space.
fi-6552 fs16
fs28 fi-6552 {f3 -} (BOOL)b moveCursorToLastKeyb0 tab Positions the cursor at the last key in the key space.
fi-6552 fs16
fs28 fi-6552 {f3 -} (BOOL)b moveCursorToNextKeyb0 tab Positions the cursor at the next key in the key space. If the cursor is at the last key, it does not move.
fi-6552 fs16
fs28 fi-6552 {f3 -} (BOOL)b moveCursorToPreviousKeyb0 tab Positions the cursor at the previous key in the key space. If the cursor is at the first key, it does not move.
fi-6552 fs16
fs28 fi-6552 {f3 -} (BOOL)b moveCursorToKey:b0 (NSData *)i keyi0 tab Positions the cursor at i keyi0 .
fi-6552 fs16
fs28 fi-6552 {f3 -}(BOOL)b isOnKeyb0 tab Returns YES if the cursor matched a key on the last operation.
pard s16 li100 fi0 ri1007 ql f0 b fs48
fs28 Accessing the Data
fs14
fs28 pard s8 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 {f3 -} (NSData *)b cursorKeyb0 tab Returns the key that the cursor is pointing to.
fi-6552 fs16
fs28 fi-6552 {f3 -} (NSData *)b cursorValueb0 tab Returns the value associated with the key that the cursor is pointing to.
fi-6552 fs16
fs28 fi-6552 {f3 -} (NSData *)b cursorValueWithRange:b0 (NSRange)i range
s9 li7030 fi-6553 fi-5796 i0 tab Returns a portion, specified by i rangei0 , of the value associated with the key that the cursor is pointing to.
pard s16 li100 fi0 ri1007 ql f0 b fs48
fs28 Changing the Data in the NSBTreeBlock
fs14
fs28 pard s8 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 {f3 -} (BOOL)b writeValue:b0 (NSData *)i valuei0 tab 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 i valuei0 as the value. This method returns YES if it inserted a new key/value pair and NO if it overwrote an existing value.
fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b writeValue:b0 (NSData *)i valuei0 tab Replaces a portion, starting at i indexi0 , of the value associated
s9 li7030 fi-6553 fi-5796 b atIndex:b0 (unsigned)i indextab tab i0 with the key that the cursor is pointing to. If the key does not exist, the NSBTreeNoValueException exception is raised.
s8 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b removeValueb0 tab Deletes the key/value pair from the NSBTreeBlock. If the key/value pair already does not exist, the NSBTreeNoValueException exception is raised.
}These are the contents of the former NiCE NeXT User Group NeXTSTEP/OpenStep software archive, currently hosted by Netfuture.ch.