1 : /** \file postingiterator.h
2 : * \brief Classes for iterating through posting lists
3 : */
4 : /* Copyright 1999,2000,2001 BrightStation PLC
5 : * Copyright 2002 Ananova Ltd
6 : * Copyright 2003,2004,2005,2007 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_POSTINGITERATOR_H
25 : #define XAPIAN_INCLUDED_POSTINGITERATOR_H
26 :
27 : #include <iterator>
28 : #include <string>
29 :
30 : #include <xapian/base.h>
31 : #include <xapian/types.h>
32 : #include <xapian/positioniterator.h>
33 : #include <xapian/visibility.h>
34 :
35 : namespace Xapian {
36 :
37 : class Database;
38 :
39 : /** @internal A wrapper class for a docid which returns the docid if
40 : * dereferenced with *. We need this to implement input_iterator semantics.
41 : */
42 : class DocIDWrapper {
43 : private:
44 : docid did;
45 : public:
46 : explicit DocIDWrapper(docid did_) : did(did_) { }
47 : docid operator*() const { return did; }
48 : };
49 :
50 : /** An iterator pointing to items in a list of postings.
51 : */
52 : class XAPIAN_VISIBILITY_DEFAULT PostingIterator {
53 : public:
54 : class Internal;
55 : /// @private @internal Reference counted internals.
56 : Xapian::Internal::RefCntPtr<Internal> internal;
57 :
58 : private:
59 : friend class Database; // So Database can construct us
60 :
61 : explicit PostingIterator(Internal *internal_);
62 :
63 : public:
64 : friend bool operator==(const PostingIterator &a,
65 : const PostingIterator &b);
66 :
67 : /// Default constructor - for declaring an uninitialised iterator
68 : PostingIterator();
69 :
70 : /// Destructor
71 : ~PostingIterator();
72 :
73 : /** Copying is allowed. The internals are reference counted, so
74 : * copying is also cheap.
75 : */
76 : PostingIterator(const PostingIterator &other);
77 :
78 : /** Assignment is allowed. The internals are reference counted,
79 : * so assignment is also cheap.
80 : */
81 : void operator=(const PostingIterator &other);
82 :
83 : PostingIterator & operator++();
84 :
85 : DocIDWrapper operator++(int) {
86 : Xapian::docid tmp = **this;
87 : operator++();
88 : return DocIDWrapper(tmp);
89 : }
90 :
91 : /** Skip the iterator to document did, or the first document after did
92 : * if did isn't in the list of documents being iterated.
93 : */
94 : void skip_to(Xapian::docid did);
95 :
96 : // Get the weight of the posting at the current position: will
97 : // need to set a weight object for this to work.
98 : // Xapian::weight get_weight() const;
99 :
100 : /// Get the document id at the current position in the postlist.
101 : Xapian::docid operator *() const;
102 :
103 : /** Get the length of the document at the current position in the
104 : * postlist.
105 : *
106 : * This information may be stored in the postlist, in which case
107 : * this lookup should be extremely fast (indeed, not require further
108 : * disk access). If the information is not present in the postlist,
109 : * it will be retrieved from the database, at a greater performance
110 : * cost.
111 : */
112 : Xapian::doclength get_doclength() const;
113 :
114 : /** Get the within document frequency of the document at the
115 : * current position in the postlist.
116 : */
117 : Xapian::termcount get_wdf() const;
118 :
119 : /** Return PositionIterator pointing to start of positionlist for
120 : * current document.
121 : */
122 : PositionIterator positionlist_begin() const;
123 :
124 : /** Return PositionIterator pointing to end of positionlist for
125 : * current document.
126 : */
127 : PositionIterator positionlist_end() const {
128 : return PositionIterator(NULL);
129 : }
130 :
131 : // Don't expose these methods here. A container iterator doesn't
132 : // provide a method to find the size of the container...
133 : // Xapian::doccount get_termfreq() const;
134 : // Xapian::termcount get_collection_freq() const;
135 :
136 : /// Return a string describing this object.
137 : std::string get_description() const;
138 :
139 : /// Allow use as an STL iterator
140 : //@{
141 : typedef std::input_iterator_tag iterator_category;
142 : typedef Xapian::docid value_type;
143 : typedef Xapian::doccount_diff difference_type;
144 : typedef Xapian::docid * pointer;
145 : typedef Xapian::docid & reference;
146 : //@}
147 : };
148 :
149 : /// Test equality of two PostingIterators
150 10 : inline bool operator==(const PostingIterator &a, const PostingIterator &b)
151 : {
152 10 : return (a.internal.get() == b.internal.get());
153 : }
154 :
155 : /// Test inequality of two PostingIterators
156 : inline bool operator!=(const PostingIterator &a, const PostingIterator &b)
157 : {
158 : return !(a == b);
159 : }
160 :
161 : }
162 :
163 : #endif /* XAPIAN_INCLUDED_POSTINGITERATOR_H */
|