FlintCursor Class Reference

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

#include <flint_cursor.h>

Inheritance diagram for FlintCursor:

Inheritance graph
[legend]
Collaboration diagram for FlintCursor:

Collaboration graph
[legend]
List of all members.

Public Member Functions

 FlintCursor (FlintTable *B)
 Create a cursor attached to a Btree.
 ~FlintCursor ()
 Destroy the FlintCursor.
bool read_tag (bool keep_compressed=false)
 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)
 Position the cursor on the highest entry with key <= key.
void find_entry_lt (const string &key)
 Position the cursor on the highest entry with key < key.
bool find_entry_ge (const string &key)
 Position the cursor on the lowest entry with key >= key.
void to_end ()
 Set the cursor to be off the end of the table.
bool after_end () const
 Determine whether cursor is off the end of table.
bool del ()
 Delete the current key/tag pair, leaving the cursor on the next entry.
FlintTableget_table () const
 Return a pointer to the FlintTable we're a cursor for.

Public Attributes

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

Private Types

enum  { UNREAD, UNCOMPRESSED, COMPRESSED }
 Status of the current_tag member. More...

Private Member Functions

 FlintCursor (const FlintCursor &)
 Copying not allowed.
FlintCursoroperator= (const FlintCursor &)
 Assignment not allowed.
void 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.
enum FlintCursor:: { ... }  tag_status
 Status of the current_tag member.
FlintTableB
 The Btree table.
Cursor_C
 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 flint_cursor.h.


Member Enumeration Documentation

anonymous enum [private]

Status of the current_tag member.

Enumerator:
UNREAD 
UNCOMPRESSED 
COMPRESSED 

Definition at line 87 of file flint_cursor.h.


Constructor & Destructor Documentation

FlintCursor::FlintCursor ( const FlintCursor  )  [private]

Copying not allowed.

