This is NSBTreeBlock.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 NSBTreeBlock
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 NSBTreeBlock provides ordered, associative storage and retrieval of untyped data. It identifies and orders data items, called i valuesi0 , by i keyi0 , using a comparator function. A companion class, NSBTreeCursor, actually manipulates the contents of the NSBTreeBlock; NSBTreeBlock only provides the mechanisms for storing and sorting the key/value pairs.
fs16
fs28 pard s15 li477 fi0 ri1007 ql f0 b fs24 fs4
fs24 Setting Up an NSBTreeBlock
pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 f1 b0 fs28 fs16
fs28 An NSBTreeBlock can be used with either a memory-based NSByteStore or an NSByteStoreFile. The NSByteStore holds the contents of the NSBTreeBlock. Use NSBTreeBlock with NSByteStoreFile to build persistent databases. An NSBTreeBlock is initialized as a new client of an NSByteStore using the method b initWithStore:b0 or b initWithStore:block:b0 . The NSBTreeBlock takes up one block in the NSByteStore per key/value pair and one block for each node in the tree. An NSBTreeBlock will always take up at least one block in the NSByteStore.
fs16
fs28 After the NSBTreeBlock has been initialized, it must have its comparator function set with the b setComparator:context:b0 . A comparator function takes as arguments two pieces of arbitrary data and their lengths and returns an integer indicating their ordering relative to one another. A comparator function is of type (NSBTreeComparator *), which has the form:
fs16
fs28 pard s5 li1231 fi0 ri1007 ql f2 fs20 typedef int NSBTreeComparator(NSData * i data1i0 , NSData * i data2i0 , const void *i contexti0 )
pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 f1 fs28 fs16
fs28 where i data1i0 and i data2i0 are pointers to data and i contexti0 is a pointer to blind data that may be used by the comparator function. The comparator function returns a number less than 0 if i data1i0 is considered less than i data2i0 , greater than 0 if i data1i0 is considered greater than i data2i0 , and equal to 0 if i data1i0 and i data2i0 are considered equal. By default, NSBTreeBlocks compare keys as strings.
fs16
fs28 pard s15 li477 fi0 ri1007 ql f0 b fs24 fs4
fs24 Getting Data Into and Out of an NSBTreeBlock
pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 f1 b0 fs28 fs16
fs28 As stated above, NSBTreeBlock simply provides the capacity for associative storage. An NSBTreeCursor is needed to take advantage of that capacity. An NSBTreeCursor is like a pointer into the NSBTreeBlock: It can move to specific positions within the key space and perform operations on the values stored at those locations, independent of other cursors. See the NSBTreeCursor class description for more information.
fs16
fs28 Multiple NSBTreeCursors may independently access a single NSBTreeBlock. The actions of one cursor don'27t affect any of the other cursors in the NSBTreeBlock, except to the extent that they modify the contents of the NSBTreeBlock. It is both safe and meaningful to remove a record that another NSBTreeCursor has just located, as long as the code using the other NSBTreeCursor anticipates this possibility, as described below.
fs16
fs28 In the case of one cursor removing a value that another cursor has just located, the second cursor will have received an indication from a key-locating method (for example, b moveCursorToKey:b0 ) that it has found a key. When it tries to access the value associated with that key, however, the key may no longer exist. The cursor will detect the deletion and slide forward to the next available key if asked to read the value, or it will raise an exception if asked to remove or write the value. If your code allows multiple cursors to be concurrently active in a single NSBTreeBlock, it must anticipate this behavior by handling the exceptions that may be raised and by comparing the key against the expected value after invoking b cursorKeyb0 . If one cursor is pointed at a key and a second cursor removes or adds a key at a different location, it does not change the position of the first cursor.
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 NSBTreeBlock Instance
fs14
fs28 pard s8 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 + (NSBTreeBlock *)b btreeBlockWithStore:b0 (NSByteStore *)i aStore
s9 li7030 fi-6553 fi-5796 i0 tab Returns a new NSBTreeBlock instance in the designated NSByteStore.
s8 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 + (NSBTreeBlock *)b btreeBlockWithStore:b0 (NSByteStore *)i aStore
s9 li7030 fi-6553 fi-5796 i0 b block:b0 (unsigned)i aBlocki0 tab Returns a new NSBTreeBlock instance in the designated NSByteStore with i aBlocki0 as the root block of the NSBTreeBlock. If i aBlocki0 does not exist or is invalid, the NSBTreeInitException is raised.
s8 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 {f3 -} (id)b initWithStore:b0 (NSByteStore *)i aStore
s9 li7030 fi-6553 fi-5796 i0 tab Initializes a newly allocated NSBTreeBlock instance in the designated NSByteStore.
s8 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 {f3 -} (id)b initWithStore:b0 (NSByteStore *)i aStore
s9 li7030 fi-6553 fi-5796 i0 b block:b0 (unsigned)i aBlocki0 tab Initializes a newly allocated NSBTreeBlock instance in the designated NSByteStore with i aBlocki0 as the root block of the NSBTreeBlock. If i aBlocki0 does not exist or is invalid, the NSBTreeInitException is raised.
pard s16 li100 fi0 ri1007 ql f0 b fs48
fs28 Accessing Information About the NSByteStore
fs14
fs28 pard s8 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 {f3 -} (NSByteStore *)b byteStoreb0 tab Returns the NSByteStore associated with the NSBTreeBlock.
fi-6552 fs16
fs28 fi-6552 {f3 -} (unsigned)b storeBlockb0 tab Returns the number of the NSByteStore block that contains the root of the NSBTreeBlock.
pard s16 li100 fi0 ri1007 ql f0 b fs48
fs28 Setting the Comparator
fs14
fs28 pard s8 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 {f3 -} (void)b setComparator:b0 (NSBTreeComparator *)i comparatori0
s9 li7030 fi-6553 fi-5796 b context:b0 (const void *)i contexti0 tab Sets the comparison method. The default is string comparison. When a value is inserted in the NSBTreeBlock, the comparator function decides where to put it. For more information, see the class description.
pard s16 li100 fi0 ri1007 ql f0 b fs48
fs28 Accessing NSBTreeBlock information
fs14
fs28 pard s8 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 {f3 -} (unsigned)b countb0 tab Returns the number of key/value pairs stored in the NSBTreeBlock.
pard s16 li100 fi0 ri1007 ql f0 b fs48
fs28 Affecting NSBTreeBlock Contents
fs14
fs28 pard s8 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 {f3 -} (void)b removeAllObjectsb0 tab Removes all key/value pairs from the NSBTreeBlock.
}These are the contents of the former NiCE NeXT User Group NeXTSTEP/OpenStep software archive, currently hosted by Netfuture.ch.