source: trunk/src/qt3support/tools/q3ptrdict.qdoc@ 902

Last change on this file since 902 was 846, checked in by Dmitry A. Kuminov, 15 years ago

trunk: Merged in qt 4.7.2 sources from branches/vendor/nokia/qt.
  • Property svn:eol-style set to native
File size: 9.9 KB
RevLine 
[556]1/****************************************************************************
2**
[846]3** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
[556]4** All rights reserved.
5** Contact: Nokia Corporation ([email protected])
6**
7** This file is part of the documentation of the Qt Toolkit.
8**
[846]9** $QT_BEGIN_LICENSE:FDL$
[556]10** Commercial Usage
11** Licensees holding valid Qt Commercial licenses may use this file in
12** accordance with the Qt Commercial License Agreement provided with the
[846]13** Software or, alternatively, in accordance with the terms contained in a
14** written agreement between you and Nokia.
[556]15**
[846]16** GNU Free Documentation License
17** Alternatively, this file may be used under the terms of the GNU Free
18** Documentation License version 1.3 as published by the Free Software
19** Foundation and appearing in the file included in the packaging of this
20** file.
[556]21**
22** If you have questions regarding the use of this file, please contact
23** Nokia at [email protected].
24** $QT_END_LICENSE$
25**
26****************************************************************************/
27
28/*!
29 \class Q3PtrDict
30 \brief The Q3PtrDict class is a template class that provides a dictionary based on void* keys.
31 \compat
32
33 Q3PtrDict is implemented as a template class. Define a template
34 instance Q3PtrDict\<X\> to create a dictionary that operates on
35 pointers to X (X*).
36
37 A dictionary is a collection of key-value pairs. The key is a
38 void* used for insertion, removal and lookup. The value is a
39 pointer. Dictionaries provide very fast insertion and lookup.
40
41 Example:
42 \snippet doc/src/snippets/code/doc_src_q3ptrdict.qdoc 0
43 In this example we use a dictionary to add an extra property (a
44 char*) to the line edits we're using.
45
46 See Q3Dict for full details, including the choice of dictionary
47 size, and how deletions are handled.
48
49 \sa Q3PtrDictIterator, Q3Dict, Q3AsciiDict, Q3IntDict
50*/
51
52
53/*!
54 \fn Q3PtrDict::Q3PtrDict( int size )
55
56 Constructs a dictionary using an internal hash array with the size
57 \a size.
58
59 Setting \a size to a suitably large prime number (equal to or
60 greater than the expected number of entries) makes the hash
61 distribution better and improves lookup performance.
62*/
63
64/*!
65 \fn Q3PtrDict::Q3PtrDict( const Q3PtrDict<type> &dict )
66
67 Constructs a copy of \a dict.
68
69 Each item in \a dict is inserted into this dictionary. Only the
70 pointers are copied (shallow copy).
71*/
72
73/*!
74 \fn Q3PtrDict::~Q3PtrDict()
75
76 Removes all items from the dictionary and destroys it.
77
78 All iterators that access this dictionary will be reset.
79
80 \sa setAutoDelete()
81*/
82
83/*!
84 \fn Q3PtrDict<type> &Q3PtrDict::operator=(const Q3PtrDict<type> &dict)
85
86 Assigns \a dict to this dictionary and returns a reference to this
87 dictionary.
88
89 This dictionary is first cleared and then each item in \a dict is
90 inserted into the dictionary. Only the pointers are copied
91 (shallow copy), unless newItem() has been reimplemented.
92*/
93
94/*!
95 \fn uint Q3PtrDict::count() const
96
97 Returns the number of items in the dictionary.
98
99 \sa isEmpty()
100*/
101
102/*!
103 \fn uint Q3PtrDict::size() const
104
105 Returns the size of the internal hash table (as specified in the
106 constructor).
107
108 \sa count()
109*/
110
111/*!
112 \fn void Q3PtrDict::resize( uint newsize )
113
114 Changes the size of the hash table to \a newsize. The contents of
115 the dictionary are preserved, but all iterators on the dictionary
116 become invalid.
117*/
118
119/*!
120 \fn bool Q3PtrDict::isEmpty() const
121
122 Returns TRUE if the dictionary is empty; otherwise returns FALSE.
123
124 \sa count()
125*/
126
127/*!
128 \fn void Q3PtrDict::insert( void *key, const type *item )
129
130 Inserts the \a key with the \a item into the dictionary.
131
132 Multiple items can have the same key, in which case only the last
133 item will be accessible using \l operator[]().
134
135 \a item may not be 0.
136
137 \sa replace()
138*/
139
140/*!
141 \fn void Q3PtrDict::replace( void *key, const type *item )
142
143 If the dictionary has key \a key, this key's item is replaced with
144 \a item. If the dictionary doesn't contain key \a key, \a item is
145 inserted into the dictionary using key \a key.
146
147 \a item may not be 0.
148
149 Equivalent to
150 \snippet doc/src/snippets/code/doc_src_q3ptrdict.qdoc 1
151
152 If there are two or more items with equal keys, then the most
153 recently inserted item will be replaced.
154
155 \sa insert()
156*/
157
158/*!
159 \fn bool Q3PtrDict::remove( void *key )
160
161 Removes the item associated with \a key from the dictionary.
162 Returns TRUE if successful, i.e. if \a key is in the dictionary;
163 otherwise returns FALSE.
164
165 If there are two or more items with equal keys, then the most
166 recently inserted item will be removed.
167
168 The removed item is deleted if \link
169 Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled.
170
171 All dictionary iterators that refer to the removed item will be
172 set to point to the next item in the dictionary traversal order.
173
174 \sa take(), clear(), setAutoDelete()
175*/
176
177/*!
178 \fn type *Q3PtrDict::take( void *key )
179
180 Takes the item associated with \a key out of the dictionary
181 without deleting it (even if \link Q3PtrCollection::setAutoDelete()
182 auto-deletion\endlink is enabled).
183