From ea318d1431c89e647598c510c4245c6571aa5f46 Mon Sep 17 00:00:00 2001 From: Timothy Pearson Date: Thu, 26 Jan 2012 23:32:43 -0600 Subject: Update to latest tqt3 automated conversion --- doc/html/ntqcache.html | 279 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 279 insertions(+) create mode 100644 doc/html/ntqcache.html (limited to 'doc/html/ntqcache.html') diff --git a/doc/html/ntqcache.html b/doc/html/ntqcache.html new file mode 100644 index 000000000..1d5d8ed33 --- /dev/null +++ b/doc/html/ntqcache.html @@ -0,0 +1,279 @@ + + + + + +TQCache Class + + + + + + + +

TQCache Class Reference

+ +

The TQCache class is a template class that provides a cache based on TQString keys. +More... +

#include <ntqcache.h> +

Inherits TQPtrCollection. +

List of all member functions. +

Public Members

TQCache ( int maxCost = 100, int size = 17, bool caseSensitive = TRUE )
~TQCache ()
int maxCost () const
int totalCost () const
void setMaxCost ( int m )
virtual uint count () const
uint size () const
bool isEmpty () const
virtual void clear ()
bool insert ( const TQString & k, const type * d, int c = 1, int p = 0 )
bool remove ( const TQString & k )
type * take ( const TQString & k )
type * find ( const TQString & k, bool ref = TRUE ) const
type * operator[] ( const TQString & k ) const
void statistics () const

Important Inherited Members

bool autoDelete () const
void setAutoDelete ( bool enable )

Detailed Description

+ + +The TQCache class is a template class that provides a cache based on TQString keys. +

+ +

A cache is a least recently used (LRU) list of cache items. Each +cache item has a key and a certain cost. The sum of item costs, +totalCost(), never exceeds the maximum cache cost, maxCost(). If +inserting a new item would cause the total cost to exceed the +maximum cost, the least recently used items in the cache are +removed. +

TQCache is a template class. TQCache<X> defines a cache that +operates on pointers to X, or X*. +

Apart from insert(), by far the most important function is find() +(which also exists as operator[]()). This function looks up an +item, returns it, and by default marks it as being the most +recently used item. +

There are also methods to remove() or take() an object from the +cache. Calling setAutoDelete(TRUE) for a cache tells it to delete +items that are removed. The default is to not delete items when +they are removed (i.e., remove() and take() are equivalent). +

When inserting an item into the cache, only the pointer is copied, +not the item itself. This is called a shallow copy. It is possible +to make the cache copy all of the item's data (known as a deep copy) when an item is inserted. insert() calls the virtual +function TQPtrCollection::newItem() for the item to be inserted. +Inherit a cache and reimplement newItem() if you want deep copies. +

When removing a cache item, the virtual function +TQPtrCollection::deleteItem() is called. The default +implementation deletes the item if auto-deletion is enabled, and +does nothing otherwise. +

There is a TQCacheIterator that can be used to traverse the items +in the cache in arbitrary order. +

In TQCache, the cache items are accessed via TQString keys, which +are Unicode strings. If you want to use non-Unicode, plain 8-bit +char* keys, use the TQAsciiCache template. A TQCache has the +same performance as a TQAsciiCache. +

Member Function Documentation

TQCache::TQCache ( int maxCost = 100, int size = 17, bool caseSensitive = TRUE ) +

+ +

Constructs a cache whose contents will never have a total cost +greater than maxCost and which is expected to contain less than +size items. +

size is actually the size of an internal hash array; it's +usually best to make it a prime number and at least 50% bigger +than the largest expected number of items in the cache. +

Each inserted item has an associated cost. When inserting a new +item, if the total cost of all items in the cache will exceed maxCost, the cache will start throwing out the older (least +recently used) items until there is enough room for the new item +to be inserted. +

If caseSensitive is TRUE (the default), the cache keys are case +sensitive; if it is FALSE, they are case-insensitive. +Case-insensitive comparison considers all Unicode letters. + +

