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

#include <glass_cursor.h>

Inheritance diagram for GlassCursor:

Collaboration diagram for GlassCursor:

Public Member Functions
	GlassCursor (const GlassTable B, const Glass::Cursor C_=NULL)
	Create a cursor attached to a Btree. More...

GlassCursor *	clone () const
	Clone a cursor. More...

	~GlassCursor ()
	Destroy the GlassCursor. More...

bool	read_tag (bool keep_compressed=false)
	Read the tag from the table and store it in current_tag. More...

bool	next ()
	Advance to the next key. More...

bool	find_entry (const string &key)
	Position the cursor on the highest entry with key <= key. More...

bool	find_exact (const string &key)
	Position the cursor exactly on a key. More...

void	find_entry_lt (const string &key)
	Position the cursor on the highest entry with key < key. More...

bool	find_entry_ge (const string &key)
	Position the cursor on the lowest entry with key >= key. More...

void	to_end ()
	Set the cursor to be off the end of the table. More...

bool	after_end () const
	Determine whether cursor is off the end of table. More...

const GlassTable *	get_table () const
	Return a pointer to the GlassTable we're a cursor for. More...

Public Attributes
string	current_key
	Current key pointed to by cursor. More...

string	current_tag
	Current tag pointed to by cursor. More...

Protected Attributes
bool	is_positioned
	Whether the cursor is positioned at a valid entry. More...

bool	is_after_end
	Whether the cursor is off the end of the table. More...

const GlassTable *	B
	The Btree table. More...

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

Private Member Functions
	GlassCursor (const GlassCursor &)
	Copying not allowed. More...

GlassCursor &	operator= (const GlassCursor &)
	Assignment not allowed. More...

void	rebuild ()
	Rebuild the cursor. More...

void	get_key (string *key) const
	Get the key. More...

Private Attributes
enum GlassCursor:: { ... }	tag_status
	Status of the current_tag member. More...

Glass::Cursor *	C
	Pointer to an array of Cursors. More...

unsigned long	version

int	level
	The value of level in the Btree structure. More...

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 147 of file glass_cursor.h.

Member Enumeration Documentation

◆ anonymous enum

anonymous enum

private

Status of the current_tag member.

Enumerator
UNREAD
UNREAD_ON_LAST_CHUNK
UNCOMPRESSED
COMPRESSED

Definition at line 174 of file glass_cursor.h.

Constructor & Destructor Documentation

◆ GlassCursor() [1/2]

GlassCursor::GlassCursor ( const GlassCursor & )

private

Copying not allowed.

◆ GlassCursor() [2/2]

GlassCursor::GlassCursor	(	const GlassTable *	B,
		const Glass::Cursor *	C_ = `NULL`
	)

explicit

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

Definition at line 54 of file glass_cursor.cc.

References C, Glass::Cursor::clone(), and level.

◆ ~GlassCursor()

GlassCursor::~GlassCursor ( )

Destroy the GlassCursor.

Definition at line 99 of file glass_cursor.cc.

References C.

Member Function Documentation

◆ after_end()

bool GlassCursor::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 329 of file glass_cursor.h.

Referenced by GlassMetadataTermList::at_end(), GlassSpellingWordsList::at_end(), GlassAllTermsList::at_end(), do_until(), main(), GlassMetadataTermList::next(), GlassSpellingWordsList::next(), GlassAllTermsList::next(), GlassCompact::CursorGt::operator()(), show_entry(), GlassMetadataTermList::skip_to(), GlassSpellingWordsList::skip_to(), and GlassAllTermsList::skip_to().

◆ clone()

GlassCursor* GlassCursor::clone ( ) const

inline

Clone a cursor.

Creates a new cursor, primed with the blocks in the first cursor. The new cursor is initially unpositioned.

Definition at line 230 of file glass_cursor.h.

◆ find_entry()

bool GlassCursor::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 GlassCursor::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 144 of file glass_cursor.cc.

References Glass::Cursor::c, C, current_key, DIR_START, get_key(), GLASS_BTREE_MAX_KEY_LEN, is_after_end, is_positioned, LOGCALL, LOGLINE, rebuild(), RETURN, tag_status, UNREAD, UNREAD_ON_LAST_CHUNK, and version.

Referenced by find_entry_lt(), GlassSpellingWordsList::GlassSpellingWordsList(), GlassSynonymTermList::GlassSynonymTermList(), GlassPostListTable::merge_changes(), GlassCompact::merge_docid_keyed(), and next().

◆ find_entry_ge()

bool GlassCursor::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 238 of file glass_cursor.cc.

References Assert, C, current_key, get_key(), GLASS_BTREE_MAX_KEY_LEN, is_after_end, is_positioned, LOGCALL, LOGLINE, rebuild(), RETURN, tag_status, UNREAD, and version.

Referenced by MutableGlassCursor::del(), main(), GlassAllTermsList::next(), GlassMetadataTermList::skip_to(), GlassSpellingWordsList::skip_to(), and GlassAllTermsList::skip_to().

◆ find_entry_lt()

void GlassCursor::find_entry_lt ( const string & key )

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

Definition at line 190 of file glass_cursor.cc.

References Assert, C, current_key, find_entry(), get_key(), is_after_end, is_positioned, LOGCALL_VOID, LOGLINE, tag_status, and UNREAD_ON_LAST_CHUNK.

Referenced by GlassMetadataTermList::GlassMetadataTermList(), GlassSynonymTermList::GlassSynonymTermList(), goto_last(), and main().

◆ find_exact()

bool GlassCursor::find_exact ( const string & key )

Position the cursor exactly on a key.

If key is found, the cursor will be set to it, the tag read. If it is not found, the cursor is left unpositioned.

