xapian-core/include/xapian/positioniterator.h

   1 /** @file
   2  *  @brief Class for iterating over term positions.
   3  */
   4 /* Copyright (C) 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_POSITIONITERATOR_H
  23 #define XAPIAN_INCLUDED_POSITIONITERATOR_H
  24
  25 #if !defined XAPIAN_IN_XAPIAN_H && !defined XAPIAN_LIB_BUILD
  26 # error Never use <xapian/positioniterator.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/types.h>
  35 #include <xapian/visibility.h>
  36
  37 namespace Xapian {
  38
  39 /// Class for iterating over term positions.
  40 class XAPIAN_VISIBILITY_DEFAULT PositionIterator {
  41     void decref();
  42
  43   public:
  44     /// Class representing the PositionIterator internals.
  45     class Internal;
  46     /// @private @internal Reference counted internals.
  47     Internal * internal;
  48
  49     /// @private @internal Construct given internals.
  50     explicit PositionIterator(Internal *internal_);
  51
  52     /// Copy constructor.
  53     PositionIterator(const PositionIterator & o);
  54
  55     /// Assignment.
  56     PositionIterator & operator=(const PositionIterator & o);
  57
  58 #ifdef XAPIAN_MOVE_SEMANTICS
  59     /// Move constructor.
  60     PositionIterator(PositionIterator && o)
  61         : internal(o.internal) {
  62         o.internal = nullptr;
  63     }
  64
  65     /// Move assignment operator.
  66     PositionIterator & operator=(PositionIterator && o) {
  67         if (this != &o) {
  68             if (internal) decref();
  69             internal = o.internal;
  70             o.internal = nullptr;
  71         }
  72         return *this;
  73     }
  74 #endif
  75
  76     /** Default constructor.
  77      *
  78      *  Creates an uninitialised iterator, which can't be used before being
  79      *  assigned to, but is sometimes syntactically convenient.
  80      */
  81     XAPIAN_NOTHROW(PositionIterator())
  82         : internal(0) { }
  83
  84     /// Destructor.
  85     ~PositionIterator() {
  86         if (internal) decref();
  87     }
  88
  89     /// Return the term position at the current iterator position.
  90     Xapian::termpos operator*() const;
  91
  92     /// Advance the iterator to the next position.
  93     PositionIterator & operator++();
  94
  95     /// Advance the iterator to the next position (postfix version).
  96     DerefWrapper_<Xapian::termpos> operator++(int) {
  97         Xapian::termpos pos(**this);
  98         operator++();
  99         return DerefWrapper_<Xapian::termpos>(pos);
 100     }
 101
 102     /** Advance the iterator to term position @a termpos.
 103      *
 104      *  @param termpos  The position to advance to.  If this position isn't in
 105      *                  the stream being iterated, then the iterator is moved
 106      *                  to the next term position after it which is.
 107      */
 108     void skip_to(Xapian::termpos termpos);
 109
 110     /// Return a string describing this object.
 111     std::string get_description() const;
 112
 113     /** @private @internal PositionIterator is what the C++ STL calls an
 114      *  input_iterator.
 115      *
 116      *  The following typedefs allow std::iterator_traits<> to work so that
 117      *  this iterator can be used with the STL.
 118      *
 119      *  These are deliberately hidden from the Doxygen-generated docs, as the
 120      *  machinery here isn't interesting to API users.  They just need to know
 121      *  that Xapian iterator classes are compatible with the STL.
 122      */
 123     // @{
 124     /// @private
 125     typedef std::input_iterator_tag iterator_category;
 126     /// @private
 127     typedef Xapian::termpos value_type;
 128     /// @private
 129     typedef Xapian::termpos_diff difference_type;
 130     /// @private
 131     typedef Xapian::termpos * pointer;
 132     /// @private
 133     typedef Xapian::termpos & reference;
 134     // @}
 135 };
 136
 137 bool
 138 XAPIAN_NOTHROW(operator==(const PositionIterator &a, const PositionIterator &b));
 139
 140 /// Equality test for PositionIterator objects.
 141 inline bool
 142 operator==(const PositionIterator &a, const PositionIterator &b) XAPIAN_NOEXCEPT
 143 {
 144     // Use a pointer comparison - this ensures both that (a == a) and correct
 145     // handling of end iterators (which we ensure have NULL internals).
 146     return a.internal == b.internal;
 147 }
 148
 149 bool
 150 XAPIAN_NOTHROW(operator!=(const PositionIterator &a, const PositionIterator &b));
 151
 152 /// Inequality test for PositionIterator objects.
 153 inline bool
 154 operator!=(const PositionIterator &a, const PositionIterator &b) XAPIAN_NOEXCEPT
 155 {
 156     return !(a == b);
 157 }
 158
 159 }
 160
 161 #endif // XAPIAN_INCLUDED_POSITIONITERATOR_H