Bcursor Class Reference

A cursor pointing to a position in a Btree table, for reading several entries in order, or finding approximate matches. More...

#include <bcursor.h>

Inheritance diagram for Bcursor:

Inheritance graph
[legend]
Collaboration diagram for Bcursor:

Collaboration graph
[legend]
List of all members.

Public Member Functions

 Bcursor (Btree *B)
 Create a cursor attached to a Btree.
 ~Bcursor ()
 Destroy the Bcursor.
void read_tag ()
 Read the tag from the table and store it in current_tag.
bool next ()
 Advance to the next key.
bool prev ()
 Move to the previous key.
bool find_entry (const string &key)
 Find an entry, or a near match, in the table.
bool after_end ()
 Determine whether cursor is off the end of table.
void del ()
 Delete the current key/tag pair, leaving the cursor on the next entry.

Public Attributes

string current_key
 Current key pointed to by cursor.
string current_tag
 Current tag pointed to by cursor.

Private Member Functions

 Bcursor (const Bcursor &)
 Copying not allowed.
Bcursoroperator= (const Bcursor &)
 Assignment not allowed.
bool get_key (string *key) const
 Get the key.

Private Attributes

bool is_positioned
 Whether the cursor is positioned at a valid entry.
bool is_after_end
 Whether the cursor is off the end of the table.
bool have_read_tag
 Have we read the tag for the current key?
BtreeB
 The Btree table.
CursorC
 Pointer to an array of Cursors.
int level
 The value of level in the Btree structure.

Detailed Description

A cursor pointing to a position in a Btree table, for reading several entries in order, or finding approximate matches.

Definition at line 67 of file bcursor.h.


Constructor & Destructor Documentation

Bcursor::Bcursor ( const Bcursor  )  [private]

Copying not allowed.

Bcursor::Bcursor ( Btree B  ) 

Create a cursor attached to a Btree.

Creates a cursor, which can be used to remember a position inside the B-tree. The position is simply the item (key and tag) to which the cursor points. A cursor is either positioned or unpositioned, and is initially unpositioned.

NB: You must not try to use a Bcursor after the Btree it is attached to is destroyed. It's safe to destroy the Bcursor after the Btree though, you just may not use the Bcursor.

Definition at line 49 of file bcursor.cc.

References B, BLK_UNUSED, Btree::block_size, Btree::C, C, level, Cursor::n, and Cursor::p.

Bcursor::~Bcursor (  ) 

Destroy the Bcursor.

Definition at line 66 of file bcursor.cc.

References C, and level.


Member Function Documentation

Bcursor& Bcursor::operator= ( const Bcursor  )  [private]

Assignment not allowed.

bool Bcursor::get_key ( string *  key  )  const [private]

Get the key.

If the cursor is unpositioned, the result is false.

If the cursor is positioned, the key of the item at the cursor is copied into key and the result is then true.

e.g.

Bcursor BC(&btree); string key;

// Now do something to each key in the Btree BC.find_entry(""); // must give result true

while (BC.next()) { BC.get_key(&key)) { do_something_to(key); }

Definition at line 199 of file bcursor.cc.

References Assert, B, C, is_positioned, level, and Btree::level.

Referenced by find_entry(), next(), and prev().

void Bcursor::read_tag (  ) 

Read the tag from the table and store it in current_tag.

Some cursor users don't need the tag, so for efficiency we only read it when asked to.

Definition at line 210 of file bcursor.cc.

References Assert, B, C, current_tag, DEBUGCALL, DEBUGLINE, have_read_tag, hex_encode(), is_positioned, level, Btree::level, Btree::next(), and Btree::read_tag().

Referenced by check_table_values_empty(), check_table_values_hello(), PositionCursor::next(), DocIDKeyedCursor::next(), PostlistCursor::next(), test_cursor1(), test_cursor2(), test_cursor3(), and test_table3().

bool Bcursor::next (  ) 

Advance to the next key.

If cursor is unpositioned, the result is simply false.

If cursor is positioned, and points to the very last item in the Btree the cursor is made unpositioned, and the result is false. Otherwise the cursor is moved to the next item in the B-tree, and the result is true.

Effectively, Bcursor::next() loses the position of BC when it drops off the end of the list of items. If this is awkward, one can always arrange for a key to be present which has a rightmost position in a set of keys,

Reimplemented in PostlistCursor, DocIDKeyedCursor, PositionCursor, and PostlistCursor.

Definition at line 121 of file bcursor.cc.

References Assert, B, C, current_key, DEBUGCALL, DEBUGLINE, get_key(), have_read_tag, hex_encode(), is_after_end, is_positioned, level, Btree::level, and Btree::next().