Parameters

key	The key to search for.

Returns: true if the key was found.

Definition at line 213 of file glass_cursor.cc.

References C, current_key, current_tag, GLASS_BTREE_MAX_KEY_LEN, is_after_end, is_positioned, LOGCALL, rare, rebuild(), RETURN, and version.

◆ get_key()

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

GlassCursor 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 279 of file glass_cursor.cc.

References Assert, Glass::Cursor::c, C, is_positioned, and level.

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

◆ get_table()

const GlassTable* GlassCursor::get_table ( ) const

inline

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

Definition at line 332 of file glass_cursor.h.

◆ next()

bool GlassCursor::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, GlassCursor::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,

Definition at line 106 of file glass_cursor.cc.

References Assert, C, current_key, find_entry(), Glass::LeafItem_base< T >::first_component(), get_key(), is_after_end, is_positioned, LOGCALL, LOGLINE, RETURN, tag_status, UNREAD, UNREAD_ON_LAST_CHUNK, and version.

Referenced by MutableGlassCursor::del(), do_until(), main(), GlassCompact::merge_docid_keyed(), GlassCompact::merge_spellings(), GlassCompact::merge_synonyms(), GlassMetadataTermList::next(), GlassSpellingWordsList::next(), GlassAllTermsList::next(), GlassCompact::PostlistCursor::next(), and GlassCompact::PositionCursor::next().

◆ operator=()

GlassCursor& GlassCursor::operator= ( const GlassCursor & )

private

Assignment not allowed.

◆ read_tag()

bool GlassCursor::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 288 of file glass_cursor.cc.

References Assert, C, COMPRESSED, current_tag, is_positioned, level, LOGCALL, LOGLINE, RETURN, tag_status, UNCOMPRESSED, UNREAD, and UNREAD_ON_LAST_CHUNK.

Referenced by GlassSpellingWordsList::get_termfreq(), GlassCompact::merge_docid_keyed(), GlassCompact::merge_spellings(), GlassCompact::merge_synonyms(), GlassAllTermsList::read_termfreq(), and show_entry().

◆ rebuild()

void GlassCursor::rebuild ( )

private

Rebuild the cursor.

Called when the table has changed.

Definition at line 71 of file glass_cursor.cc.

References C, Glass::Cursor::clone(), Glass::Cursor::destroy(), Glass::Cursor::init(), level, Glass::Cursor::swap(), and version.

Referenced by find_entry(), find_entry_ge(), and find_exact().

◆ to_end()

void GlassCursor::to_end ( )

inline

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

Definition at line 322 of file glass_cursor.h.

Referenced by GlassMetadataTermList::next(), GlassSpellingWordsList::next(), GlassAllTermsList::next(), GlassMetadataTermList::skip_to(), GlassSpellingWordsList::skip_to(), and GlassAllTermsList::skip_to().

Member Data Documentation

◆ B

const GlassTable* GlassCursor::B

protected

The Btree table.

Definition at line 178 of file glass_cursor.h.

Referenced by MutableGlassCursor::del().

◆ C

Glass::Cursor* GlassCursor::C

private

Pointer to an array of Cursors.

Definition at line 182 of file glass_cursor.h.

Referenced by find_entry(), find_entry_ge(), find_entry_lt(), find_exact(), get_key(), GlassCursor(), next(), read_tag(), rebuild(), and ~GlassCursor().

◆ current_key

string GlassCursor::current_key

◆ current_tag

string GlassCursor::current_tag

Current tag pointed to by cursor.

You must call read_tag to make this value available.

Definition at line 244 of file glass_cursor.h.

Referenced by find_exact(), GlassSpellingWordsList::get_termfreq(), GlassCompact::merge_docid_keyed(), GlassCompact::merge_spellings(), GlassCompact::merge_synonyms(), read_tag(), GlassAllTermsList::read_termfreq(), and show_entry().

◆ is_after_end

bool GlassCursor::is_after_end

protected

Whether the cursor is off the end of the table.

Definition at line 170 of file glass_cursor.h.

Referenced by MutableGlassCursor::del(), find_entry(), find_entry_ge(), find_entry_lt(), find_exact(), and next().

◆ is_positioned

bool GlassCursor::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 166 of file glass_cursor.h.

Referenced by MutableGlassCursor::del(), find_entry(), find_entry_ge(), find_entry_lt(), find_exact(), get_key(), next(), and read_tag().

◆ level

int GlassCursor::level

private

The value of level in the Btree structure.

Definition at line 187 of file glass_cursor.h.

Referenced by get_key(), GlassCursor(), read_tag(), and rebuild().

◆ tag_status

enum { ... } GlassCursor::tag_status

Status of the current_tag member.

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

◆ version

unsigned long GlassCursor::version

private

Definition at line 184 of file glass_cursor.h.

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

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

backends/glass/glass_cursor.h
backends/glass/glass_cursor.cc

Public Member Functions

Public Attributes

Protected Attributes

Private Types

Private Member Functions

Private Attributes

Detailed Description

Member Enumeration Documentation

◆ anonymous enum

Constructor & Destructor Documentation

◆ GlassCursor() [1/2]

◆ GlassCursor() [2/2]

◆ ~GlassCursor()

Member Function Documentation

◆ after_end()

◆ clone()

◆ find_entry()

◆ find_entry_ge()

◆ find_entry_lt()

◆ find_exact()

◆ get_key()

◆ get_table()

◆ next()

◆ operator=()

◆ read_tag()

◆ rebuild()

◆ to_end()

Member Data Documentation

◆ B

◆ C

◆ current_key

◆ current_tag

◆ is_after_end

◆ is_positioned

◆ level

◆ tag_status

◆ version