xapian-core/include/xapian/postingiterator.h

   1 /** @file
   2  *  @brief Class for iterating over a list of document ids
   3  */
   4 /* Copyright (C) 2007,2008,2009,2010,2011,2012,2013,2014,2015 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
  19  * USA
  20  */
  21
  22 #ifndef XAPIAN_INCLUDED_POSTINGITERATOR_H
  23 #define XAPIAN_INCLUDED_POSTINGITERATOR_H
  24
  25 #if !defined XAPIAN_IN_XAPIAN_H && !defined XAPIAN_LIB_BUILD
  26 # error Never use <xapian/postingiterator.h> directly; include <xapian.h> instead.
  27 #endif
  28
  29 #include <iterator>
  30 #include <string>
  31
  32 #include <xapian/attributes.h>
  33 #include <xapian/derefwrapper.h>
  34 #include <xapian/positioniterator.h>
  35 #include <xapian/types.h>
  36 #include <xapian/visibility.h>
  37
  38 namespace Xapian {
  39
  40 /// Class for iterating over a list of terms.
  41 class XAPIAN_VISIBILITY_DEFAULT PostingIterator {
  42   public:
  43     /// Class representing the PostingIterator internals.
  44     class Internal;
  45     /// @private @internal Reference counted internals.
  46     Internal * internal;
  47
  48     /// @private @internal Construct given internals.
  49     explicit PostingIterator(Internal *internal_);
  50
  51     /// Copy constructor.
  52     PostingIterator(const PostingIterator & o);
  53
  54     /// Assignment.
  55     PostingIterator & operator=(const PostingIterator & o);
  56
  57 #ifdef XAPIAN_MOVE_SEMANTICS
  58     /// Move constructor.
  59     PostingIterator(PostingIterator && o)
  60         : internal(o.internal) {
  61         o.internal = nullptr;
  62     }
  63
  64     /// Move assignment operator.
  65     PostingIterator & operator=(PostingIterator && o) {
  66         if (this != &o) {
  67             if (internal) decref();
  68             internal = o.internal;
  69             o.internal = nullptr;
  70         }
  71         return *this;
  72     }
  73 #endif
  74
  75     /** Default constructor.
  76      *
  77      *  Creates an uninitialised iterator, which can't be used before being
  78      *  assigned to, but is sometimes syntactically convenient.
  79      */
  80     XAPIAN_NOTHROW(PostingIterator())
  81         : internal(0) { }
  82
  83     /// Destructor.
  84     ~PostingIterator() {
  85         if (internal) decref();
  86     }
  87
  88     /// Return the document id at the current position.
  89     Xapian::docid operator*() const;
  90
  91     /// Return the wdf for the document at the current position.
  92     Xapian::termcount get_wdf() const;
  93
  94     /// Return the length of the document at the current position.
  95     Xapian::termcount get_doclength() const;
  96
  97     /// Return the number of unique terms in the current document.
  98     Xapian::termcount get_unique_terms() const;
  99
 100 #if 0 // FIXME: TermIterator supports this, so PostingIterator really ought to.
 101     /// Return the length of the position list for the current position.
 102     Xapian::termcount positionlist_count() const;
 103 #endif
 104
 105     /// Return a PositionIterator for the current document.
 106     PositionIterator positionlist_begin() const;
 107
 108     /// Return an end PositionIterator for the current document.
 109     PositionIterator XAPIAN_NOTHROW(positionlist_end() const) {
 110         return PositionIterator();
 111     }
 112
 113     /// Advance the iterator to the next position.
 114     PostingIterator & operator++();
 115
 116     /// Advance the iterator to the next position (postfix version).
 117     DerefWrapper_<Xapian::docid> operator++(int) {
 118         Xapian::docid did(**this);
 119         operator++();
 120         return DerefWrapper_<Xapian::docid>(did);
 121     }
 122
 123     /** Advance the iterator to document @a did.
 124      *
 125      *  @param did      The document id to advance to.  If this document id
 126      *                  isn't in the stream being iterated, then the iterator
 127      *                  is moved to the next document id after it which is.
 128      */
 129     void skip_to(Xapian::docid did);
 130
 131     /// Return a string describing this object.
 132     std::string get_description() const;
 133
 134     /** @private @internal PostingIterator is what the C++ STL calls an
 135      *  input_iterator.
 136      *
 137      *  The following typedefs allow std::iterator_traits<> to work so that
 138      *  this iterator can be used with the STL.
 139      *
 140      *  These are deliberately hidden from the Doxygen-generated docs, as the
 141      *  machinery here isn't interesting to API users.  They just need to know
 142      *  that Xapian iterator classes are compatible with the STL.
 143      */
 144     // @{
 145     /// @private
 146     typedef std::input_iterator_tag iterator_category;
 147     /// @private
 148     typedef Xapian::docid value_type;
 149     /// @private
 150     typedef Xapian::doccount_diff difference_type;
 151     /// @private
 152     typedef Xapian::docid * pointer;
 153     /// @private
 154     typedef Xapian::docid & reference;
 155     // @}
 156
 157   private:
 158     void decref();
 159
 160     void post_advance(Internal * res);
 161 };
 162
 163 bool
 164 XAPIAN_NOTHROW(operator==(const PostingIterator &a, const PostingIterator &b));
 165
 166 /// Equality test for PostingIterator objects.
 167 inline bool
 168 operator==(const PostingIterator &a, const PostingIterator &b) XAPIAN_NOEXCEPT
 169 {
 170     // Use a pointer comparison - this ensures both that (a == a) and correct
 171     // handling of end iterators (which we ensure have NULL internals).
 172     return a.internal == b.internal;
 173 }
 174
 175 inline bool
 176 XAPIAN_NOTHROW(operator!=(const PostingIterator &a, const PostingIterator &b));
 177
 178 /// Inequality test for PostingIterator objects.
 179 inline bool
 180 operator!=(const PostingIterator &a, const PostingIterator &b) XAPIAN_NOEXCEPT
 181 {
 182     return !(a == b);
 183 }
 184
 185 }
 186
 187 #endif // XAPIAN_INCLUDED_POSTINGITERATOR_H