xapian-core/api/termlist.h

   1 /** @file
   2  * @brief Abstract base class for termlists.
   3  */
   4 /* Copyright (C) 2007,2010,2013,2020 Olly Betts
   5  *
   6  * This program is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU General Public License as
   8  * published by the Free Software Foundation; either version 2 of the
   9  * License, or (at your option) any later version.
  10  *
  11  * This program is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14  * GNU General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU General Public License
  17  * along with this program; if not, write to the Free Software
  18  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
  19  */
  20
  21 #ifndef XAPIAN_INCLUDED_TERMLIST_H
  22 #define XAPIAN_INCLUDED_TERMLIST_H
  23
  24 #include <string>
  25 #include <vector>
  26
  27 #include "xapian/intrusive_ptr.h"
  28 #include <xapian/types.h>
  29 #include <xapian/termiterator.h>
  30
  31 namespace Xapian {
  32     class PositionIterator;
  33     namespace Internal {
  34         class ExpandStats;
  35     }
  36 }
  37
  38 /// Abstract base class for termlists.
  39 class Xapian::TermIterator::Internal : public Xapian::Internal::intrusive_base {
  40     /// Don't allow assignment.
  41     void operator=(const Internal &);
  42
  43     /// Don't allow copying.
  44     Internal(const Internal &);
  45
  46   protected:
  47     /// Only constructable as a base class for derived classes.
  48     Internal() { }
  49
  50   public:
  51     /** We have virtual methods and want to be able to delete derived classes
  52      *  using a pointer to the base class, so we need a virtual destructor.
  53      */
  54     virtual ~Internal();
  55
  56     /// Return approximate size of this termlist.
  57     virtual Xapian::termcount get_approx_size() const = 0;
  58
  59     /// Collate weighting information for the current term.
  60     virtual void accumulate_stats(Xapian::Internal::ExpandStats & stats) const;
  61
  62     /// Return the termname at the current position.
  63     virtual std::string get_termname() const = 0;
  64
  65     /// Return the wdf for the term at the current position.
  66     virtual Xapian::termcount get_wdf() const = 0;
  67
  68     /// Return the term frequency for the term at the current position.
  69     virtual Xapian::doccount get_termfreq() const = 0;
  70
  71     /** Advance the current position to the next term in the termlist.
  72      *
  73      *  The list starts before the first term in the list, so next(), skip_to()
  74      *  or check() must be called before any methods which need the context of
  75      *  the current position.
  76      *
  77      *  @return If a non-NULL pointer is returned, then the caller should
  78      *          substitute the returned pointer for its pointer to us, and then
  79      *          delete us.  This "pruning" can only happen for a non-leaf
  80      *          subclass of this class.
  81      */
  82     virtual Internal * next() = 0;
  83
  84     /** Skip forward to the specified term.
  85      *
  86      *  If the specified term isn't in the list, position ourselves on the
  87      *  first term after tname (or at_end() if no terms after tname exist).
  88      */
  89     virtual Internal * skip_to(const std::string &term) = 0;
  90
  91     /// Return true if the current position is past the last term in this list.
  92     virtual bool at_end() const = 0;
  93
  94     /// Return the length of the position list for the current position.
  95     virtual Xapian::termcount positionlist_count() const = 0;
  96
  97     /** Get pointer to vector<termpos> if that's the internal representation.
  98      *
  99      *  This avoids unnecessary copying of positions in the common cases - the
 100      *  case it doesn't help with is adding a document back with unmodified
 101      *  positions *AND* a different docid, which is an unusual thing to do.
 102      *
 103      *  @return Pointer to vector<termpos> or NULL.
 104      */
 105     virtual const std::vector<Xapian::termpos> * get_vector_termpos() const;
 106
 107     /// Return a PositionIterator for the current position.
 108     virtual Xapian::PositionIterator positionlist_begin() const = 0;
 109
 110     /** Which shard of a multidatabase this is from.
 111      *
 112      *  Used by Enquire::get_eset().
 113      */
 114     size_t shard_index = 0;
 115 };
 116
 117 // In the external API headers, this class is Xapian::TermIterator::Internal,
 118 // but in the library code it's still known as "TermList" in most places.
 119 typedef Xapian::TermIterator::Internal TermList;
 120
 121 #endif // XAPIAN_INCLUDED_TERMLIST_H