xapian-core/backends/valuelist.h

   1 /** @file valuelist.h
   2  * @brief Abstract base class for value streams.
   3  */
   4 /* Copyright (C) 2007,2008 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_VALUELIST_H
  22 #define XAPIAN_INCLUDED_VALUELIST_H
  23
  24 #include <string>
  25
  26 #include "xapian/intrusive_ptr.h"
  27 #include <xapian/types.h>
  28 #include <xapian/valueiterator.h>
  29
  30 /// Abstract base class for value streams.
  31 class Xapian::ValueIterator::Internal : public Xapian::Internal::intrusive_base {
  32     /// Don't allow assignment.
  33     void operator=(const Internal &);
  34
  35     /// Don't allow copying.
  36     Internal(const Internal &);
  37
  38   protected:
  39     /// Only constructable as a base class for derived classes.
  40     Internal() { }
  41
  42   public:
  43     /** We have virtual methods and want to be able to delete derived classes
  44      *  using a pointer to the base class, so we need a virtual destructor.
  45      */
  46     virtual ~Internal();
  47
  48     /// Return the docid at the current position.
  49     virtual Xapian::docid get_docid() const = 0;
  50
  51     /// Return the value at the current position.
  52     virtual std::string get_value() const = 0;
  53
  54     /// Return the value slot for the current position/this iterator.
  55     virtual Xapian::valueno get_valueno() const = 0;
  56
  57     /// Return true if the current position is past the last entry in this list.
  58     virtual bool at_end() const = 0;
  59
  60     /** Advance the current position to the next document in the value stream.
  61      *
  62      *  The list starts before the first entry in the list, so next(),
  63      *  skip_to() or check() must be called before any methods which need the
  64      *  context of the current position.
  65      */
  66     virtual void next() = 0;
  67
  68     /** Skip forward to the specified docid.
  69      *
  70      *  If the specified docid isn't in the list, position ourselves on the
  71      *  first document after it (or at_end() if no greater docids are present).
  72      */
  73     virtual void skip_to(Xapian::docid) = 0;
  74
  75     /** Check if the specified docid occurs in this valuestream.
  76      *
  77      *  The caller is required to ensure that the specified @a docid actually
  78      *  exists in the database.
  79      *
  80      *  This method acts like skip_to() if that can be done at little extra
  81      *  cost, in which case it then returns true.
  82      *
  83      *  Otherwise it simply checks if a particular docid is present.  If it
  84      *  is, it returns true.  If it isn't, it returns false, and leaves the
  85      *  position unspecified (and hence the result of calling methods which
  86      *  depend on the current position, such as get_docid(), are also
  87      *  unspecified).  In this state, next() will advance to the first matching
  88      *  position after @a docid, and skip_to() will act as it would if the
  89      *  position was the first matching position after @a docid.
  90      *
  91      *  The default implementation calls skip_to().
  92      */
  93     virtual bool check(Xapian::docid did);
  94
  95     /// Return a string description of this object.
  96     virtual std::string get_description() const = 0;
  97 };
  98
  99 // In the external API headers, this class is Xapian::ValueIterator::Internal,
 100 // but in the library code it's known as "ValueList" in most places.
 101 typedef Xapian::ValueIterator::Internal ValueList;
 102
 103 #endif // XAPIAN_INCLUDED_VALUELIST_H