BrassCursor Class Reference

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

#include <brass_cursor.h>

Inheritance diagram for BrassCursor:

[legend]

Collaboration diagram for BrassCursor:

[legend]

List of all members.

Public Member Functions

BrassCursor (const BrassTable *B)

Create a cursor attached to a Btree.

~BrassCursor ()

Destroy the BrassCursor.

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.

const BrassTable * get_table () const

Return a pointer to the BrassTable 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.

Protected 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.

const BrassTable * B

The Btree table.

Private Types

enum { UNREAD, UNCOMPRESSED, COMPRESSED }

Status of the current_tag member. More...

Private Member Functions

BrassCursor (const BrassCursor &)

Copying not allowed.

BrassCursor & operator= (const BrassCursor &)

Assignment not allowed.

void rebuild ()

Rebuild the cursor.

void get_key (string *key) const

Get the key.

Private Attributes

enum BrassCursor:: { ... } tag_status

Status of the current_tag member.

Brass::Cursor * C

Pointer to an array of Cursors.

unsigned long version

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 71 of file brass_cursor.h.

Member Enumeration Documentation

anonymous enum [private]

Status of the current_tag member.

Enumerator:

UNREAD
UNCOMPRESSED
COMPRESSED

Definition at line 99 of file brass_cursor.h.

Constructor & Destructor Documentation

BrassCursor::BrassCursor ( const BrassCursor & ) [private]

Copying not allowed.

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

Definition at line 55 of file brass_cursor.cc.

References B, BLK_UNUSED, BrassTable::block_size, BrassTable::C, C, BrassTable::cursor_created_since_last_modification, level, Brass::Cursor::n, and Brass::Cursor::p.

BrassCursor::~BrassCursor ( )

Destroy the BrassCursor.

Definition at line 104 of file brass_cursor.cc.

References C, level, and Brass::Cursor::p.

Member Function Documentation

bool BrassCursor::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 243 of file brass_cursor.h.

Referenced by BrassSynonymTermList::at_end(), BrassSpellingWordsList::at_end(), BrassMetadataTermList::at_end(), BrassAllTermsList::at_end(), BrassValueList::check(), BrassValueList::next(), BrassSynonymTermList::next(), BrassSpellingWordsList::next(), BrassMetadataTermList::next(), BrassAllTermsList::next(), BrassCompact::CursorGt::operator()(), BrassValueList::skip_to(), BrassSynonymTermList::skip_to(), BrassSpellingWordsList::skip_to(), BrassMetadataTermList::skip_to(), and BrassAllTermsList::skip_to().

bool BrassCursor::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 BrassCursor::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 196 of file brass_cursor.cc.

References B, BRASS_BTREE_MAX_KEY_LEN, Brass::Cursor::c, C, current_key, BrassTable::cursor_version, DIR_START, BrassTable::find(), BrassTable::form_key(), get_key(), is_after_end, is_positioned, LOGCALL, LOGLINE, BrassTable::prev(), rebuild(), RETURN, tag_status, UNREAD, and version.

Referenced by BrassSpellingWordsList::BrassSpellingWordsList(), BrassSynonymTermList::BrassSynonymTermList(), BrassValueList::check(), BrassPostListTable::merge_changes(), BrassCompact::merge_docid_keyed(), BrassCompact::MergeCursor::MergeCursor(), next(), BrassCompact::PostlistCursor::PostlistCursor(), prev(), and BrassValueList::skip_to().

bool BrassCursor::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 244 of file brass_cursor.cc.

References Assert, B, BRASS_BTREE_MAX_KEY_LEN, C, current_key, BrassTable::cursor_version, BrassTable::find(), BrassTable::form_key(), get_key(), is_after_end, is_positioned, LOGCALL, LOGLINE, BrassTable::next(), rebuild(), RETURN, tag_status, UNREAD, and version.

Referenced by MutableBrassCursor::del(), BrassValueList::next(), BrassAllTermsList::next(), BrassSynonymTermList::skip_to(), BrassSpellingWordsList::skip_to(), BrassMetadataTermList::skip_to(), and BrassAllTermsList::skip_to().

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

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

Definition at line 223 of file brass_cursor.h.

Referenced by BrassMetadataTermList::BrassMetadataTermList(), and BrassSynonymTermList::BrassSynonymTermList().

void BrassCursor::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.

BrassCursor BC(&btree); string key;

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

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

Definition at line 285 of file brass_cursor.cc.

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

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

const BrassTable* BrassCursor::get_table ( ) const [inline]

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

Definition at line 246 of file brass_cursor.h.

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

bool BrassCursor::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, BrassCursor::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 BrassCompact::PostlistCursor.

Definition at line 159 of file brass_cursor.cc.

References Assert, B, C, current_key, BrassTable::cursor_version, find_entry(), get_key(), is_after_end, is_positioned, LOGCALL, LOGLINE, BrassTable::next(), RETURN, tag_status, UNREAD, and version.

