1QMemArray(3qt) QMemArray(3qt)
2
6 QMemArray - Template class that provides arrays of simple types
7
9 All the functions in this class are reentrant when Qt is built with
10 thread support.</p>
11 #include <qmemarray.h>
13 Inherited by QByteArray and QPointArray.
15 Public Members
17 typedef type * Iterator
18 typedef const type * ConstIterator
19 QMemArray ()
20 QMemArray ( int size )
21 QMemArray ( const QMemArray<type> & a )
22 ~QMemArray ()
23 QMemArray<type> & operator= ( const QMemArray<type> & a )
24 type * data () const
25 uint nrefs () const
26 uint size () const
27 uint count () const
28 bool isEmpty () const
29 bool isNull () const
30 bool resize ( uint size )
31 bool resize ( uint size, Optimization optim )
32 bool truncate ( uint pos )
33 bool fill ( const type & v, int size = -1 )
34 virtual void detach ()
35 QMemArray<type> copy () const
36 QMemArray<type> & assign ( const QMemArray<type> & a )
37 QMemArray<type> & assign ( const type * data, uint size )
38 QMemArray<type> & duplicate ( const QMemArray<type> & a )
39 QMemArray<type> & duplicate ( const type * data, uint size )
40 QMemArray<type> & setRawData ( const type * data, uint size )
41 void resetRawData ( const type * data, uint size )
42 int find ( const type & v, uint index = 0 ) const
43 int contains ( const type & v ) const
44 void sort ()
45 int bsearch ( const type & v ) const
46 type & operator[] ( int index ) const
47 type & at ( uint index ) const
48 operator const type * () const
49 bool operator== ( const QMemArray<type> & a ) const
50 bool operator!= ( const QMemArray<type> & a ) const
51 Iterator begin ()
52 Iterator end ()
53 ConstIterator begin () const
54 ConstIterator end () const
55 Protected Members
57 QMemArray ( int, int )
58
60 Q_UINT16 qChecksum ( const char * data, uint len )
61 QDataStream & operator<< ( QDataStream & s, const QByteArray & a )
62 QDataStream & operator>> ( QDataStream & s, QByteArray & a )
63
65 The QMemArray class is a template class that provides arrays of simple
66 types.
67 QMemArray is implemented as a template class. Define a template
69 instance QMemArray<X> to create an array that contains X items.
70 QMemArray stores the array elements directly in the array. It can only
72 deal with simple types (i.e. C++ types, structs, and classes that have
73 no constructors, destructors, or virtual functions). QMemArray uses
74 bitwise operations to copy and compare array elements.
75 The QPtrVector collection class is also a kind of array. Like most
77 collection classes, it uses pointers to the contained items.
78 QMemArray uses explicit sharing with a reference count. If more than
80 one array shares common data and one of the arrays is modified, all the
81 arrays are modified.
82 The benefit of sharing is that a program does not need to duplicate
84 data when it is not required, which results in lower memory use and
85 less copying of data.
86 An alternative to QMemArray is QValueVector. The QValueVector class
88 also provides an array of objects, but can deal with objects that have
89 constructors (specifically a copy constructor and a default
90 constructor). QValueVector provides an STL-compatible syntax and is
91 implicitly shared.
92 Example:
94 #include <qmemarray.h>
96 #include <stdio.h>
97 QMemArray<int> fib( int num ) // returns fibonacci array
98 {
99 Q_ASSERT( num > 2 );
100 QMemArray<int> f( num ); // array of ints
101 f[0] = f[1] = 1;
102 for ( int i = 2; i < num; i++ )
103 f[i] = f[i-1] + f[i-2];
104 return f;
105 }
106 int main()
107 {
108 QMemArray<int> a = fib( 6 ); // get first 6 fibonaccis
109 for ( int i = 0; i < a.size(); i++ )
110 qDebug( "%d: %d", i, a[i] );
111 qDebug( "1 is found %d times", a.contains(1) );
112 qDebug( "5 is found at index %d", a.find(5) );
113 return 0;
114 }
115 Program output:
117 0: 1
119 1: 1
120 2: 2
121 3: 3
122 4: 5
123 5: 8
124 1 is found 2 times
125 5 is found at index 4
126 Note concerning the use of QMemArray for manipulating structs or
128 classes: Compilers will often pad the size of structs of odd sizes up
129 to the nearest word boundary. This will then be the size QMemArray will
130 use for its bitwise element comparisons. Because the remaining bytes
131 will typically be uninitialized, this can cause find() etc. to fail to
132 find the element. Example:
133 // MyStruct may be padded to 4 or 8 bytes
135 struct MyStruct
136 {
137 short i; // 2 bytes
138 char c; // 1 byte
139 };
140 QMemArray<MyStruct> a(1);
141 a[0].i = 5;
142 a[0].c = 't';
143 MyStruct x;
144 x.i = '5';
145 x.c = 't';
146 int i = a.find( x ); // may return -1 if the pad bytes differ
147 To work around this, make sure that you use a struct where sizeof()
149 returns the same as the sum of the sizes of the members either by
150 changing the types of the struct members or by adding dummy members.
151 QMemArray data can be traversed by iterators (see begin() and end()).
153 The number of items is returned by count(). The array can be resized
154 with resize() and filled using fill().
155 You can make a shallow copy of the array with assign() (or operator=())
157 and a deep copy with duplicate().
158 Search for values in the array with find() and contains(). For sorted
160 arrays (see sort()) you can search using bsearch().
161 You can set the data directly using setRawData() and resetRawData(),
163 although this requires care.
164 See also Shared Classes and Non-GUI Classes.
166 Member Type Documentation
169 A const QMemArray iterator.
170 See also begin() and end().
172
174 A QMemArray iterator.
175 See also begin() and end().
177
180 Constructs an array without allocating array space. The arguments
181 should be (0, 0). Use at your own risk.
182
184 Constructs a null array.
185 See also isNull().
187
189 Constructs an array with room for size elements. Makes a null array if
190 size == 0.
191 The elements are left uninitialized.
193 See also resize() and isNull().
195
197 Constructs a shallow copy of a.
198 See also assign().
200
202 Dereferences the array data and deletes it if this was the last
203 reference.
204
206 Shallow copy. Dereferences the current array and references the data
207 contained in a instead. Returns a reference to this array.
208 See also operator=().
210
212 This is an overloaded member function, provided for convenience. It
213 behaves essentially like the above function.
214 Shallow copy. Dereferences the current array and references the array
216 data data, which contains size elements. Returns a reference to this
217 array.
218 Do not delete data later; QMemArray will call free() on it at the right
220 time.
221
223 Returns a reference to the element at position index in the array.
224 This can be used to both read and set an element.
226 See also operator[]().
228
230 Returns an iterator pointing at the beginning of this array. This
231 iterator can be used in the same way as the iterators of QValueList and
232 QMap, for example.
233
235 This is an overloaded member function, provided for convenience. It
236 behaves essentially like the above function.
237 Returns a const iterator pointing at the beginning of this array. This
239 iterator can be used in the same way as the iterators of QValueList and
240 QMap, for example.
241
243 In a sorted array (as sorted by sort()), finds the first occurrence of
244 v by using a binary search. For a sorted array this is generally much
245 faster than find(), which does a linear search.
246 Returns the position of v, or -1 if v could not be found.
248 See also sort() and find().
250
252 Returns the number of times v occurs in the array.
253 See also find().
255
257 Returns a deep copy of this array.
258 See also detach() and duplicate().
260
262 Returns the same as size().
263 See also size().
265 Example: scribble/scribble.cpp.
267
269 Returns a pointer to the actual array data.
270 The array is a null array if data() == 0 (null pointer).
272 See also isNull().
274 Examples:
276
278 Detaches this array from shared array data; i.e. it makes a private,
279 deep copy of the data.
280 Copying will be performed only if the reference count is greater than
282 one.
283 See also copy().
285 Reimplemented in QBitArray.
287
289 Deep copy. Dereferences the current array and obtains a copy of the
290 data contained in a instead. Returns a reference to this array.
291 See also copy().
293
295 This is an overloaded member function, provided for convenience. It
296 behaves essentially like the above function.
297 Deep copy. Dereferences the current array and obtains a copy of the
299 array data data instead. Returns a reference to this array. The size of
300 the array is given by size.
301 See also copy().
303
305 Returns an iterator pointing behind the last element of this array.
306 This iterator can be used in the same way as the iterators of
307 QValueList and QMap, for example.
308
310 This is an overloaded member function, provided for convenience. It
311 behaves essentially like the above function.
312 Returns a const iterator pointing behind the last element of this
314 array. This iterator can be used in the same way as the iterators of
315 QValueList and QMap, for example.
316
318 Fills the array with the value v. If size is specified as different
319 from -1, then the array will be resized before being filled.
320 Returns TRUE if successful, i.e. if size is -1, or size is != -1 and
322 the memory can be allocated; otherwise returns FALSE.
323 See also resize().
325
327 Finds the first occurrence of v, starting at position index.
328 Returns the position of v, or -1 if v could not be found.
330 See also contains().
332
334 Returns TRUE if the array is empty; otherwise returns FALSE.
335 isEmpty() is equivalent to isNull() for QMemArray (unlike QString).
337
339 Returns TRUE if the array is null; otherwise returns FALSE.
340 A null array has size() == 0 and data() == 0.
342
344 Returns the reference count for the shared array data. This reference
345 count is always greater than zero.
346
348 Cast operator. Returns a pointer to the array.
349 See also data().
351
353 Returns TRUE if this array is different from a; otherwise returns
354 FALSE.
355 The two arrays are compared bitwise.
357 See also operator==().
359
361 Assigns a shallow copy of a to this array and returns a reference to
362 this array.
363 Equivalent to assign( a ).
365
367 Returns TRUE if this array is equal to a; otherwise returns FALSE.
368 The two arrays are compared bitwise.
370 See also operator!=().
372
374 Returns a reference to the element at position index in the array.
375 This can be used to both read and set an element. Equivalent to at().
377 See also at().
379
381 Removes internal references to the raw data that was set using
382 setRawData(). This means that QMemArray no longer has access to the
383 data, so you are free to manipulate data as you wish. You can now use
384 the QMemArray without affecting the original data, for example by
385 calling setRawData() with a pointer to some other data.
386 The arguments must be the data and length, size, that were passed to
388 setRawData(). This is for consistency checking.
389 See also setRawData().
391
393 Resizes (expands or shrinks) the array to size elements. The array
394 becomes a null array if size == 0.
395 Returns TRUE if successful, or FALSE if the memory cannot be allocated.
397 New elements are not initialized.
399 optim is either QGArray::MemOptim (the default) or QGArray::SpeedOptim.
401 Note: By default, SpeedOptim is not available for general use since it
403 is only available if Qt is built in a particular configuration.
404 See also size().
406 Example: fileiconview/qfileiconview.cpp.
408
410 This is an overloaded member function, provided for convenience. It
411 behaves essentially like the above function.
412 Resizes (expands or shrinks) the array to size elements. The array
414 becomes a null array if size == 0.
415 Returns TRUE if successful, i.e. if the memory can be allocated;
417 otherwise returns FALSE.
418 New elements are not initialized.
420 See also size().
422
424 Sets raw data and returns a reference to the array.
425 Dereferences the current array and sets the new array data to data and
427 the new array size to size. Do not attempt to resize or re-assign the
428 array data when raw data has been set. Call resetRawData(data, size) to
429 reset the array.
430 Setting raw data is useful because it sets QMemArray data without
432 allocating memory or copying data.
433 Example I (intended use):
435 static char bindata[] = { 231, 1, 44, ... };
437 QByteArray a;
438 a.setRawData( bindata, sizeof(bindata) ); // a points to bindata
439 QDataStream s( a, IO_ReadOnly ); // open on a's data
440 s >> <something>; // read raw bindata
441 a.resetRawData( bindata, sizeof(bindata) ); // finished
442 Example II (you don't want to do this):
444 static char bindata[] = { 231, 1, 44, ... };
446 QByteArray a, b;
447 a.setRawData( bindata, sizeof(bindata) ); // a points to bindata
448 a.resize( 8 ); // will crash
449 b = a; // will crash
450 a[2] = 123; // might crash
451 // forget to resetRawData: will crash
452 Warning: If you do not call resetRawData(), QMemArray will attempt to
454 deallocate or reallocate the raw data, which might not be too good. Be
455 careful.
456 See also resetRawData().
458
460 Returns the size of the array (maximum number of elements).
461 The array is a null array if size() == 0.
463 See also isNull() and resize().
465
467 Sorts the array elements in ascending order, using bitwise comparison
468 (memcmp()).
469 See also bsearch().
471
473 Truncates the array at position pos.
474 Returns TRUE if successful, i.e. if the memory can be allocated;
476 otherwise returns FALSE.
477 Equivalent to resize(pos).
479 See also resize().
481
484 Writes byte array a to the stream s and returns a reference to the
485 stream.
486 See also Format of the QDataStream operators.
488
490 Reads a byte array into a from the stream s and returns a reference to
491 the stream.
492 See also Format of the QDataStream operators.
494
496 Returns the CRC-16 checksum of len bytes starting at data.
497 The checksum is independent of the byte order (endianness).
499
502 http://doc.trolltech.com/qmemarray.html
503 http://www.trolltech.com/faq/tech.html
504
506 Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com. See the
507 license file included in the distribution for a complete license
508 statement.
509
511 Generated automatically from the source code.
512
514 If you find a bug in Qt, please report it as described in
515 http://doc.trolltech.com/bughowto.html. Good bug reports help us to
516 help you. Thank you.
517 The definitive Qt documentation is provided in HTML format; it is
519 located at $QTDIR/doc/html and can be read using Qt Assistant or with a
520 web browser. This man page is provided as a convenience for those users
521 who prefer man pages, although this format is not officially supported
522 by Trolltech.
523 If you find errors in this manual page, please report them to qt-
525 bugs@trolltech.com. Please include the name of the manual page
526 (qmemarray.3qt) and the Qt version (3.3.8).
527Trolltech AS 2 February 2007 QMemArray(3qt)