Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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://www.freebsd.org/cgi/man.cgi?query=WordCursor&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help