1QAsciiCache(3qt) QAsciiCache(3qt)
2
6 QAsciiCache - Template class that provides a cache based on char* keys
7
9 #include <qasciicache.h>
10 Inherits QPtrCollection.
12 Public Members
14 QAsciiCache ( int maxCost = 100, int size = 17, bool caseSensitive =
15 TRUE, bool copyKeys = TRUE )
16 ~QAsciiCache ()
17 int maxCost () const
18 int totalCost () const
19 void setMaxCost ( int m )
20 virtual uint count () const
21 uint size () const
22 bool isEmpty () const
23 virtual void clear ()
24 bool insert ( const char * k, const type * d, int c = 1, int p = 0 )
25 bool remove ( const char * k )
26 type * take ( const char * k )
27 type * find ( const char * k, bool ref = TRUE ) const
28 type * operator[] ( const char * k ) const
29 void statistics () const
30
32 The QAsciiCache class is a template class that provides a cache based
33 on char* keys.
34 QAsciiCache is implemented as a template class. Define a template
36 instance QAsciiCache<X> to create a cache that operates on pointers to
37 X (X*).
38 A cache is a least recently used (LRU) list of cache items. The cache
40 items are accessed via char* keys. For Unicode keys use the QCache
41 template instead, which uses QString keys. A QCache has the same
42 performace as a QAsciiCache.
43 Each cache item has a cost. The sum of item costs, totalCost(), will
45 not exceed the maximum cache cost, maxCost(). If inserting a new item
46 would cause the total cost to exceed the maximum cost, the least
47 recently used items in the cache are removed.
48 Apart from insert(), by far the most important function is find()
50 (which also exists as operator[]()). This function looks up an item,
51 returns it, and by default marks it as being the most recently used
52 item.
53 There are also methods to remove() or take() an object from the cache.
55 Calling setAutoDelete(TRUE) tells the cache to delete items that are
56 removed. The default is to not delete items when then are removed
57 (i.e., remove() and take() are equivalent).
58 When inserting an item into the cache, only the pointer is copied, not
60 the item itself. This is called a shallow copy. It is possible to make
61 the cache copy all of the item's data (known as a deep copy) when an
62 item is inserted. insert() calls the virtual function
63 QPtrCollection::newItem() for the item to be inserted. Inherit a cache
64 and reimplement newItem() if you want deep copies.
65 When removing a cache item the virtual function
67 QPtrCollection::deleteItem() is called. Its default implementation in
68 QAsciiCache is to delete the item if auto-deletion is enabled.
69 There is a QAsciiCacheIterator which may be used to traverse the items
71 in the cache in arbitrary order.
72 See also QAsciiCacheIterator, QCache, QIntCache, Collection Classes,
74 and Non-GUI Classes.
75
78 caseSensitive = TRUE, bool copyKeys = TRUE )
79 Constructs a cache whose contents will never have a total cost greater
80 than maxCost and which is expected to contain less than size items.
81 size is actually the size of an internal hash array; it's usually best
83 to make it prime and at least 50% bigger than the largest expected
84 number of items in the cache.
85 Each inserted item has an associated cost. When inserting a new item,
87 if the total cost of all items in the cache will exceed maxCost, the
88 cache will start throwing out the older (least recently used) items
89 until there is enough room for the new item to be inserted.
90 If caseSensitive is TRUE (the default), the cache keys are case
92 sensitive; if it is FALSE, they are case-insensitive. Case-insensitive
93 comparison only affects the 26 letters in US-ASCII. If copyKeys is TRUE
94 (the default), QAsciiCache makes a copy of the cache keys, otherwise it
95 copies just the const char * pointer - slightly faster if you can
96 guarantee that the keys will never change, but very risky.
97
99 Removes all items from the cache and destroys it. All iterators that
100 access this cache will be reset.
101
103 Removes all items from the cache, and deletes them if auto-deletion has
104 been enabled.
105 All cache iterators that operate on this cache are reset.
107 See also remove() and take().
109 Reimplemented from QPtrCollection.
111
113 Returns the number of items in the cache.
114 See also totalCost() and size().
116 Reimplemented from QPtrCollection.
118
120 Returns the item with key k, or 0 if the key does not exist in the
121 cache. If ref is TRUE (the default), the item is moved to the front of
122 the least recently used list.
123 If there are two or more items with equal keys, the one that was
125 inserted last is returned.
126
128 0 )
129 Inserts the item d into the cache using key k, and with an associated
130 cost of c. Returns TRUE if the item is successfully inserted. Returns
131 FALSE if the item is not inserted, for example, if the cost of the item
132 exceeds maxCost().
133 The cache's size is limited, and if the total cost is too high,
135 QAsciiCache will remove old, least recently used items until there is
136 room for this new item.
137 Items with duplicate keys can be inserted.
139 The parameter p is internal and should be left at the default value
141 (0).
142 Warning: If this function returns FALSE, you must delete d yourself.
144 Additionally, be very careful about using d after calling this
145 function, because any other insertions into the cache, from anywhere in
146 the application or within Qt itself, could cause the object to be
147 discarded from the cache and the pointer to become invalid.
148
150 Returns TRUE if the cache is empty; otherwise returns FALSE.
151
153 Returns the maximum allowed total cost of the cache.
154 See also setMaxCost() and totalCost().
156
158 Returns the item with key k, or 0 if k does not exist in the cache, and
159 moves the item to the front of the least recently used list.
160 If there are two or more items with equal keys, the one that was
162 inserted last is returned.
163 This is the same as find( k, TRUE ).
165 See also find().
167
169 Removes the item with key k and returns TRUE if the item was present in
170 the cache; otherwise returns FALSE.
171 The item is deleted if auto-deletion has been enabled, i.e., if you
173 have called setAutoDelete(TRUE).
174 If there are two or more items with equal keys, the one that was
176 inserted last is removed.
177 All iterators that refer to the removed item are set to point to the
179 next item in the cache's traversal order.
180 See also take() and clear().
182
184 Sets the maximum allowed total cost of the cache to m. If the current
185 total cost is greater than m, some items are removed immediately.
186 See also maxCost() and totalCost().
188
190 Returns the size of the hash array used to implement the cache. This
191 should be a bit bigger than count() is likely to be.
192
194 A debug-only utility function. Prints out cache usage, hit/miss, and
195 distribution information using qDebug(). This function does nothing in
196 the release library.
197
199 Takes the item associated with k out of the cache without deleting it
200 and returns a pointer to the item taken out, or 0 if the key does not
201 exist in the cache.
202 If there are two or more items with equal keys, the one that was
204 inserted last is taken.
205 All iterators that refer to the taken item are set to point to the next
207 item in the cache's traversal order.
208 See also remove() and clear().
210
212 Returns the total cost of the items in the cache. This is an integer in
213 the range 0 to maxCost().
214 See also setMaxCost().
216
219 http://doc.trolltech.com/qasciicache.html
220 http://www.trolltech.com/faq/tech.html
221
223 Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com. See the
224 license file included in the distribution for a complete license
225 statement.
226
228 Generated automatically from the source code.
229
231 If you find a bug in Qt, please report it as described in
232 http://doc.trolltech.com/bughowto.html. Good bug reports help us to
233 help you. Thank you.
234 The definitive Qt documentation is provided in HTML format; it is
236 located at $QTDIR/doc/html and can be read using Qt Assistant or with a
237 web browser. This man page is provided as a convenience for those users
238 who prefer man pages, although this format is not officially supported
239 by Trolltech.
240 If you find errors in this manual page, please report them to qt-
242 bugs@trolltech.com. Please include the name of the manual page
243 (qasciicache.3qt) and the Qt version (3.3.8).
244Trolltech AS 2 February 2007 QAsciiCache(3qt)