FreeBSD Manual Pages
WordCursor(3) 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 ob- ject contains the result of the search and status information that in- dicates 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 LO- CATION 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 suc- cess, 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 cur- sor_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 inter- nal 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 suc- cess, 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 oth- erwise. 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 fail- ure. Returns WORD_WALK_NOMATCH_FAILED if the current entry does not match requirements, it's safe to call WalkNextStep again un- til 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 immedi- ately 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 suc- cess, 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 (cur- sor_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 re- sponsible 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. Re- turns 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 nac- tion) = 0 Protected method. Derived classes should use this function to initialize the object if they do not call a WordCursor construc- tor 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 ar- guments. Return OK on success, NOTOK on error. WordKey searchKey Input data. The key to be searched, see DESCRIPTION for more in- formation. 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), Word- Dict(3), WordListOne(3), WordKey(3), WordKeyInfo(3), WordType(3), Word- DBInfo(3), WordRecordInfo(3), WordRecord(3), WordReference(3), WordCur- sorOne(3), WordMonitor(3), Configuration(3), mifluz(3) local WordCursor(3)
NAME | SYNOPSIS | DESCRIPTION | METHODS | AUTHORS | SEE ALSO
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=WordCursor&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>