--- name: "WordCursor" section: "3" platform: "linux" package: "libmifluz0-dev" version: "0.24.0-9" release: "Debian 3.1 (Sarge)" platforms: ["linux"] url: "https://new.carta.tech/WordCursor" --- # WordCursor(3) abstract class to search and retrieve entries in a WordList object. ## NAME WordCursor - abstract class to search and retrieve entries in a WordList object. ## SYNOPSIS ``` #include int callback(WordList *, WordDBCursor& , const WordReference *, Object &) { ... } Object* data = ... WordList *words = ...; WordCursor *search = words->Cursor(WordKey("word "), HTDIG_WORDLIST_COLLECTOR); if(search->Walk() == NOTOK) bark; List* results = search->GetResults(); WordCursor *search = words->Cursor(callback, data); WordCursor *search = words->Cursor(WordKey("word ")); WordCursor *search = words->Cursor(WordKey("word "), 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 \ \")** find all occurrences of *word* Ex3: **WordKey("meet \ 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 \")** 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_dump/1.md), [htdb\_stat(1)](/htdb_stat/1.md), [htdb\_load(1)](/htdb_load/1.md), [mifluzdump(1)](/mifluzdump/1.md), [mifluzload(1)](/mifluzload/1.md), [mifluzsearch(1)](/mifluzsearch/1.md), [mifluzdict(1)](/mifluzdict/1.md), [WordContext(3)](/WordContext/3.md), [WordList(3)](/WordList/3.md), [WordDict(3)](/WordDict/3.md), [WordListOne(3)](/WordListOne/3.md), [WordKey(3)](/WordKey/3.md), [WordKeyInfo(3)](/WordKeyInfo/3.md), [WordType(3)](/WordType/3.md), [WordDBInfo(3)](/WordDBInfo/3.md), [WordRecordInfo(3)](/WordRecordInfo/3.md), [WordRecord(3)](/WordRecord/3.md), [WordReference(3)](/WordReference/3.md), [WordCursorOne(3)](/WordCursorOne/3.md), [WordMonitor(3)](/WordMonitor/3.md), [Configuration(3)](/Configuration/3.md), [mifluz(3)](/mifluz/3.md)