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/

NAME

SYNOPSIS

DESCRIPTION

METHODS

AUTHORS

SEE ALSO