xapian-core/api/termlist.h

   1 /** @file termlist.h
   2  * @brief Abstract base class for termlists.
   3  */
   4 /* Copyright (C) 2007,2010,2013 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     /** Return the collection frequency for the term at the current position.
  72      *
  73      *  This method is only implemented for subclasses of AllTermsList
  74      *  (and isn't currently used).
  75      */
  76     virtual Xapian::termcount get_collection_freq() const;
  77
  78     /** Advance the current position to the next term in the termlist.
  79      *
  80      *  The list starts before the first term in the list, so next()
  81      *  must be called before any methods which need the context of
  82      *  the current position.
  83      *
  84      *  @return If a non-NULL pointer is returned, then the caller should
  85      *          substitute the returned pointer for its pointer to us, and then
  86      *          delete us.  This "pruning" can only happen for a non-leaf
  87      *          subclass of this class.
  88      */
  89     virtual Internal * next() = 0;
  90
  91     /** Skip forward to the specified term.
  92      *
  93      *  If the specified term isn't in the list, position ourselves on the
  94      *  first term after tname (or at_end() if no terms after tname exist).
  95      */
  96     virtual Internal * skip_to(const std::string &term) = 0;
  97
  98     /// Return true if the current position is past the last term in this list.
  99     virtual bool at_end() const = 0;
 100
 101     /// Return the length of the position list for the current position.
 102     virtual Xapian::termcount positionlist_count() const = 0;
 103
 104     /** Get pointer to vector<termpos> if that's the internal representation.
 105      *
 106      *  This avoids unnecessary copying of positions in the common cases - the
 107      *  case it doesn't help with is adding a document back with unmodified
 108      *  positions *AND* a different docid, which is an unusual thing to do.
 109      *
 110      *  @return Pointer to vector<termpos> or NULL.
 111      */
 112     virtual const std::vector<Xapian::termpos> * get_vector_termpos() const;
 113
 114     /// Return a PositionIterator for the current position.
 115     virtual Xapian::PositionIterator positionlist_begin() const = 0;
 116 };
 117
 118 // In the external API headers, this class is Xapian::TermIterator::Internal,
 119 // but in the library code it's still known as "TermList" in most places.
 120 typedef Xapian::TermIterator::Internal TermList;
 121
 122 #endif // XAPIAN_INCLUDED_TERMLIST_H