TQCache::~TQCache () +

+ +

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

bool TQPtrCollection::autoDelete () const +

+ +

Returns the setting of the auto-delete option. The default is FALSE. +

void TQCache::clear () `[virtual]` +

+ +

Removes all items from the cache and deletes them if auto-deletion +has been enabled. +

All cache iterators that operate this on cache are reset. +

uint TQCache::count () const `[virtual]` +

+ +

Returns the number of items in the cache. +

type * TQCache::find ( const TQString & k, bool ref = TRUE ) const +

+ +

Returns the item associated with key k, or 0 if the key does +not exist in the cache. If ref is TRUE (the default), the item +is moved to the front of the least recently used list. +

If there are two or more items with equal keys, the one that was +inserted last is returned. + +

bool TQCache::insert ( const TQString & k, const type * d, int c = 1, int p = 0 ) +

+ +

Inserts the item d into the cache with key k and associated +cost, c. Returns TRUE if it is successfully inserted; otherwise +returns FALSE. +

The cache's size is limited, and if the total cost is too high, +TQCache will remove old, least recently used items until there is +room for this new item. +

The parameter p is internal and should be left at the default +value (0). +

Warning: If this function returns FALSE (which could happen, e.g. +if the cost of this item alone exceeds maxCost()) you must delete +d yourself. Additionally, be very careful about using d +after calling this function because any other insertions into the +cache, from anywhere in the application or within TQt itself, could +cause the object to be discarded from the cache and the pointer to +become invalid. + +

bool TQCache::isEmpty () const +

+ +

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

int TQCache::maxCost () const +

+ +

Returns the maximum allowed total cost of the cache. +

See also setMaxCost() and totalCost(). + +

type * TQCache::operator[] ( const TQString & k ) const +

+ +

Returns the item associated with key k, or 0 if k does not +exist in the cache, and moves the item to the front of the least +recently used list. +

If there are two or more items with equal keys, the one that was +inserted last is returned. +

This is the same as find( k, TRUE ). +

bool TQCache::remove ( const TQString & k ) +

+ +

Removes the item associated with k, and returns TRUE if the +item was present in the cache; otherwise returns FALSE. +

The item is deleted if auto-deletion has been enabled, i.e., if +you have called setAutoDelete(TRUE). +

If there are two or more items with equal keys, the one that was +inserted last is removed. +

All iterators that refer to the removed item are set to point to +the next item in the cache's traversal order. +

void TQPtrCollection::setAutoDelete ( bool enable ) +

+ +

Sets the collection to auto-delete its contents if enable is +TRUE and to never delete them if enable is FALSE. +

If auto-deleting is turned on, all the items in a collection are +deleted when the collection itself is deleted. This is convenient +if the collection has the only pointer to the items. +

The default setting is FALSE, for safety. If you turn it on, be +careful about copying the collection - you might find yourself +with two collections deleting the same items. +

Note that the auto-delete setting may also affect other functions +in subclasses. For example, a subclass that has a remove() +function will remove the item from its data structure, and if +auto-delete is enabled, will also delete the item. +

void TQCache::setMaxCost ( int m ) +

+ +

Sets the maximum allowed total cost of the cache to m. If the +current total cost is greater than m, some items are deleted +immediately. +

uint TQCache::size () const +

+ +

Returns the size of the hash array used to implement the cache. +This should be a bit bigger than count() is likely to be. + +

void TQCache::statistics () const +

+ +

A debug-only utility function. Prints out cache usage, hit/miss, +and distribution information using qDebug(). This function does +nothing in the release library. + +

type * TQCache::take ( const TQString & k ) +

+ +

Takes the item associated with k out of the cache without +deleting it, and returns a pointer to the item taken out, or 0 +if the key does not exist in the cache. +

If there are two or more items with equal keys, the one that was +inserted last is taken. +

All iterators that refer to the taken item are set to point to the +next item in the cache's traversal order. +

int TQCache::totalCost () const +

+ +

Returns the total cost of the items in the cache. This is an +integer in the range 0 to maxCost(). +