|
1 /**************************************************************************** |
|
2 ** |
|
3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). |
|
4 ** All rights reserved. |
|
5 ** Contact: Nokia Corporation (qt-info@nokia.com) |
|
6 ** |
|
7 ** This file is part of the documentation of the Qt Toolkit. |
|
8 ** |
|
9 ** $QT_BEGIN_LICENSE:LGPL$ |
|
10 ** No Commercial Usage |
|
11 ** This file contains pre-release code and may not be distributed. |
|
12 ** You may use this file in accordance with the terms and conditions |
|
13 ** contained in the Technology Preview License Agreement accompanying |
|
14 ** this package. |
|
15 ** |
|
16 ** GNU Lesser General Public License Usage |
|
17 ** Alternatively, this file may be used under the terms of the GNU Lesser |
|
18 ** General Public License version 2.1 as published by the Free Software |
|
19 ** Foundation and appearing in the file LICENSE.LGPL included in the |
|
20 ** packaging of this file. Please review the following information to |
|
21 ** ensure the GNU Lesser General Public License version 2.1 requirements |
|
22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. |
|
23 ** |
|
24 ** In addition, as a special exception, Nokia gives you certain additional |
|
25 ** rights. These rights are described in the Nokia Qt LGPL Exception |
|
26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. |
|
27 ** |
|
28 ** If you have questions regarding the use of this file, please contact |
|
29 ** Nokia at qt-info@nokia.com. |
|
30 ** |
|
31 ** |
|
32 ** |
|
33 ** |
|
34 ** |
|
35 ** |
|
36 ** |
|
37 ** |
|
38 ** $QT_END_LICENSE$ |
|
39 ** |
|
40 ****************************************************************************/ |
|
41 |
|
42 /*! |
|
43 \class Q3AsciiCache |
|
44 \brief The Q3AsciiCache class is a template class that provides a cache based on char* keys. |
|
45 \compat |
|
46 |
|
47 Q3AsciiCache is implemented as a template class. Define a template |
|
48 instance Q3AsciiCache\<X\> to create a cache that operates on |
|
49 pointers to X (X*). |
|
50 |
|
51 A cache is a least recently used (LRU) list of cache items. The |
|
52 cache items are accessed via \c char* keys. For Unicode keys use |
|
53 the Q3Cache template instead, which uses QString keys. A Q3Cache |
|
54 has the same performace as a Q3AsciiCache. |
|
55 |
|
56 Each cache item has a cost. The sum of item costs, totalCost(), |
|
57 will not exceed the maximum cache cost, maxCost(). If inserting a |
|
58 new item would cause the total cost to exceed the maximum cost, |
|
59 the least recently used items in the cache are removed. |
|
60 |
|
61 Apart from insert(), by far the most important function is find() |
|
62 (which also exists as operator[]()). This function looks up an |
|
63 item, returns it, and by default marks it as being the most |
|
64 recently used item. |
|
65 |
|
66 There are also methods to remove() or take() an object from the |
|
67 cache. Calling \link Q3PtrCollection::setAutoDelete() |
|
68 setAutoDelete(TRUE)\endlink tells the cache to delete items that |
|
69 are removed. The default is to not delete items when then are |
|
70 removed (i.e., remove() and take() are equivalent). |
|
71 |
|
72 When inserting an item into the cache, only the pointer is copied, |
|
73 not the item itself. This is called a shallow copy. It is possible |
|
74 to make the cache copy all of the item's data (known as a deep |
|
75 copy) when an item is inserted. insert() calls the virtual |
|
76 function Q3PtrCollection::newItem() for the item to be inserted. |
|
77 Inherit a cache and reimplement newItem() if you want deep copies. |
|
78 |
|
79 When removing a cache item the virtual function |
|
80 Q3PtrCollection::deleteItem() is called. Its default implementation |
|
81 in Q3AsciiCache is to delete the item if \link |
|
82 Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled. |
|
83 |
|
84 There is a Q3AsciiCacheIterator which may be used to traverse the |
|
85 items in the cache in arbitrary order. |
|
86 |
|
87 \sa Q3AsciiCacheIterator, Q3Cache, Q3IntCache |
|
88 */ |
|
89 |
|
90 /*! |
|
91 \fn Q3AsciiCache::Q3AsciiCache( const Q3AsciiCache<type> &c ) |
|
92 |
|
93 \internal |
|
94 |
|
95 Do not use. A Q3AsciiCache cannot be copied. Calls qFatal() in debug version. |
|
96 */ |
|
97 |
|
98 |
|
99 /*! |
|
100 \fn Q3AsciiCache::Q3AsciiCache( int maxCost, int size, bool caseSensitive, bool copyKeys ) |
|
101 |
|
102 Constructs a cache whose contents will never have a total cost |
|
103 greater than \a maxCost and which is expected to contain less than |
|
104 \a size items. |
|
105 |
|
106 \a size is actually the size of an internal hash array; it's |
|
107 usually best to make it prime and at least 50% bigger than the |
|
108 largest expected number of items in the cache. |
|
109 |
|
110 Each inserted item has an associated cost. When inserting a new |
|
111 item, if the total cost of all items in the cache will exceed \a |
|
112 maxCost, the cache will start throwing out the older (least |
|
113 recently used) items until there is enough room for the new item |
|
114 to be inserted. |
|
115 |
|
116 If \a caseSensitive is TRUE (the default), the cache keys are case |
|
117 sensitive; if it is FALSE, they are case-insensitive. |
|
118 Case-insensitive comparison only affects the 26 letters in |
|
119 US-ASCII. If \a copyKeys is TRUE (the default), Q3AsciiCache makes |
|
120 a copy of the cache keys, otherwise it copies just the const char |
|
121 * pointer - slightly faster if you can guarantee that the keys |
|
122 will never change, but very risky. |
|
123 */ |
|
124 |
|
125 /*! |
|
126 \fn Q3AsciiCache::~Q3AsciiCache() |
|
127 |
|
128 Removes all items from the cache and destroys it. |
|
129 All iterators that access this cache will be reset. |
|
130 */ |
|
131 |
|
132 /*! |
|
133 \fn Q3AsciiCache<type>& Q3AsciiCache::operator=( const Q3AsciiCache<type> &c ) |
|
134 |
|
135 \internal |
|
136 |
|
137 Do not use. A Q3AsciiCache cannot be copied. Calls qFatal() in debug version. |
|
138 */ |
|
139 |
|
140 /*! |
|
141 \fn int Q3AsciiCache::maxCost() const |
|
142 |
|
143 Returns the maximum allowed total cost of the cache. |
|
144 |
|
145 \sa setMaxCost() totalCost() |
|
146 */ |
|
147 |
|
148 /*! |
|
149 \fn int Q3AsciiCache::totalCost() const |
|
150 |
|
151 Returns the total cost of the items in the cache. This is an |
|
152 integer in the range 0 to maxCost(). |
|
153 |
|
154 \sa setMaxCost() |
|
155 */ |
|
156 |
|
157 /*! |
|
158 \fn void Q3AsciiCache::setMaxCost( int m ) |
|
159 |
|
160 Sets the maximum allowed total cost of the cache to \a m. If the |
|
161 current total cost is greater than \a m, some items are removed |
|
162 immediately. |
|
163 |
|
164 \sa maxCost() totalCost() |
|
165 */ |
|
166 |
|
167 /*! |
|
168 \fn uint Q3AsciiCache::count() const |
|
169 |
|
170 Returns the number of items in the cache. |
|
171 |
|
172 \sa totalCost() size() |
|
173 */ |
|
174 |
|
175 /*! |
|
176 \fn uint Q3AsciiCache::size() const |
|
177 |
|
178 Returns the size of the hash array used to implement the cache. |
|
179 This should be a bit bigger than count() is likely to be. |
|
180 */ |
|
181 |
|
182 /*! |
|
183 \fn bool Q3AsciiCache::isEmpty() const |
|
184 |
|
185 Returns TRUE if the cache is empty; otherwise returns FALSE. |
|
186 */ |
|
187 |
|
188 /*! |
|
189 \fn bool Q3AsciiCache::insert( const char *k, const type *d, int c, int p ) |
|
190 |
|
191 Inserts the item \a d into the cache using key \a k, and with an |
|
192 associated cost of \a c. Returns TRUE if the item is successfully |
|
193 inserted. Returns FALSE if the item is not inserted, for example, |
|
194 if the cost of the item exceeds maxCost(). |
|
195 |
|
196 The cache's size is limited, and if the total cost is too high, |
|
197 Q3AsciiCache will remove old, least recently used items until there |
|
198 is room for this new item. |
|
199 |
|
200 Items with duplicate keys can be inserted. |
|
201 |
|
202 The parameter \a p is internal and should be left at the default |
|
203 value (0). |
|
204 |
|
205 \warning If this function returns FALSE, you must delete \a d |
|
206 yourself. Additionally, be very careful about using \a d after |
|
207 calling this function, because any other insertions into the |
|
208 cache, from anywhere in the application or within Qt itself, could |
|
209 cause the object to be discarded from the cache and the pointer to |
|
210 become invalid. |
|
211 */ |
|
212 |
|
213 /*! |
|
214 \fn bool Q3AsciiCache::remove( const char *k ) |
|
215 |
|
216 Removes the item with key \a k and returns TRUE if the item was |
|
217 present in the cache; otherwise returns FALSE. |
|
218 |
|
219 The item is deleted if auto-deletion has been enabled, i.e., if |
|
220 you have called \link Q3PtrCollection::setAutoDelete() |
|
221 setAutoDelete(TRUE)\endlink. |
|
222 |
|
223 If there are two or more items with equal keys, the one that was |
|
224 inserted last is removed. |
|
225 |
|
226 All iterators that refer to the removed item are set to point to |
|
227 the next item in the cache's traversal order. |
|
228 |
|
229 \sa take(), clear() |
|
230 */ |
|
231 |
|
232 /*! |
|
233 \fn type *Q3AsciiCache::take( const char *k ) |
|
234 |
|
235 Takes the item associated with \a k out of the cache without |
|
236 deleting it and returns a pointer to the item taken out, or 0 |
|
237 if the key does not exist in the cache. |
|
238 |
|
239 If there are two or more items with equal keys, the one that was |
|
240 inserted last is taken. |
|
241 |
|
242 All iterators that refer to the taken item are set to point to the |
|
243 next item in the cache's traversal order. |
|
244 |
|
245 \sa remove(), clear() |
|
246 */ |
|
247 |
|
248 /*! |
|
249 \fn void Q3AsciiCache::clear() |
|
250 |
|
251 Removes all items from the cache, and deletes them if \link |
|
252 Q3PtrCollection::setAutoDelete() auto-deletion\endlink has been |
|
253 enabled. |
|
254 |
|
255 All cache iterators that operate on this cache are reset. |
|
256 |
|
257 \sa remove() take() |
|
258 */ |
|
259 |
|
260 /*! |
|
261 \fn type *Q3AsciiCache::find( const char *k, bool ref ) const |
|
262 |
|
263 Returns the item with key \a k, or 0 if the key does not exist |
|
264 in the cache. If \a ref is TRUE (the default), the item is moved |
|
265 to the front of the least recently used list. |
|
266 |
|
267 If there are two or more items with equal keys, the one that was |
|
268 inserted last is returned. |
|
269 */ |
|
270 |
|
271 /*! |
|
272 \fn type *Q3AsciiCache::operator[]( const char *k ) const |
|
273 |
|
274 Returns the item with key \a k, or 0 if \a k does not exist in |
|
275 the cache, and moves the item to the front of the least recently |
|
276 used list. |
|
277 |
|
278 If there are two or more items with equal keys, the one that was |
|
279 inserted last is returned. |
|
280 |
|
281 This is the same as find( k, TRUE ). |
|
282 |
|
283 \sa find() |
|
284 */ |
|
285 |
|
286 /*! |
|
287 \fn void Q3AsciiCache::statistics() const |
|
288 |
|
289 A debug-only utility function. Prints out cache usage, hit/miss, |
|
290 and distribution information using qDebug(). This function does |
|
291 nothing in the release library. |
|
292 */ |
|
293 |
|
294 /*! |
|
295 \class Q3AsciiCacheIterator |
|
296 \brief The Q3AsciiCacheIterator class provides an iterator for Q3AsciiCache collections. |
|
297 \compat |
|
298 |
|
299 Note that the traversal order is arbitrary; you are not guaranteed |
|
300 any particular order. If new objects are inserted into the cache |
|
301 while the iterator is active, the iterator may or may not see |
|
302 them. |
|
303 |
|
304 Multiple iterators are completely independent, even when they |
|
305 operate on the same Q3AsciiCache. Q3AsciiCache updates all iterators |
|
306 that refer an item when that item is removed. |
|
307 |
|
308 Q3AsciiCacheIterator provides an operator++() and an operator+=() |
|
309 to traverse the cache; current() and currentKey() to access the |
|
310 current cache item and its key. It also provides atFirst() and |
|
311 atLast(), which return TRUE if the iterator points to the first or |
|
312 last item in the cache respectively. The isEmpty() function |
|
313 returns TRUE if the cache is empty; and count() returns the number |
|
314 of items in the cache. |
|
315 |
|
316 Note that atFirst() and atLast() refer to the iterator's arbitrary |
|
317 ordering, not to the cache's internal least recently used list. |
|
318 |
|
319 \sa Q3AsciiCache |
|
320 */ |
|
321 |
|
322 /*! |
|
323 \fn Q3AsciiCacheIterator::Q3AsciiCacheIterator( const Q3AsciiCache<type> &cache ) |
|
324 |
|
325 Constructs an iterator for \a cache. The current iterator item is |
|
326 set to point to the first item in the \a cache. |
|
327 */ |
|
328 |
|
329 /*! |
|
330 \fn Q3AsciiCacheIterator::Q3AsciiCacheIterator (const Q3AsciiCacheIterator<type> & ci) |
|
331 |
|
332 Constructs an iterator for the same cache as \a ci. The new |
|
333 iterator starts at the same item as ci.current() but moves |
|
334 independently from there on. |
|
335 */ |
|
336 |
|
337 /*! |
|
338 \fn Q3AsciiCacheIterator<type>& Q3AsciiCacheIterator::operator=( const Q3AsciiCacheIterator<type> &ci ) |
|
339 |
|
340 Makes this an iterator for the same cache as \a ci. The new |
|
341 iterator starts at the same item as ci.current(), but moves |
|
342 independently thereafter. |
|
343 */ |
|
344 |
|
345 /*! |
|
346 \fn uint Q3AsciiCacheIterator::count() const |
|
347 |
|
348 Returns the number of items in the cache over which this iterator |
|
349 operates. |
|
350 |
|
351 \sa isEmpty() |
|
352 */ |
|
353 |
|
354 /*! |
|
355 \fn bool Q3AsciiCacheIterator::isEmpty() const |
|
356 |
|
357 Returns TRUE if the cache is empty, i.e. count() == 0; otherwise |
|
358 returns FALSE. |
|
359 |
|
360 \sa count() |
|
361 */ |
|
362 |
|
363 /*! |
|
364 \fn bool Q3AsciiCacheIterator::atFirst() const |
|
365 |
|
366 Returns TRUE if the iterator points to the first item in the |
|
367 cache; otherwise returns FALSE. Note that this refers to the |
|
368 iterator's arbitrary ordering, not to the cache's internal least |
|
369 recently used list. |
|
370 |
|
371 \sa toFirst(), atLast() |
|
372 */ |
|
373 |
|
374 /*! |
|
375 \fn bool Q3AsciiCacheIterator::atLast() const |
|
376 |
|
377 Returns TRUE if the iterator points to the last item in the cache; |
|
378 otherwise returns FALSE. Note that this refers to the iterator's |
|
379 arbitrary ordering, not to the cache's internal least recently |
|
380 used list. |
|
381 |
|
382 \sa toLast(), atFirst() |
|
383 */ |
|
384 |
|
385 /*! |
|
386 \fn type *Q3AsciiCacheIterator::toFirst() |
|
387 |
|
388 Sets the iterator to point to the first item in the cache and |
|
389 returns a pointer to the item. |
|
390 |
|
391 Sets the iterator to 0 and returns 0 if the cache is empty. |
|
392 |
|
393 \sa toLast() isEmpty() |
|
394 */ |
|
395 |
|
396 /*! |
|
397 \fn type *Q3AsciiCacheIterator::toLast() |
|
398 |
|
399 Sets the iterator to point to the last item in the cache and |
|
400 returns a pointer to the item. |
|
401 |
|
402 Sets the iterator to 0 and returns 0 if the cache is empty. |
|
403 |
|
404 \sa toFirst() isEmpty() |
|
405 */ |
|
406 |
|
407 /*! |
|
408 \fn Q3AsciiCacheIterator::operator type *() const |
|
409 |
|
410 Cast operator. Returns a pointer to the current iterator item. |
|
411 Same as current(). |
|
412 */ |
|
413 |
|
414 /*! |
|
415 \fn type *Q3AsciiCacheIterator::current() const |
|
416 |
|
417 Returns a pointer to the current iterator item. |
|
418 */ |
|
419 |
|
420 /*! |
|
421 \fn const char *Q3AsciiCacheIterator::currentKey() const |
|
422 |
|
423 Returns the key for the current iterator item. |
|
424 */ |
|
425 |
|
426 /*! |
|
427 \fn type *Q3AsciiCacheIterator::operator()() |
|
428 |
|
429 Makes the succeeding item current and returns the original current |
|
430 item. |
|
431 |
|
432 If the current iterator item was the last item in the cache or if |
|
433 it was 0, 0 is returned. |
|
434 */ |
|
435 |
|
436 /*! |
|
437 \fn type *Q3AsciiCacheIterator::operator+=( uint jump ) |
|
438 |
|
439 Returns the item \a jump positions after the current item, or 0 |
|
440 if it is beyond the last item. Makes this the current item. |
|
441 */ |
|
442 |
|
443 /*! |
|
444 \fn type *Q3AsciiCacheIterator::operator-=( uint jump ) |
|
445 |
|
446 Returns the item \a jump positions before the current item, or 0 |
|
447 if it is before the first item. Makes this the current item. |
|
448 */ |
|
449 |
|
450 /*! |
|
451 \fn type *Q3AsciiCacheIterator::operator++() |
|
452 |
|
453 Prefix ++ makes the iterator point to the item just after |
|
454 current(), and makes that the new current item for the iterator. If |
|
455 current() was the last item, operator++() returns 0. |
|
456 */ |
|
457 |
|
458 /*! |
|
459 \fn type *Q3AsciiCacheIterator::operator--() |
|
460 |
|
461 Prefix -- makes the iterator point to the item just before |
|
462 current(), and makes that the new current item for the iterator. If |
|
463 current() was the first item, operator--() returns 0. |
|
464 */ |
|
465 |