1QAsciiCache(3qt)                                              QAsciiCache(3qt)
2
3
4

NAME

6       QAsciiCache - Template class that provides a cache based on char* keys
7

SYNOPSIS

9       #include <qasciicache.h>
10
11       Inherits QPtrCollection.
12
13   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

DESCRIPTION

32       The QAsciiCache class is a template class that provides a cache based
33       on char* keys.
34
35       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
39       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
44       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
49       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
54       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
59       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
66       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
70       There is a QAsciiCacheIterator which may be used to traverse the items
71       in the cache in arbitrary order.
72
73       See also QAsciiCacheIterator, QCache, QIntCache, Collection Classes,
74       and Non-GUI Classes.
75

MEMBER FUNCTION DOCUMENTATION

QAsciiCache::QAsciiCache ( int maxCost = 100, int size = 17, bool

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
82       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
86       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
91       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

QAsciiCache::~QAsciiCache ()

99       Removes all items from the cache and destroys it. All iterators that
100       access this cache will be reset.
101

void QAsciiCache::clear () [virtual]

103       Removes all items from the cache, and deletes them if auto-deletion has
104       been enabled.
105
106       All cache iterators that operate on this cache are reset.
107
108       See also remove() and take().
109
110       Reimplemented from QPtrCollection.
111

uint QAsciiCache::count () const [virtual]

113       Returns the number of items in the cache.
114
115       See also totalCost() and size().
116
117       Reimplemented from QPtrCollection.
118

type * QAsciiCache::find ( const char * k, bool ref = TRUE ) const

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
124       If there are two or more items with equal keys, the one that was
125       inserted last is returned.
126

bool QAsciiCache::insert ( const char * k, const type * d, int c = 1, int p =

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
134       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
138       Items with duplicate keys can be inserted.
139
140       The parameter p is internal and should be left at the default value
141       (0).
142
143       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

bool QAsciiCache::isEmpty () const

150       Returns TRUE if the cache is empty; otherwise returns FALSE.
151

int QAsciiCache::maxCost () const

153       Returns the maximum allowed total cost of the cache.
154
155       See also setMaxCost() and totalCost().
156

type * QAsciiCache::operator[] ( const char * k ) const

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
161       If there are two or more items with equal keys, the one that was
162       inserted last is returned.
163
164       This is the same as find( k, TRUE ).
165
166       See also find().
167

bool QAsciiCache::remove ( const char * k )

169       Removes the item with key k and returns TRUE if the item was present in
170       the cache; otherwise returns FALSE.
171
172       The item is deleted if auto-deletion has been enabled, i.e., if you
173       have called setAutoDelete(TRUE).
174
175       If there are two or more items with equal keys, the one that was
176       inserted last is removed.
177
178       All iterators that refer to the removed item are set to point to the
179       next item in the cache's traversal order.
180
181       See also take() and clear().
182

void QAsciiCache::setMaxCost ( int m )

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
187       See also maxCost() and totalCost().
188

uint QAsciiCache::size () const

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

void QAsciiCache::statistics () const

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

type * QAsciiCache::take ( const char * k )

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
203       If there are two or more items with equal keys, the one that was
204       inserted last is taken.
205
206       All iterators that refer to the taken item are set to point to the next
207       item in the cache's traversal order.
208
209       See also remove() and clear().
210

int QAsciiCache::totalCost () const

212       Returns the total cost of the items in the cache. This is an integer in
213       the range 0 to maxCost().
214
215       See also setMaxCost().
216
217

SEE ALSO

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

AUTHOR

228       Generated automatically from the source code.
229

BUGS

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
235       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
241       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).
244
245
246
247Trolltech AS                    2 February 2007               QAsciiCache(3qt)
Impressum