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