Referenced by MutableBrassCursor::del(), BrassCompact::merge_docid_keyed(), BrassCompact::merge_spellings(), BrassCompact::merge_synonyms(), BrassCompact::MergeCursor::MergeCursor(), BrassValueList::next(), BrassSynonymTermList::next(), BrassSpellingWordsList::next(), BrassMetadataTermList::next(), BrassCompact::PostlistCursor::next(), BrassAllTermsList::next(), and BrassValueList::skip_to().

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

Assignment not allowed.

bool BrassCursor::prev ( )

Move to the previous key.

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

Definition at line 115 of file brass_cursor.cc.

References Assert, B, C, current_key, BrassTable::cursor_version, find_entry(), get_key(), is_after_end, is_positioned, LOGCALL, LOGLINE, BrassTable::prev(), RETURN, tag_status, UNREAD, and version.

bool BrassCursor::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 294 of file brass_cursor.cc.

References Assert, B, C, COMPRESSED, current_tag, is_positioned, level, BrassTable::level, LOGCALL, LOGLINE, BrassTable::next(), BrassTable::read_tag(), RETURN, tag_status, UNCOMPRESSED, and UNREAD.

Referenced by BrassSpellingWordsList::get_termfreq(), BrassCompact::merge_docid_keyed(), BrassCompact::merge_spellings(), BrassCompact::merge_synonyms(), BrassCompact::PostlistCursor::next(), BrassAllTermsList::read_termfreq_and_collfreq(), and BrassValueList::update_reader().

void BrassCursor::rebuild ( ) [private]

Rebuild the cursor.

Called when the table has changed.

Definition at line 75 of file brass_cursor.cc.

References B, BLK_UNUSED, BrassTable::block_size, BrassTable::C, C, BrassTable::cursor_version, level, BrassTable::level, Brass::Cursor::n, Brass::Cursor::p, and version.

Referenced by find_entry(), and find_entry_ge().

void BrassCursor::to_end ( ) [inline]

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

Definition at line 236 of file brass_cursor.h.

Referenced by BrassSynonymTermList::next(), BrassSpellingWordsList::next(), BrassMetadataTermList::next(), BrassAllTermsList::next(), BrassSynonymTermList::skip_to(), BrassSpellingWordsList::skip_to(), BrassMetadataTermList::skip_to(), and BrassAllTermsList::skip_to().

Member Data Documentation

const BrassTable* BrassCursor::B [protected]

The Btree table.

Definition at line 103 of file brass_cursor.h.

Referenced by BrassCursor(), MutableBrassCursor::del(), find_entry(), find_entry_ge(), get_key(), next(), prev(), read_tag(), and rebuild().

Brass::Cursor* BrassCursor::C [private]

Pointer to an array of Cursors.

Definition at line 107 of file brass_cursor.h.

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

string BrassCursor::current_key

string BrassCursor::current_tag

Current tag pointed to by cursor.

You must call read_tag to make this value available.

Definition at line 159 of file brass_cursor.h.

Referenced by BrassSpellingWordsList::get_termfreq(), BrassCompact::merge_docid_keyed(), BrassCompact::merge_spellings(), BrassCompact::merge_synonyms(), BrassCompact::PostlistCursor::next(), read_tag(), BrassAllTermsList::read_termfreq_and_collfreq(), and BrassValueList::update_reader().

bool BrassCursor::is_after_end [protected]

Whether the cursor is off the end of the table.

Definition at line 95 of file brass_cursor.h.

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

bool BrassCursor::is_positioned [protected]

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 91 of file brass_cursor.h.

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

int BrassCursor::level [private]

The value of level in the Btree structure.

Definition at line 112 of file brass_cursor.h.

Referenced by BrassCursor(), get_key(), read_tag(), rebuild(), and ~BrassCursor().

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

Status of the current_tag member.

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

unsigned long BrassCursor::version [private]

Definition at line 109 of file brass_cursor.h.

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

The documentation for this class was generated from the following files:

backends/brass/brass_cursor.h
backends/brass/brass_cursor.cc


Public Member Functions
	BrassCursor (const BrassTable *B)
	Create a cursor attached to a Btree.
	~BrassCursor ()
	Destroy the BrassCursor.
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.
const BrassTable *	get_table () const
	Return a pointer to the BrassTable 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.
Protected 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.
const BrassTable *	B
	The Btree table.
Private Types
enum	{ UNREAD, UNCOMPRESSED, COMPRESSED }
	Status of the current_tag member. More...
Private Member Functions
	BrassCursor (const BrassCursor &)
	Copying not allowed.
BrassCursor &	operator= (const BrassCursor &)
	Assignment not allowed.
void	rebuild ()
	Rebuild the cursor.
void	get_key (string *key) const
	Get the key.
Private Attributes
enum BrassCursor:: { ... }	tag_status
	Status of the current_tag member.
Brass::Cursor *	C
	Pointer to an array of Cursors.
unsigned long	version
int	level
	The value of level in the Btree structure.