1/** \file termiterator.h
2 * \brief Classes for iterating through term lists
3 */
4/* Copyright 1999,2000,2001 BrightStation PLC
5 * Copyright 2002 Ananova Ltd
6 * Copyright 2003,2004,2005,2006,2007,2008,2009,2012 Olly Betts
7 *
8 * This program is free software; you can redistribute it and/or
9 * modify it under the terms of the GNU General Public License as
10 * published by the Free Software Foundation; either version 2 of the
11 * License, or (at your option) any later version.
12 *
13 * This program is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 * GNU General Public License for more details.
17 *
18 * You should have received a copy of the GNU General Public License
19 * along with this program; if not, write to the Free Software
20 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301
21 * USA
22 */
23
24#ifndef XAPIAN_INCLUDED_TERMITERATOR_H
25#define XAPIAN_INCLUDED_TERMITERATOR_H
26
27#include <iterator>
28#include <string>
29
30#include <xapian/base.h>
31#include <xapian/derefwrapper.h>
32#include <xapian/types.h>
33#include <xapian/positioniterator.h>
34#include <xapian/visibility.h>
35
36namespace Xapian {
37
38class Database;
39
40/** An iterator pointing to items in a list of terms.
41 */
42class XAPIAN_VISIBILITY_DEFAULT TermIterator {
43 public:
44 class Internal;
45 /// @internal Reference counted internals.
46 Xapian::Internal::RefCntPtr<Internal> internal;
47
48 /// @internal Reference counted internals.
49 explicit TermIterator(Internal *internal_);
50
51 /// Default constructor - for declaring an uninitialised iterator.
52 TermIterator();
53
54 /// Destructor.
55 ~TermIterator();
56
57 /** Copying is allowed. The internals are reference counted, so
58 * copying is also cheap.
59 */
60 TermIterator(const TermIterator &other);
61
62 /** Assignment is allowed. The internals are reference counted,
63 * so assignment is also cheap.
64 */
65 void operator=(const TermIterator &other);
66
67 /// Return the current term.
68 std::string operator *() const;
69
70 /// Advance the iterator to the next position.
71 TermIterator & operator++();
72
73 /// Advance the iterator to the next position (postfix version).
74 DerefWrapper_<std::string> operator++(int) {
75 const std::string & term(**this);
76 operator++();
77 return DerefWrapper_<std::string>(term);
78 }
79
80 /** Advance the iterator to the specified term.
81 *
82 * If the specified term isn't in the list, position ourselves on the
83 * first term after it (or at_end() if no greater terms are present).
84 */
85 void skip_to(const std::string & tname);
86
87 /** Return the wdf of the current term (if meaningful).
88 *
89 * The wdf (within document frequency) is the number of occurrences
90 * of a term in a particular document.
91 */
92 Xapian::termcount get_wdf() const;
93
94 /** Return the term frequency of the current term (if meaningful).
95 *
96 * The term frequency is the number of documents which a term indexes.
97 */
98 Xapian::doccount get_termfreq() const;
99
100 /** Return length of positionlist for current term.
101 */
102 Xapian::termcount positionlist_count() const;
103
104 /** Return PositionIterator pointing to start of positionlist for
105 * current term.
106 */
107 PositionIterator positionlist_begin() const;
108
109 /** Return PositionIterator pointing to end of positionlist for
110 * current term.
111 */
112 PositionIterator positionlist_end() const {
113 return PositionIterator();
114 }
115
116 /// Return a string describing this object.
117 std::string get_description() const;
118
119 /// Allow use as an STL iterator
120 //@{
121 typedef std::input_iterator_tag iterator_category;
122 typedef std::string value_type;
123 typedef Xapian::termcount_diff difference_type;
124 typedef std::string * pointer;
125 typedef std::string & reference;
126 //@}
127};
128
129/// Equality test for TermIterator objects.
130inline bool
131operator==(const TermIterator &a, const TermIterator &b)
132{
133 return (a.internal.get() == b.internal.get());
134}
135
136/// Inequality test for TermIterator objects.
137inline bool
138operator!=(const TermIterator &a, const TermIterator &b)
139{
140 return !(a == b);
141}
142
143}
144
145#endif /* XAPIAN_INCLUDED_TERMITERATOR_H */
146