http://www.ousob.com --- Legacy Redefined OuSob - File: /wwwroot/clipx/usr/include/htdig/WordCursor.h

// // WordList.h // // NAME // // search specification and results for WordList. // // SYNOPSIS // // #include <WordList.h> // // int callback(WordList *, WordDBCursor& , const WordReference *, Object &) // { // ... // } // // Object* data = ... // // WordList *words = ...; // // WordCursor *search = words->Cursor(callback, data); // WordCursor *search = words->Cursor(WordKey("word <DEF> <UNDEF> <UNDEF>")); // WordCursor *search = words->Cursor(WordKey("word <DEF> <UNDEF> <UNDEF>"), callback, data); // // ... // // if(search->Walk() == NOTOK) bark; // List* results = search->GetResults(); // // if(search->WalkNext() == OK) // dosomething(search->GetFound()); // // DESCRIPTION // // WordCursor is an iterator on an inverted index. It is created by // asking a <i>WordList</i> object with the <i>Cursor.</i> There is // no other way to create a WordCursor object. // When the <i>Walk*</i> 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 <b>callback</b> function that is called each time a match is // found takes the following arguments: // <pre> // 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. // </pre> // // The <i>WordKey</i> object that specifies the search criterion // may be used as follows (assuming word is followed by DOCID and // LOCATION): // // Ex1: <b>WordKey("word <DEF> <UNDEF> <UNDEF>")</b> find all occurrences // of <i>word</i>. // // Ex2: <b>WordKey("meet <UNDEF> <UNDEF> <UNDEF>")</b> find all occurrences // starting with <i>meet</i>, including <i>meeting</i> etc. // // Ex3: <b>WordKey("meet <DEF> <UNDEF> 1")</b> find all occurrences of // <i>meet</i> that occur at LOCATION 1 in any DOCID. This can // be inefficient since the search has to scan all occurrences // of <i>meet</i> to find the ones that occur at LOCATION 1. // // Ex4: <b>WordKey("meet <DEF> 2 <UNDEF>")</b> find all occurrences of // <i>meet</i> that occur in DOCID 2, at any location. // // Interface functions are virtual so that a derivation of the // class is possible. Some functions are meant to be used by derived // classes such as the <b>Initialize</b> function. All data members // should be accessed using the corresponding accessor if possible. // // END // // Part of the ht://Dig package <http://www.htdig.org/> // Copyright (c) 1999-2004 The ht://Dig Group // For copyright details, see the file COPYING in your distribution // or the GNU Library General Public License (LGPL) version 2 or later // <http://www.gnu.org/copyleft/lgpl.html> // // $Id: WordCursor.h,v 1.4 2004/05/28 13:15:26 lha Exp $ // #ifndef _WordCursor_h_ #define _WordCursor_h_ #ifndef SWIG #include "htString.h" #include "WordKey.h" #include "WordDB.h" class WordList; class WordDBCursor; #endif /* SWIG */ // // Possible values of the action argument of WordList::Walk // check walk function in WordList.cc for info on these: // #define HTDIG_WORDLIST_COLLECTOR 0x0001 #define HTDIG_WORDLIST_WALKER 0x0002 #ifndef SWIG // // Type of the callback argument in WordCursor // typedef int (*wordlist_walk_callback_t)(WordList *, WordDBCursor& , const WordReference *, Object &); #endif /* SWIG */ // // Possible values of the status member // // // WalkNext reached the end of the matches // #define WORD_WALK_ATEND 0x0001 // // Failed to acquire Berkeley DB cursor // #define WORD_WALK_CURSOR_FAILED 0x0002 // // Berkeley DB Get operation failed // #define WORD_WALK_GET_FAILED 0x0004 // // Callback function returned NOTOK // #define WORD_WALK_CALLBACK_FAILED 0x0008 // // WalkNextStep hit an entry that does not match the // searched key. // #define WORD_WALK_NOMATCH_FAILED 0x0010 // // WordCursor contains undefined data // #define WORD_WALK_FAILED 0xffffffff // // Possible return values of the IsA() method // #define WORD_CURSOR 1 #define WORD_CURSORS 2 // // Wordlist::Walk uses WordCursor for : // state information : cursor // search term description // debug/trace/benchmarking // search result format description // class WordCursor { public: #ifndef SWIG // // Private constructor. Creator of the object must then call Initialize() // prior to using any other methods. // WordCursor() { Clear(); } //- // Private constructor. See WordList::Cursor method with same prototype for // description. // WordCursor(WordList *words, wordlist_walk_callback_t callback, Object * callback_data) { Clear(); Initialize(words, WordKey(), callback, callback_data, HTDIG_WORDLIST_WALKER); } //- // Private constructor. See WordList::Cursor method with same prototype for // description. // WordCursor(WordList *words, const WordKey &searchKey, int action = HTDIG_WORDLIST_WALKER) { Clear(); Initialize(words, searchKey, 0, 0, action); } //- // Private constructor. See WordList::Cursor method with same prototype for // description. // WordCursor(WordList *words, const WordKey &searchKey, wordlist_walk_callback_t callback, Object * callback_data) { Clear(); Initialize(words, searchKey, callback, callback_data, HTDIG_WORDLIST_WALKER); } #endif /* SWIG */ virtual ~WordCursor() {} //- // Clear all data in object, set <b>GetResult()</b> data to NULL but // do not delete it (the application is responsible for that). // virtual void Clear(); virtual void ClearInternal(); virtual void ClearResult(); //- // Returns the type of the object. May be overloaded by // derived classes to differentiate them at runtime. // Returns WORD_CURSOR. // virtual int IsA() const { return WORD_CURSOR; } //- // Returns true if WalkNext() step entries in strictly increasing // order, false if it step entries in random order. // virtual int Ordered() const { return 1; } //- // Optimize the cursor before starting a Walk. // Returns OK on success, NOTOK otherwise. // virtual int Optimize() { return OK; } //- // Save in <b>buffer</b> 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 <b>buffer</b> using the // WordKey::Get method. // virtual int ContextSave(String& buffer) const { found.Get(buffer); return OK; } //- // Restore from buffer all the information necessary to // resume the walk at the point it left. The <b>buffer</b> is expected // to contain an ASCII representation of a WordKey (see WordKey::Set // method). A <b>Seek</b> is done on the key and the object is prepared // to jump to the next occurrence when <b>WalkNext</b> is called (the // cursor_get_flags is set to <i>DB_NEXT.</i> // virtual int ContextRestore(const String& buffer); #ifndef SWIG //- // Walk and collect data from the index. // Returns OK on success, NOTOK otherwise. // virtual int Walk(); #endif /* SWIG */ //- // 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 WalkInit(); //- // Move before the first index matching entry. // Returns OK on success, NOTOK otherwise. // virtual int WalkRewind(); //- // Move to the next matching entry. // At end of list, WORD_WALK_ATEND is returned. // Returns OK on success, NOTOK otherwise. // virtual int WalkNext(); #ifndef SWIG //- // 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 WalkNextStep(); #endif /* SWIG */ //- // Terminate Walk, free allocated resources. // Returns OK on success, NOTOK otherwise. // virtual int WalkFinish(); // // Find out if cursor should better jump to the next possible key // (DB_SET_RANGE) instead of sequential iterating (DB_NEXT). If it // is decided that jump is a better move : cursor_set_flags = // DB_SET_RANGE key = calculated next possible key Else do nothing // Return OK if skipping successfull. Returns WORD_WALK_ATEND if no // more possible match, reached the maximum. Returns // WORD_WALK_FAILED on general failure, occurs if called and no // skipping necessary. // int SkipUselessSequentialWalking(); //- // Move before the inverted index position specified in <b>patch.</b> // May only be called after a successfull call to the <i>WalkNext</i> // or <i>WalkNextStep</i>method. // Copy defined fields from <b>patch</b> into a copy of the // <i>found</i> data member and // initialize internal state so that <i>WalkNext</i> jumps to // this key next time it's called (cursor_get_flag set to DB_SET_RANGE). // Returns OK if successfull, NOTOK otherwise. // virtual int Seek(const WordKey& patch); //- // Returns true if cursor is positioned after the last possible // match, false otherwise. // virtual int IsAtEnd() const { return status == WORD_WALK_ATEND; } // // Accessors for input parameters // //- // Returns the search criterion. // WordKey& GetSearch() { return searchKey; } #ifndef SWIG const WordKey& GetSearch() const { return searchKey; } #endif /* SWIG */ //- // Returns the type of action when a matching entry // is found. // int GetAction() const { return action; } // // Accessors for output parameters // //- // Returns the list of WordReference found. The application // is responsible for deallocation of the list. // List *GetResults() { return collectRes; } //- // 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. // List *GetTraces() { return traceRes; } //- // For debugging purposes. Set the list of WordReference hit // during the search process. // void SetTraces(List* traceRes_arg) { traceRes = traceRes_arg; } //- // Returns the last entry hit by the search. Only contains // a valid value if the last <i>WalkNext</i> or <i>WalkNextStep</i> // call was successfull (i.e. returned OK). // const WordReference& GetFound() { return found; } //- // Returns the number of occurrences of the searched word // in the inverted index in the <b>noccurrence</b> parameter. // Returns OK on success, NOTOK on failure. // virtual int Noccurrence(unsigned int& noccurrence) const; #ifndef SWIG //- // Convert the whole structure to an ASCII string description // Returns OK if successfull, NOTOK otherwise. // virtual int Get(String& bufferout) const; String Get() const { String tmp; Get(tmp); return tmp; } protected: //- // 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 <b>Walk*</b> method is called. See the // DESCRIPTION section for the semantics of the arguments. // Return OK on success, NOTOK on error. // int Initialize(WordList *nwords, const WordKey &nsearchKey, wordlist_walk_callback_t ncallback, Object * ncallback_data, int naction); // // Input parameters // //- // Input data. The key to be searched, see DESCRIPTION for more information. // WordKey searchKey; // // Input data. What do do when a WordReference is found. // Can either be // HTDIG_WORDLIST_COLLECTOR WordReference found stored in collectRes // HTDIG_WORDLIST_WALKER callback is called for each WordReference found // int action; // // Input data. Callback function called for each match found. // wordlist_walk_callback_t callback; // // Input data. Argument given to callback, contains arbitrary // caller defined data. // Object *callback_data; // // Output parameters // // // Output data. List of WordReference found in the search. // List *collectRes; //- // Output data. Last match found. Use GetFound() to retrieve it. // WordReference found; //- // Output data. WORD_WALK_ATEND if cursor is past last match, // OK otherwise. Use GetStatus() to retrieve it. // int status; // // Debugging section. Do not use unless you know exactly what you do. // // // Collect everything found while searching (not necessarily matching) // List *traceRes; // // Internal state // // // The actual Berkeley DB cursor. // WordDBCursor cursor; // // The latest retrieved key and data // String key; String data; // // The shorted prefix key computed from searchKey // WordKey prefixKey; //- // WalkNext leap is either DB_NEXT or DB_SET_RANGE. // int cursor_get_flags; // // True if search key is a prefix key // int searchKeyIsSameAsPrefix; //- // The inverted index used by this cursor. // WordList *words; #endif /* SWIG */ }; #endif /* _WordCursor_h_ */