1 /** @file termiterator.h
2 * @brief Class for iterating over a list of terms
4 /* Copyright (C) 2007,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_TERMITERATOR_H
23 #define XAPIAN_INCLUDED_TERMITERATOR_H
25 #if !defined XAPIAN_IN_XAPIAN_H && !defined XAPIAN_LIB_BUILD
26 # error "Never use <xapian/termiterator.h> directly; include <xapian.h> instead."
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>
40 /// Class for iterating over a list of terms.
41 class XAPIAN_VISIBILITY_DEFAULT TermIterator
{
43 /// Class representing the TermIterator internals.
45 /// @private @internal Reference counted internals.
48 /// @private @internal Construct given internals.
49 explicit TermIterator(Internal
*internal_
);
52 TermIterator(const TermIterator
& o
);
55 TermIterator
& operator=(const TermIterator
& o
);
57 /** Default constructor.
59 * Creates an uninitialised iterator, which can't be used before being
60 * assigned to, but is sometimes syntactically convenient.
62 XAPIAN_NOTHROW(TermIterator())
67 if (internal
) decref();
70 /// Return the term at the current position.
71 std::string
operator*() const;
73 /// Return the wdf for the term at the current position.
74 Xapian::termcount
get_wdf() const;
76 /// Return the term frequency for the term at the current position.
77 Xapian::doccount
get_termfreq() const;
79 /// Return the length of the position list for the current position.
80 Xapian::termcount
positionlist_count() const;
82 /// Return a PositionIterator for the current term.
83 PositionIterator
positionlist_begin() const;
85 /// Return an end PositionIterator for the current term.
86 PositionIterator
XAPIAN_NOTHROW(positionlist_end() const) {
87 return PositionIterator();
90 /// Advance the iterator to the next position.
91 TermIterator
& operator++();
93 /// Advance the iterator to the next position (postfix version).
94 DerefWrapper_
<std::string
> operator++(int) {
95 const std::string
& term(**this);
97 return DerefWrapper_
<std::string
>(term
);
100 /** Advance the iterator to term @a term.
102 * If the iteration is over an unsorted list of terms, then this method
103 * will throw Xapian::InvalidOperationError.
105 * @param term The term to advance to. If this term isn't in
106 * the stream being iterated, then the iterator is moved
107 * to the next term after it which is.
109 void skip_to(const std::string
&term
);
111 /// Return a string describing this object.
112 std::string
get_description() const;
114 /** @private @internal TermIterator is what the C++ STL calls an
117 * The following typedefs allow std::iterator_traits<> to work so that
118 * this iterator can be used with the STL.
120 * These are deliberately hidden from the Doxygen-generated docs, as the
121 * machinery here isn't interesting to API users. They just need to know
122 * that Xapian iterator classes are compatible with the STL.
126 typedef std::input_iterator_tag iterator_category
;
128 typedef std::string value_type
;
130 typedef Xapian::termcount_diff difference_type
;
132 typedef std::string
* pointer
;
134 typedef std::string
& reference
;
140 void post_advance(Internal
* res
);
144 XAPIAN_NOTHROW(operator==(const TermIterator
&a
, const TermIterator
&b
));
146 /// Equality test for TermIterator objects.
148 operator==(const TermIterator
&a
, const TermIterator
&b
) XAPIAN_NOEXCEPT
150 // Use a pointer comparison - this ensures both that (a == a) and correct
151 // handling of end iterators (which we ensure have NULL internals).
152 return a
.internal
== b
.internal
;
156 XAPIAN_NOTHROW(operator!=(const TermIterator
&a
, const TermIterator
&b
));
158 /// Inequality test for TermIterator objects.
160 operator!=(const TermIterator
&a
, const TermIterator
&b
) XAPIAN_NOEXCEPT
167 #endif // XAPIAN_INCLUDED_TERMITERATOR_H