FlintCursor::FlintCursor ( FlintTable 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 FlintCursor after the Btree it is attached to is destroyed. It's safe to destroy the FlintCursor after the Btree though, you just may not use the FlintCursor.

Definition at line 53 of file flint_cursor.cc.

References B, BLK_UNUSED, FlintTable::block_size, FlintTable::C, C, level, Cursor_::n, and Cursor_::p.

FlintCursor::~FlintCursor (  ) 

Destroy the FlintCursor.

Definition at line 70 of file flint_cursor.cc.

References C, and level.


Member Function Documentation

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

Assignment not allowed.

void FlintCursor::get_key ( string *  key  )  const [private]

Get the key.

The key of the item at the cursor is copied into key.

The cursor must be positioned before calling this method.

e.g.

FlintCursor 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 240 of file flint_cursor.cc.

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

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

bool FlintCursor::read_tag ( bool  keep_compressed = false  ) 

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.

Parameters:
keep_compressed Don't uncompress the tag - e.g. useful if it's just being opaquely copied (default: false).
Returns:
true if current_tag holds compressed data (always false if keep_compressed was false).

Definition at line 249 of file flint_cursor.cc.

References Assert, B, C, COMPRESSED, current_tag, DEBUGCALL, DEBUGLINE, hex_encode(), is_positioned, level, FlintTable::level, FlintTable::next(), FlintTable::read_tag(), tag_status, UNCOMPRESSED, and UNREAD.

Referenced by FlintSpellingWordsList::get_termfreq(), main(), merge_docid_keyed(), and FlintAllTermsList::read_termfreq_and_collfreq().

bool FlintCursor::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, FlintCursor::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, and PostlistCursor.

Definition at line 124 of file flint_cursor.cc.

References Assert, B, C, current_key, DEBUGCALL, DEBUGLINE, get_key(), hex_encode(), is_after_end, is_positioned, level, FlintTable::level, FlintTable::next(), tag_status, and UNREAD.

Referenced by del(), main(), merge_docid_keyed(), MergeCursor::MergeCursor(), PostlistCursor::next(), FlintSynonymTermList::next(), FlintSpellingWordsList::next(), FlintMetadataTermList::next(), and FlintAllTermsList::next().

bool FlintCursor::prev (  ) 

Move to the previous key.

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

Definition at line 81 of file flint_cursor.cc.

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

Referenced by main().

bool FlintCursor::find_entry ( const string &  key  ) 

Position the cursor on the highest entry with key <= key.

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 FlintCursor::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 155 of file flint_cursor.cc.

References Assert, B, Cursor_::c, C, current_key, DEBUGCALL, DEBUGLINE, DIR_START, FlintTable::find(), FLINT_BTREE_MAX_KEY_LEN, FlintTable::form_key(), get_key(), hex_encode(), is_after_end, is_positioned, level, FlintTable::level, FlintTable::prev(), RETURN, tag_status, and UNREAD.

Referenced by FlintSpellingWordsList::FlintSpellingWordsList(), FlintSynonymTermList::FlintSynonymTermList(), main(), merge_docid_keyed(), MergeCursor::MergeCursor(), PostlistCursor::PostlistCursor(), and prev().

void FlintCursor::find_entry_lt ( const string &  key  )  [inline]

Position the cursor on the highest entry with key < key.

Definition at line 207 of file flint_cursor.h.

Referenced by FlintAllTermsList::FlintAllTermsList(), and FlintSynonymTermList::FlintSynonymTermList().

bool FlintCursor::find_entry_ge ( const string &  key  ) 

Position the cursor on the lowest entry with key >= key.

Returns:
true if the exact key was found in the table, false otherwise.

Definition at line 201 of file flint_cursor.cc.

References Assert, B, C, current_key, DEBUGCALL, DEBUGLINE, FlintTable::find(), FLINT_BTREE_MAX_KEY_LEN, FlintTable::form_key(), get_key(), hex_encode(), is_after_end, is_positioned, level, FlintTable::level, FlintTable::next(), RETURN, tag_status, and UNREAD.

Referenced by del(), FlintSynonymTermList::skip_to(), FlintSpellingWordsList::skip_to(), and FlintAllTermsList::skip_to().

void FlintCursor::to_end (  )  [inline]

Set the cursor to be off the end of the table.

Definition at line 220 of file flint_cursor.h.

Referenced by FlintSynonymTermList::next(), FlintSpellingWordsList::next(), FlintMetadataTermList::next(), FlintAllTermsList::next(), FlintSynonymTermList::skip_to(), FlintSpellingWordsList::skip_to(), and FlintAllTermsList::skip_to().

bool FlintCursor::after_end (  )  const [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 227 of file flint_cursor.h.

Referenced by FlintSynonymTermList::at_end(), FlintSpellingWordsList::at_end(), FlintMetadataTermList::at_end(), FlintAllTermsList::at_end(), main(), FlintSynonymTermList::next(), FlintSpellingWordsList::next(), FlintMetadataTermList::next(), FlintAllTermsList::next(), CursorGt::operator()(), FlintSynonymTermList::skip_to(), FlintSpellingWordsList::skip_to(), and FlintAllTermsList::skip_to().

bool FlintCursor::del (  ) 

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

Returns:
false if the cursor ends up unpositioned.

Definition at line 272 of file flint_cursor.cc.

References Assert, B, current_key, FlintTable::del(), find_entry_ge(), is_after_end, is_positioned, and next().

FlintTable* FlintCursor::get_table (  )  const [inline]

Return a pointer to the FlintTable we're a cursor for.

Definition at line 237 of file flint_cursor.h.

Referenced by MergeCursor::~MergeCursor(), and PostlistCursor::~PostlistCursor().


Member Data Documentation

bool FlintCursor::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 flint_cursor.h.

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

bool FlintCursor::is_after_end [private]

Whether the cursor is off the end of the table.

Definition at line 84 of file flint_cursor.h.

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

enum { ... } FlintCursor::tag_status [private]

Status of the current_tag member.

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

FlintTable* FlintCursor::B [private]

The Btree table.

Definition at line 90 of file flint_cursor.h.

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

Cursor_* FlintCursor::C [private]

Pointer to an array of Cursors.

Definition at line 93 of file flint_cursor.h.

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

int FlintCursor::level [private]

The value of level in the Btree structure.

Definition at line 96 of file flint_cursor.h.

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

string FlintCursor::current_key

Current key pointed to by cursor.

Definition at line 138 of file flint_cursor.h.

Referenced by del(), find_entry(), find_entry_ge(), FlintSpellingWordsList::get_termfreq(), FlintSynonymTermList::get_termname(), FlintSpellingWordsList::get_termname(), FlintMetadataTermList::get_termname(), main(), merge_docid_keyed(), PostlistCursor::next(), FlintSynonymTermList::next(), FlintSpellingWordsList::next(), FlintMetadataTermList::next(), next(), FlintAllTermsList::next(), CursorGt::operator()(), prev(), FlintSynonymTermList::skip_to(), FlintSpellingWordsList::skip_to(), and FlintAllTermsList::skip_to().

string FlintCursor::current_tag

Current tag pointed to by cursor.

You must call read_tag to make this value available.

Definition at line 143 of file flint_cursor.h.

Referenced by FlintSpellingWordsList::get_termfreq(), main(), merge_docid_keyed(), PostlistCursor::next(), read_tag(), and FlintAllTermsList::read_termfreq_and_collfreq().


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.