xapian-core  1.4.25
Public Member Functions | Public Attributes | Protected Attributes | Private Types | Private Member Functions | Private Attributes | List of all members
ChertCursor Class Reference

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

#include <chert_cursor.h>

+ Inheritance diagram for ChertCursor:
+ Collaboration diagram for ChertCursor:

Public Member Functions

 ChertCursor (const ChertTable *B)
 Create a cursor attached to a Btree. More...
 
 ~ChertCursor ()
 Destroy the ChertCursor. 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 prev ()
 Move to the previous key. More...
 
bool find_entry (const string &key)
 Position the cursor on the highest entry with key <= 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 ChertTableget_table () const
 Return a pointer to the ChertTable 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 ChertTableB
 The Btree table. More...
 

Private Types

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

Private Member Functions

 ChertCursor (const ChertCursor &)
 Copying not allowed. More...
 
ChertCursoroperator= (const ChertCursor &)
 Assignment not allowed. More...
 
void rebuild ()
 Rebuild the cursor. More...
 
void get_key (string *key) const
 Get the key. More...
 

Private Attributes

enum ChertCursor:: { ... }  tag_status
 Status of the current_tag member. More...
 
CursorC
 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 66 of file chert_cursor.h.

Member Enumeration Documentation

◆ anonymous enum

anonymous enum
private

Status of the current_tag member.

Enumerator
UNREAD 
UNCOMPRESSED 
COMPRESSED 

Definition at line 94 of file chert_cursor.h.

Constructor & Destructor Documentation

◆ ChertCursor() [1/2]

ChertCursor::ChertCursor ( const ChertCursor )
private

Copying not allowed.

◆ ChertCursor() [2/2]

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

Definition at line 53 of file chert_cursor.cc.

References BLK_UNUSED, C, level, Cursor::n, and Cursor::p.

◆ ~ChertCursor()

ChertCursor::~ChertCursor ( )

Destroy the ChertCursor.

Definition at line 103 of file chert_cursor.cc.

References C, level, and Cursor::p.

Member Function Documentation

◆ after_end()

bool ChertCursor::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 238 of file chert_cursor.h.

Referenced by ChertMetadataTermList::at_end(), ChertSpellingWordsList::at_end(), ChertAllTermsList::at_end(), ChertMetadataTermList::next(), ChertSpellingWordsList::next(), ChertAllTermsList::next(), ChertCompact::CursorGt::operator()(), ChertMetadataTermList::skip_to(), ChertSpellingWordsList::skip_to(), and ChertAllTermsList::skip_to().

◆ find_entry()

bool ChertCursor::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 ChertCursor::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
keyThe key to look for in the table.
Returns
true if the exact key was found in the table, false otherwise.

Definition at line 195 of file chert_cursor.cc.

References Cursor::c, C, CHERT_BTREE_MAX_KEY_LEN, Item_base< T >::component_of(), current_key, DIR_START, get_key(), is_after_end, is_positioned, LOGCALL, LOGLINE, rebuild(), RETURN, tag_status, UNREAD, and version.

Referenced by ChertSpellingWordsList::ChertSpellingWordsList(), ChertSynonymTermList::ChertSynonymTermList(), ChertPostListTable::merge_changes(), ChertCompact::merge_docid_keyed(), next(), prev(), and ChertTable::really_empty().

◆ find_entry_ge()

bool ChertCursor::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 243 of file chert_cursor.cc.

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

Referenced by MutableChertCursor::del(), ChertAllTermsList::next(), ChertMetadataTermList::skip_to(), ChertSpellingWordsList::skip_to(), and ChertAllTermsList::skip_to().

◆ find_entry_lt()

void ChertCursor::find_entry_lt ( const string &  key)
inline

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

Definition at line 218 of file chert_cursor.h.

Referenced by ChertMetadataTermList::ChertMetadataTermList(), and ChertSynonymTermList::ChertSynonymTermList().

◆ get_key()

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

ChertCursor 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 284 of file chert_cursor.cc.

References Assert, C, is_positioned, Item_base< T >::key(), level, and Key::read().

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

◆ get_table()

const ChertTable* ChertCursor::get_table ( ) const
inline

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

Definition at line 241 of file chert_cursor.h.

◆ next()

bool ChertCursor::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, ChertCursor::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 158 of file chert_cursor.cc.

References Assert, C, Item_base< T >::component_of(), current_key, find_entry(), get_key(), is_after_end, is_positioned, LOGCALL, LOGLINE, RETURN, tag_status, UNREAD, and version.

Referenced by MutableChertCursor::del(), ChertCompact::merge_docid_keyed(), ChertCompact::merge_spellings(), ChertCompact::merge_synonyms(), ChertMetadataTermList::next(), ChertSpellingWordsList::next(), ChertAllTermsList::next(), ChertCompact::PostlistCursor::next(), and ChertTable::really_empty().

◆ operator=()

ChertCursor& ChertCursor::operator= ( const ChertCursor )
private

Assignment not allowed.

◆ prev()

bool ChertCursor::prev ( )

Move to the previous key.

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

Definition at line 114 of file chert_cursor.cc.

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

◆ read_tag()

bool ChertCursor::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_compressedDon'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 293 of file chert_cursor.cc.

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

Referenced by ChertSpellingWordsList::get_termfreq(), ChertTable::is_open(), ChertCompact::merge_docid_keyed(), ChertCompact::merge_spellings(), ChertCompact::merge_synonyms(), and ChertAllTermsList::read_termfreq().

◆ rebuild()

void ChertCursor::rebuild ( )
private

Rebuild the cursor.

Called when the table has changed.

Definition at line 73 of file chert_cursor.cc.

References BLK_UNUSED, C, level, Cursor::n, Cursor::p, and version.

Referenced by find_entry(), and find_entry_ge().

◆ to_end()

void ChertCursor::to_end ( )
inline

Member Data Documentation

◆ B

const ChertTable* ChertCursor::B
protected

The Btree table.

Definition at line 98 of file chert_cursor.h.

Referenced by MutableChertCursor::del().

◆ C

Cursor* ChertCursor::C
private

Pointer to an array of Cursors.

Definition at line 102 of file chert_cursor.h.

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

◆ current_key

string ChertCursor::current_key

◆ current_tag

string ChertCursor::current_tag

Current tag pointed to by cursor.

You must call read_tag to make this value available.

Definition at line 154 of file chert_cursor.h.

Referenced by ChertSpellingWordsList::get_termfreq(), ChertCompact::merge_docid_keyed(), ChertCompact::merge_spellings(), ChertCompact::merge_synonyms(), read_tag(), and ChertAllTermsList::read_termfreq().

◆ is_after_end

bool ChertCursor::is_after_end
protected

Whether the cursor is off the end of the table.

Definition at line 90 of file chert_cursor.h.

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

◆ is_positioned

bool ChertCursor::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 86 of file chert_cursor.h.

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

◆ level

int ChertCursor::level
private

The value of level in the Btree structure.

Definition at line 107 of file chert_cursor.h.

Referenced by ChertCursor(), ChertTable::empty(), get_key(), read_tag(), rebuild(), and ~ChertCursor().

◆ tag_status

enum { ... } ChertCursor::tag_status

Status of the current_tag member.

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

◆ version

unsigned long ChertCursor::version
private

Definition at line 104 of file chert_cursor.h.

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


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