Branch data Line data Source code
1 : : /* chert_cursor.h: Interface to Btree cursors
2 : : *
3 : : * Copyright 1999,2000,2001 BrightStation PLC
4 : : * Copyright 2002,2003,2004,2006,2007,2008,2010 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 OM_HGUARD_CHERT_CURSOR_H
23 : : #define OM_HGUARD_CHERT_CURSOR_H
24 : :
25 : : #include <xapian/visibility.h>
26 : :
27 : : #include "chert_types.h"
28 : :
29 : : #include <string>
30 : : using std::string;
31 : :
32 : : #define BLK_UNUSED uint4(-1)
33 : :
34 : : class Cursor {
35 : : private:
36 : : // Prevent copying
37 : : Cursor(const Cursor &);
38 : : Cursor & operator=(const Cursor &);
39 : :
40 : : public:
41 : : /// Constructor, to initialise important elements.
42 : 5885482 : Cursor() : p(0), c(-1), n(BLK_UNUSED), rewrite(false)
43 : 5885482 : {}
44 : :
45 : : /// pointer to a block
46 : : byte * p;
47 : : /// offset in the block's directory
48 : : int c;
49 : : /** block number
50 : : *
51 : : * n is kept in tandem with p. The unassigned state is when
52 : : * p == 0 and n == BLK_UNUSED.
53 : : *
54 : : * Setting n to BLK_UNUSED is necessary in at least some cases.
55 : : */
56 : :
57 : : uint4 n;
58 : : /// true if the block is not the same as on disk, and so needs rewriting
59 : : bool rewrite;
60 : : };
61 : :
62 : : class ChertTable;
63 : :
64 : : /** A cursor pointing to a position in a Btree table, for reading several
65 : : * entries in order, or finding approximate matches.
66 : : */
67 : : class XAPIAN_VISIBILITY_DEFAULT ChertCursor {
68 : : private:
69 : : /// Copying not allowed
70 : : ChertCursor(const ChertCursor &);
71 : :
72 : : /// Assignment not allowed
73 : : ChertCursor & operator=(const ChertCursor &);
74 : :
75 : : /** Rebuild the cursor.
76 : : *
77 : : * Called when the table has changed.
78 : : */
79 : : void rebuild();
80 : :
81 : : protected:
82 : : /** Whether the cursor is positioned at a valid entry.
83 : : *
84 : : * false initially, and after the cursor has dropped
85 : : * off either end of the list of items
86 : : */
87 : : bool is_positioned;
88 : :
89 : : /** Whether the cursor is off the end of the table.
90 : : */
91 : : bool is_after_end;
92 : :
93 : : private:
94 : : /** Status of the current_tag member. */
95 : : enum { UNREAD, UNCOMPRESSED, COMPRESSED } tag_status;
96 : :
97 : : protected:
98 : : /// The Btree table
99 : : const ChertTable * B;
100 : :
101 : : private:
102 : : /// Pointer to an array of Cursors
103 : : Cursor * C;
104 : :
105 : : unsigned long version;
106 : :
107 : : /** The value of level in the Btree structure. */
108 : : int level;
109 : :
110 : : /** Get the key.
111 : : *
112 : : * The key of the item at the cursor is copied into key.
113 : : *
114 : : * The cursor must be positioned before calling this method.
115 : : *
116 : : * e.g.
117 : : *
118 : : * ChertCursor BC(&btree);
119 : : * string key;
120 : : *
121 : : * // Now do something to each key in the Btree
122 : : * BC.find_entry(""); // must give result true
123 : : *
124 : : * while (BC.next()) {
125 : : * BC.get_key(&key);
126 : : * do_something_to(key);
127 : : * }
128 : : */
129 : : void get_key(string * key) const;
130 : :
131 : : public:
132 : : /** Create a cursor attached to a Btree.
133 : : *
134 : : * Creates a cursor, which can be used to remember a position inside
135 : : * the B-tree. The position is simply the item (key and tag) to which
136 : : * the cursor points. A cursor is either positioned or unpositioned,
137 : : * and is initially unpositioned.
138 : : *
139 : : * NB: You must not try to use a ChertCursor after the Btree it is
140 : : * attached to is destroyed. It's safe to destroy the ChertCursor
141 : : * after the Btree though, you just may not use the ChertCursor.
142 : : */
143 : : ChertCursor(const ChertTable *B);
144 : :
145 : : /** Destroy the ChertCursor */
146 : : ~ChertCursor();
147 : :
148 : : /** Current key pointed to by cursor.
149 : : */
150 : : string current_key;
151 : :
152 : : /** Current tag pointed to by cursor. You must call read_tag to
153 : : * make this value available.
154 : : */
155 : : string current_tag;
156 : :
157 : : /** Read the tag from the table and store it in current_tag.
158 : : *
159 : : * Some cursor users don't need the tag, so for efficiency we
160 : : * only read it when asked to.
161 : : *
162 : : * @param keep_compressed Don't uncompress the tag - e.g. useful
163 : : * if it's just being opaquely copied
164 : : * (default: false).
165 : : *
166 : : * @return true if current_tag holds compressed data (always
167 : : * false if keep_compressed was false).
168 : : */
169 : : bool read_tag(bool keep_compressed = false);
170 : :
171 : : /** Advance to the next key.
172 : : *
173 : : * If cursor is unpositioned, the result is simply false.
174 : : *
175 : : * If cursor is positioned, and points to the very last item in the
176 : : * Btree the cursor is made unpositioned, and the result is false.
177 : : * Otherwise the cursor is moved to the next item in the B-tree,
178 : : * and the result is true.
179 : : *
180 : : * Effectively, ChertCursor::next() loses the position of BC when it
181 : : * drops off the end of the list of items. If this is awkward, one can
182 : : * always arrange for a key to be present which has a rightmost
183 : : * position in a set of keys,
184 : : */
185 : : bool next();
186 : :
187 : : /** Move to the previous key.
188 : : *
189 : : * This is like ChertCursor::next, but BC is taken to the previous
190 : : * rather than next item.
191 : : */
192 : : bool prev();
193 : :
194 : : /** Position the cursor on the highest entry with key <= @a key.
195 : : *
196 : : * If the exact key is found in the table, the cursor will be
197 : : * set to point to it, and the method will return true.
198 : : *
199 : : * If the key is not found, the cursor will be set to point to
200 : : * the key preceding that asked for, and the method will return
201 : : * false. If there is no key preceding that asked for, the cursor
202 : : * will point to a null key.
203 : : *
204 : : * Note: Since the B-tree always contains a null key, which precedes
205 : : * everything, a call to ChertCursor::find_entry always results in a
206 : : * valid key being pointed to by the cursor.
207 : : *
208 : : * Note: Calling this method with a null key, then calling next()
209 : : * will leave the cursor pointing to the first key.
210 : : *
211 : : * @param key The key to look for in the table.
212 : : *
213 : : * @return true if the exact key was found in the table, false
214 : : * otherwise.
215 : : */
216 : : bool find_entry(const string &key);
217 : :
218 : : /// Position the cursor on the highest entry with key < @a key.
219 : 10140 : void find_entry_lt(const string &key) {
220 [ + + ]: 10140 : if (find_entry(key)) prev();
221 : 10140 : }
222 : :
223 : : /** Position the cursor on the lowest entry with key >= @a key.
224 : : *
225 : : * @return true if the exact key was found in the table, false
226 : : * otherwise.
227 : : */
228 : : bool find_entry_ge(const string &key);
229 : :
230 : : /** Set the cursor to be off the end of the table.
231 : : */
232 : 5079 : void to_end() { is_after_end = true; }
233 : :
234 : : /** Determine whether cursor is off the end of table.
235 : : *
236 : : * @return true if the cursor has been moved off the end of the
237 : : * table, past the last entry in it, and false otherwise.
238 : : */
239 : 52879 : bool after_end() const { return is_after_end; }
240 : :
241 : : /// Return a pointer to the ChertTable we're a cursor for.
242 : 24 : const ChertTable * get_table() const { return B; }
243 : : };
244 : :
245 : 6 : class MutableChertCursor : public ChertCursor {
246 : : public:
247 : : /** Create a mutable cursor attached to a Btree.
248 : : *
249 : : * A mutable cursor allows the items to be deleted.
250 : : *
251 : : * Creates a cursor, which can be used to remember a position inside
252 : : * the B-tree. The position is simply the item (key and tag) to which
253 : : * the cursor points. A cursor is either positioned or unpositioned,
254 : : * and is initially unpositioned.
255 : : *
256 : : * NB: You must not try to use a MutableChertCursor after the Btree it is
257 : : * attached to is destroyed. It's safe to destroy the MutableChertCursor
258 : : * after the Btree though, you just may not use the MutableChertCursor.
259 : : */
260 : 6 : MutableChertCursor(ChertTable *B_) : ChertCursor(B_) { }
261 : :
262 : : /** Delete the current key/tag pair, leaving the cursor on the next
263 : : * entry.
264 : : *
265 : : * @return false if the cursor ends up unpositioned.
266 : : */
267 : : bool del();
268 : : };
269 : :
270 : : #endif /* OM_HGUARD_CHERT_CURSOR_H */
|
