DragonFly On-Line Manual Pages
WordCursor(3) DragonFly Library Functions Manual WordCursor(3)
NAME
WordCursor -
abstract class to search and retrieve entries in a WordList object.
SYNOPSIS
#include <WordList.h>
int callback(WordList *, WordDBCursor& , const WordReference *, Object &)
{
...
}
Object* data = ...
WordList *words = ...;
WordCursor *search = words->Cursor(WordKey("word <UNDEF> <UNDEF>"), HTDIG_WORDLIST_COLLECTOR);
if(search->Walk() == NOTOK) bark;
List* results = search->GetResults();
WordCursor *search = words->Cursor(callback, data);
WordCursor *search = words->Cursor(WordKey("word <UNDEF> <UNDEF>"));
WordCursor *search = words->Cursor(WordKey("word <UNDEF> <UNDEF>"), callback, data);
WordCursor *search = words->Cursor(WordKey());
search->WalkInit();
if(search->WalkNext() == OK)
dosomething(search->GetFound());
search->WalkFinish();
DESCRIPTION
WordCursor is an iterator on an inverted index. It is created by asking
a WordList object with the Cursor. There is no other way to create a
WordCursor object. When the Walk* methods return, the WordCursor
object contains the result of the search and status information that
indicates if it reached the end of the list (IsAtEnd() method).
The callback function that is called each time a match is found takes
the following arguments:
WordList* words pointer to the inverted index handle.
WordDBCursor& cursor to call Del() and delete the current match
WordReference* wordRef is the match
Object& data is the user data provided by the caller when
search began.
The WordKey object that specifies the search criterion may be used as
follows (assuming word is followed by DOCID and LOCATION):
Ex1: WordKey() walk the entire list of occurences.
Ex2: WordKey("word <UNDEF> <UNDEF>") find all occurrences of word
Ex3: WordKey("meet <UNDEF> 1") find all occurrences of meet that occur
at LOCATION 1 in any DOCID. This can be inefficient since the search
has to scan all occurrences of meet to find the ones that occur at
LOCATION 1.
Ex4: WordKey("meet 2 <UNDEF>") find all occurrences of meet that occur
in DOCID 2, at any location.
WordList is an abstract class and cannot be instanciated. See the
WordCursorOne manual page for an actual implementation of a WordCursor
object.
METHODS
virtual void Clear() = 0
Clear all data in object, set GetResult() data to NULL but do
not delete it (the application is responsible for that).
virtual inline int IsA() const
Returns the type of the object. May be overloaded by derived
classes to differentiate them at runtime. Returns WORD_CURSOR.
virtual inline int Optimize()
Optimize the cursor before starting a Walk. Returns OK on
success, NOTOK otherwise.
virtual int ContextSave(String& buffer) const = 0
Save in buffer all the information necessary to resume the walk
at the point it left. The ASCII representation of the last key
found (GetFound()) is written in buffer using the WordKey::Get
method.
virtual int ContextRestore(const String& buffer) = 0
Restore from buffer all the information necessary to resume the
walk at the point it left. The buffer is expected to contain an
ASCII representation of a WordKey (see WordKey::Set method). A
Seek is done on the key and the object is prepared to jump to
the next occurrence when WalkNext is called (the
cursor_get_flags is set to DB_NEXT.
virtual int Walk() = 0
Walk and collect data from the index. Returns OK on success,
NOTOK otherwise.
virtual int WalkInit() = 0
Must be called before other Walk methods are used. Fill
internal state according to input parameters and move before the
first matching entry. Returns OK on success, NOTOK otherwise.
virtual int WalkRewind() = 0
Move before the first index matching entry. Returns OK on
success, NOTOK otherwise.
virtual int WalkNext() = 0
Move to the next matching entry. At end of list,
WORD_WALK_ATEND is returned. Returns OK on success, NOTOK
otherwise. When OK is returned, the GetFound() method returns
the matched entry. When WORD_WALK_ATEND is returned, the
GetFound() method returns an empty object if the end of the
index was reached or the match that was found and that is
greated than the specified search criterion.
virtual int WalkNextStep() = 0
Advance the cursor one step. The entry pointed to by the cursor
may or may not match the requirements. Returns OK if entry
pointed by cursor matches requirements. Returns NOTOK on
failure. Returns WORD_WALK_NOMATCH_FAILED if the current entry
does not match requirements, it's safe to call WalkNextStep
again until either OK or NOTOK is returned.
virtual int WalkNextExclude(const WordKey& key)
Return 0 if this key must not be returned by WalkNext as a valid
match. The WalkNextStep method calls this virtual method
immediately after jumping to the next entry in the database.
This may be used, for instance, to skip entries that were
selected by a previous search.
virtual int WalkFinish() = 0
Terminate Walk, free allocated resources. Returns OK on
success, NOTOK otherwise.
virtual int Seek(const WordKey& patch) = 0
Move before the inverted index position specified in patch. May
only be called after a successfull call to the WalkNext or
WalkNextStep method. Copy defined fields from patch into a copy
of the found data member and initialize internal state so that
WalkNext jumps to this key next time it's called
(cursor_get_flag set to DB_SET_RANGE). Returns OK if
successfull, NOTOK otherwise.
virtual inline int IsAtEnd() const
Returns true if cursor is positioned after the last possible
match, false otherwise.
virtual inline int IsNoMatch() const
Returns true if cursor hit a value that does not match search
criterion.
inline WordKey& GetSearch()
Returns the search criterion.
inline int GetAction() const
Returns the type of action when a matching entry is found.
inline List *GetResults()
Returns the list of WordReference found. The application is
responsible for deallocation of the list. If the action input
flag bit HTDIG_WORDLIST_COLLECTOR is not set, return a NULL
pointer.
inline List *GetTraces()
For debugging purposes. Returns the list of WordReference hit
during the search process. Some of them match the searched key,
some don't. The application is responsible for deallocation of
the list.
inline void SetTraces(List* traceRes_arg)
For debugging purposes. Set the list of WordReference hit during
the search process.
inline const WordReference& GetFound()
Returns the last entry hit by the search. Only contains a valid
value if the last WalkNext or WalkNextStep call was successfull
(i.e. returned OK).
inline int GetStatus() const
Returns the status of the cursor which may be OK or
WORD_WALK_ATEND.
virtual int Get(String& bufferout) const = 0
Convert the whole structure to an ASCII string description.
Returns OK if successfull, NOTOK otherwise.
inline String Get() const
Convert the whole structure to an ASCII string description and
return it.
virtual int Initialize(WordList *nwords, const WordKey &nsearchKey,
wordlist_walk_callback_t ncallback, Object * ncallback_data, int
naction) = 0
Protected method. Derived classes should use this function to
initialize the object if they do not call a WordCursor
constructor in their own constructutor. Initialization may occur
after the object is created and must occur before a Walk* method
is called. See the DESCRIPTION section for the semantics of the
arguments. Return OK on success, NOTOK on error.
WordKey searchKey
Input data. The key to be searched, see DESCRIPTION for more
information.
WordReference found
Output data. Last match found. Use GetFound() to retrieve it.
int status
Output data. WORD_WALK_ATEND if cursor is past last match, OK
otherwise. Use GetStatus() to retrieve it.
WordList *words
The inverted index used by this cursor.
AUTHORS
Loic Dachary loic@gnu.org
The Ht://Dig group http://dev.htdig.org/
SEE ALSO
htdb_dump(1), htdb_stat(1), htdb_load(1), mifluzdump(1), mifluzload(1),
mifluzsearch(1), mifluzdict(1), WordContext(3), WordList(3),
WordDict(3), WordListOne(3), WordKey(3), WordKeyInfo(3), WordType(3),
WordDBInfo(3), WordRecordInfo(3), WordRecord(3), WordReference(3),
WordCursorOne(3), WordMonitor(3), Configuration(3), mifluz(3)
local WordCursor(3)