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 Wrap an existing Internal.
  49     XAPIAN_VISIBILITY_INTERNAL
  50     explicit PostingIterator(Internal *internal_);
  51
  52     /// Copy constructor.
  53     PostingIterator(const PostingIterator & o);
  54
  55     /// Assignment.
  56     PostingIterator & operator=(const PostingIterator & o);
  57
  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
  74     /** Default constructor.
  75      *
  76      *  Creates an uninitialised iterator, which can't be used before being
  77      *  assigned to, but is sometimes syntactically convenient.
  78      */
  79     PostingIterator() noexcept
  80         : internal() { }
  81
  82     /// Destructor.
  83     ~PostingIterator() {
  84         if (internal) decref();
  85     }
  86
  87     /// Return the document id at the current position.
  88     Xapian::docid operator*() const;
  89
  90     /// Return the wdf for the document at the current position.
  91     Xapian::termcount get_wdf() const;
  92
  93     /// Return the length of the document at the current position.
  94     Xapian::termcount get_doclength() const;
  95
  96     /// Return the number of unique terms in the current document.
  97     Xapian::termcount get_unique_terms() const;
  98
  99     /// Return the max_wdf in the current document.
 100     Xapian::termcount get_wdfdocmax() const;
 101
 102 #if 0 // FIXME: TermIterator supports this, so PostingIterator really ought to.
 103     /// Return the length of the position list for the current position.
 104     Xapian::termcount positionlist_count() const;
 105 #endif
 106
 107     /// Return a PositionIterator for the current document.
 108     PositionIterator positionlist_begin() const;
 109
 110     /// Return an end PositionIterator for the current document.
 111     PositionIterator positionlist_end() const noexcept {
 112         return PositionIterator();
 113     }
 114
 115     /// Advance the iterator to the next position.
 116     PostingIterator & operator++();
 117
 118     /// Advance the iterator to the next position (postfix version).
 119     DerefWrapper_<Xapian::docid> operator++(int) {
 120         Xapian::docid did(**this);
 121         operator++();
 122         return DerefWrapper_<Xapian::docid>(did);
 123     }
 124
 125     /** Advance the iterator to document @a did.
 126      *
 127      *  @param did      The document id to advance to.  If this document id
 128      *                  isn't in the stream being iterated, then the iterator
 129      *                  is moved to the next document id after it which is.
 130      */
 131     void skip_to(Xapian::docid did);
 132
 133     /// Return a string describing this object.
 134     std::string get_description() const;
 135
 136     /** @private @internal PostingIterator is what the C++ STL calls an
 137      *  input_iterator.
 138      *
 139      *  The following typedefs allow std::iterator_traits<> to work so that
 140      *  this iterator can be used with the STL.
 141      *
 142      *  These are deliberately hidden from the Doxygen-generated docs, as the
 143      *  machinery here isn't interesting to API users.  They just need to know
 144      *  that Xapian iterator classes are compatible with the STL.
 145      */
 146     // @{
 147     /// @private
 148     typedef std::input_iterator_tag iterator_category;
 149     /// @private
 150     typedef Xapian::docid value_type;
 151     /// @private
 152     typedef Xapian::doccount_diff difference_type;
 153     /// @private
 154     typedef Xapian::docid * pointer;
 155     /// @private
 156     typedef Xapian::docid & reference;
 157     // @}
 158
 159   private:
 160     void decref();
 161
 162     XAPIAN_VISIBILITY_INTERNAL
 163     void post_advance(Internal * res);
 164 };
 165
 166 /// Equality test for PostingIterator objects.
 167 inline bool
 168 operator==(const PostingIterator& a, const PostingIterator& b) 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 /// Inequality test for PostingIterator objects.
 176 inline bool
 177 operator!=(const PostingIterator& a, const PostingIterator& b) noexcept
 178 {
 179     return !(a == b);
 180 }
 181
 182 }
 183
 184 #endif // XAPIAN_INCLUDED_POSTINGITERATOR_H