Referenced by del(), PositionCursor::next(), DocIDKeyedCursor::next(), PostlistCursor::next(), test_cursor1(), test_cursor3(), and test_table3().

bool Bcursor::prev (  ) 

Move to the previous key.

This is like Bcursor::next, but BC is taken to the previous rather than next item.

Definition at line 77 of file bcursor.cc.

References Assert, B, C, current_key, DEBUGCALL, DEBUGLINE, find_entry(), get_key(), have_read_tag, hex_encode(), is_after_end, is_positioned, level, Btree::level, and Btree::prev().

bool Bcursor::find_entry ( const string &  key  ) 

Find an entry, or a near match, in the table.

If the exact key is found in the table, the cursor will be set to point to it, and the method will return true.

If the key is not found, the cursor will be set to point to the key preceding that asked for, and the method will return false.

If there is no key preceding that asked for, the cursor will point to a null key.

Note: Since the B-tree always contains a null key, which precedes everything, a call to Bcursor::find_entry always results in a valid key being pointed to by the cursor.

Note: Calling this method with a null key, then calling next() will leave the cursor pointing to the first key.

Parameters:
key The key to look for in the table.
Returns:
true if the exact key was found in the table, false otherwise.

Definition at line 153 of file bcursor.cc.

References Assert, B, BTREE_MAX_KEY_LEN, Cursor::c, C, current_key, DEBUGCALL, DEBUGLINE, DIR_START, Btree::find(), Btree::form_key(), get_key(), have_read_tag, hex_encode(), is_after_end, is_positioned, level, Btree::level, Btree::prev(), and RETURN.

Referenced by check_table_values_empty(), check_table_values_hello(), del(), DocIDKeyedCursor::DocIDKeyedCursor(), PositionCursor::PositionCursor(), prev(), test_cursor1(), test_cursor2(), test_cursor3(), test_simple1(), and test_table3().

bool Bcursor::after_end (  )  [inline]

Determine whether cursor is off the end of table.

Returns:
true if the cursor has been moved off the end of the table, past the last entry in it, and false otherwise.

Definition at line 208 of file bcursor.h.

Referenced by test_cursor1(), and test_cursor3().

void Bcursor::del (  ) 

Delete the current key/tag pair, leaving the cursor on the next entry.

Definition at line 230 of file bcursor.cc.

References Assert, B, current_key, DEBUGLINE, Btree::del(), find_entry(), hex_encode(), is_after_end, and next().


Member Data Documentation

bool Bcursor::is_positioned [private]

Whether the cursor is positioned at a valid entry.

false initially, and after the cursor has dropped off either end of the list of items

Definition at line 80 of file bcursor.h.

Referenced by find_entry(), get_key(), next(), prev(), and read_tag().

bool Bcursor::is_after_end [private]

Whether the cursor is off the end of the table.

Definition at line 84 of file bcursor.h.

Referenced by del(), find_entry(), next(), and prev().

bool Bcursor::have_read_tag [private]

Have we read the tag for the current key?

Definition at line 88 of file bcursor.h.

Referenced by find_entry(), next(), prev(), and read_tag().

Btree* Bcursor::B [private]

The Btree table.

Definition at line 91 of file bcursor.h.

Referenced by Bcursor(), del(), find_entry(), get_key(), next(), prev(), and read_tag().

Cursor* Bcursor::C [private]

Pointer to an array of Cursors.

Definition at line 94 of file bcursor.h.

Referenced by Bcursor(), find_entry(), get_key(), next(), prev(), read_tag(), and ~Bcursor().

int Bcursor::level [private]

The value of level in the Btree structure.

Definition at line 97 of file bcursor.h.

Referenced by Bcursor(), find_entry(), get_key(), next(), prev(), read_tag(), and ~Bcursor().

string Bcursor::current_key

Current key pointed to by cursor.

Definition at line 140 of file bcursor.h.

Referenced by check_table_values_empty(), check_table_values_hello(), del(), find_entry(), PositionCursor::next(), DocIDKeyedCursor::next(), next(), prev(), test_cursor1(), test_cursor2(), test_cursor3(), and test_table3().

string Bcursor::current_tag

Current tag pointed to by cursor.

You must call read_tag to make this value available.

Definition at line 145 of file bcursor.h.

Referenced by check_table_values_empty(), check_table_values_hello(), PositionCursor::next(), DocIDKeyedCursor::next(), read_tag(), test_cursor1(), test_cursor2(), test_cursor3(), and test_table3().


The documentation for this class was generated from the following files:
Documentation for Xapian (version 1.0.10).
Generated on 24 Dec 2008 by Doxygen 1.5.2.