1 /** @file positioniterator.h
2 * @brief Class for iterating over term positions.
4 /* Copyright (C) 2008,2009,2010,2011,2012,2013,2014,2015 Olly Betts
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.
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.
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
22 #ifndef XAPIAN_INCLUDED_POSITIONITERATOR_H
23 #define XAPIAN_INCLUDED_POSITIONITERATOR_H
25 #if !defined XAPIAN_IN_XAPIAN_H && !defined XAPIAN_LIB_BUILD
26 # error "Never use <xapian/positioniterator.h> directly; include <xapian.h> instead."
32 #include <xapian/attributes.h>
33 #include <xapian/derefwrapper.h>
34 #include <xapian/types.h>
35 #include <xapian/visibility.h>
39 /// Class for iterating over term positions.
40 class XAPIAN_VISIBILITY_DEFAULT PositionIterator
{
44 /// Class representing the PositionIterator internals.
46 /// @private @internal Reference counted internals.
49 /// @private @internal Construct given internals.
50 explicit PositionIterator(Internal
*internal_
);
53 PositionIterator(const PositionIterator
& o
);
56 PositionIterator
& operator=(const PositionIterator
& o
);
58 /** Default constructor.
60 * Creates an uninitialised iterator, which can't be used before being
61 * assigned to, but is sometimes syntactically convenient.
63 XAPIAN_NOTHROW(PositionIterator())
68 if (internal
) decref();
71 /// Return the term position at the current iterator position.
72 Xapian::termpos
operator*() const;
74 /// Advance the iterator to the next position.
75 PositionIterator
& operator++();
77 /// Advance the iterator to the next position (postfix version).
78 DerefWrapper_
<Xapian::termpos
> operator++(int) {
79 Xapian::termpos
pos(**this);
81 return DerefWrapper_
<Xapian::termpos
>(pos
);
84 /** Advance the iterator to term position @a termpos.
86 * @param termpos The position to advance to. If this position isn't in
87 * the stream being iterated, then the iterator is moved
88 * to the next term position after it which is.
90 void skip_to(Xapian::termpos termpos
);
92 /// Return a string describing this object.
93 std::string
get_description() const;
95 /** @private @internal PositionIterator is what the C++ STL calls an
98 * The following typedefs allow std::iterator_traits<> to work so that
99 * this iterator can be used with the STL.
101 * These are deliberately hidden from the Doxygen-generated docs, as the
102 * machinery here isn't interesting to API users. They just need to know
103 * that Xapian iterator classes are compatible with the STL.
107 typedef std::input_iterator_tag iterator_category
;
109 typedef Xapian::termpos value_type
;
111 typedef Xapian::termpos_diff difference_type
;
113 typedef Xapian::termpos
* pointer
;
115 typedef Xapian::termpos
& reference
;
120 XAPIAN_NOTHROW(operator==(const PositionIterator
&a
, const PositionIterator
&b
));
122 /// Equality test for PositionIterator objects.
124 operator==(const PositionIterator
&a
, const PositionIterator
&b
) XAPIAN_NOEXCEPT
126 // Use a pointer comparison - this ensures both that (a == a) and correct
127 // handling of end iterators (which we ensure have NULL internals).
128 return a
.internal
== b
.internal
;
132 XAPIAN_NOTHROW(operator!=(const PositionIterator
&a
, const PositionIterator
&b
));
134 /// Inequality test for PositionIterator objects.
136 operator!=(const PositionIterator
&a
, const PositionIterator
&b
) XAPIAN_NOEXCEPT
143 #endif // XAPIAN_INCLUDED_POSITIONITERATOR_H