1QMemArray(3qt)                                                  QMemArray(3qt)
2
3
4

NAME

6       QMemArray - Template class that provides arrays of simple types
7

SYNOPSIS

9       All the functions in this class are reentrant when Qt is built with
10       thread support.</p>
11
12       #include <qmemarray.h>
13
14       Inherited by QByteArray and QPointArray.
15
16   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
56   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

DESCRIPTION

65       The QMemArray class is a template class that provides arrays of simple
66       types.
67
68       QMemArray is implemented as a template class. Define a template
69       instance QMemArray<X> to create an array that contains X items.
70
71       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
76       The QPtrVector collection class is also a kind of array. Like most
77       collection classes, it uses pointers to the contained items.
78
79       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
83       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
87       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
93       Example:
94
95           #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
116       Program output:
117
118           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
127       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
134           // 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
148       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
152       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
156       You can make a shallow copy of the array with assign() (or operator=())
157       and a deep copy with duplicate().
158
159       Search for values in the array with find() and contains(). For sorted
160       arrays (see sort()) you can search using bsearch().
161
162       You can set the data directly using setRawData() and resetRawData(),
163       although this requires care.
164
165       See also Shared Classes and Non-GUI Classes.
166
167   Member Type Documentation

QMemArray::ConstIterator

169       A const QMemArray iterator.
170
171       See also begin() and end().
172

QMemArray::Iterator

174       A QMemArray iterator.
175
176       See also begin() and end().
177

MEMBER FUNCTION DOCUMENTATION

QMemArray::QMemArray ( int, int ) [protected]

180       Constructs an array without allocating array space. The arguments
181       should be (0, 0). Use at your own risk.
182

QMemArray::QMemArray ()

184       Constructs a null array.
185
186       See also isNull().
187

QMemArray::QMemArray ( int size )

189       Constructs an array with room for size elements. Makes a null array if
190       size == 0.
191
192       The elements are left uninitialized.
193
194       See also resize() and isNull().
195

QMemArray::QMemArray ( const QMemArray<type> & a )

197       Constructs a shallow copy of a.
198
199       See also assign().
200

QMemArray::~QMemArray ()

202       Dereferences the array data and deletes it if this was the last
203       reference.
204

QMemArray<type> & QMemArray::assign ( const QMemArray<type> & a )

206       Shallow copy. Dereferences the current array and references the data
207       contained in a instead. Returns a reference to this array.
208
209       See also operator=().
210

QMemArray<type> & QMemArray::assign ( const type * data, uint size )

212       This is an overloaded member function, provided for convenience. It
213       behaves essentially like the above function.
214
215       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
219       Do not delete data later; QMemArray will call free() on it at the right
220       time.
221

type & QMemArray::at ( uint index ) const

223       Returns a reference to the element at position index in the array.
224
225       This can be used to both read and set an element.
226
227       See also operator[]().
228

Iterator QMemArray::begin ()

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

ConstIterator QMemArray::begin () const

235       This is an overloaded member function, provided for convenience. It
236       behaves essentially like the above function.
237
238       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

int QMemArray::bsearch ( const type & v ) const

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
247       Returns the position of v, or -1 if v could not be found.
248
249       See also sort() and find().
250

int QMemArray::contains ( const type & v ) const

252       Returns the number of times v occurs in the array.
253
254       See also find().
255

QMemArray<type> QMemArray::copy () const

257       Returns a deep copy of this array.
258
259       See also detach() and duplicate().
260

uint QMemArray::count () const

262       Returns the same as size().
263
264       See also size().
265
266       Example: scribble/scribble.cpp.
267

type * QMemArray::data () const

269       Returns a pointer to the actual array data.
270
271       The array is a null array if data() == 0 (null pointer).
272
273       See also isNull().
274
275       Examples:
276

void QMemArray::detach () [virtual]

278       Detaches this array from shared array data; i.e. it makes a private,
279       deep copy of the data.
280
281       Copying will be performed only if the reference count is greater than
282       one.
283
284       See also copy().
285
286       Reimplemented in QBitArray.
287

QMemArray<type> & QMemArray::duplicate ( const QMemArray<type> & a )

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
292       See also copy().
293

QMemArray<type> & QMemArray::duplicate ( const type * data, uint size )

295       This is an overloaded member function, provided for convenience. It
296       behaves essentially like the above function.
297
298       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
302       See also copy().
303

Iterator QMemArray::end ()

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

ConstIterator QMemArray::end () const

310       This is an overloaded member function, provided for convenience. It
311       behaves essentially like the above function.
312
313       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

bool QMemArray::fill ( const type & v, int size = -1 )

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
321       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
324       See also resize().
325

int QMemArray::find ( const type & v, uint index = 0 ) const

327       Finds the first occurrence of v, starting at position index.
328
329       Returns the position of v, or -1 if v could not be found.
330
331       See also contains().
332

bool QMemArray::isEmpty () const

334       Returns TRUE if the array is empty; otherwise returns FALSE.
335
336       isEmpty() is equivalent to isNull() for QMemArray (unlike QString).
337

bool QMemArray::isNull () const

339       Returns TRUE if the array is null; otherwise returns FALSE.
340
341       A null array has size() == 0 and data() == 0.
342

uint QMemArray::nrefs () const

344       Returns the reference count for the shared array data. This reference
345       count is always greater than zero.
346

QMemArray::operator const type * () const

348       Cast operator. Returns a pointer to the array.
349
350       See also data().
351

bool QMemArray::operator!= ( const QMemArray<type> & a ) const

353       Returns TRUE if this array is different from a; otherwise returns
354       FALSE.
355
356       The two arrays are compared bitwise.
357
358       See also operator==().
359

QMemArray<type> & QMemArray::operator= ( const QMemArray<type> & a )

361       Assigns a shallow copy of a to this array and returns a reference to
362       this array.
363
364       Equivalent to assign( a ).
365

bool QMemArray::operator== ( const QMemArray<type> & a ) const

367       Returns TRUE if this array is equal to a; otherwise returns FALSE.
368
369       The two arrays are compared bitwise.
370
371       See also operator!=().
372

type & QMemArray::operator[] ( int index ) const

374       Returns a reference to the element at position index in the array.
375
376       This can be used to both read and set an element. Equivalent to at().
377
378       See also at().
379

void QMemArray::resetRawData ( const type * data, uint size )

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
387       The arguments must be the data and length, size, that were passed to
388       setRawData(). This is for consistency checking.
389
390       See also setRawData().
391

bool QMemArray::resize ( uint size, Optimization optim )

393       Resizes (expands or shrinks) the array to size elements. The array
394       becomes a null array if size == 0.
395
396       Returns TRUE if successful, or FALSE if the memory cannot be allocated.
397
398       New elements are not initialized.
399
400       optim is either QGArray::MemOptim (the default) or QGArray::SpeedOptim.
401
402       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
405       See also size().
406
407       Example: fileiconview/qfileiconview.cpp.
408

bool QMemArray::resize ( uint size )

410       This is an overloaded member function, provided for convenience. It
411       behaves essentially like the above function.
412
413       Resizes (expands or shrinks) the array to size elements. The array
414       becomes a null array if size == 0.
415
416       Returns TRUE if successful, i.e. if the memory can be allocated;
417       otherwise returns FALSE.
418
419       New elements are not initialized.
420
421       See also size().
422

QMemArray<type> & QMemArray::setRawData ( const type * data, uint size )

424       Sets raw data and returns a reference to the array.
425
426       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
431       Setting raw data is useful because it sets QMemArray data without
432       allocating memory or copying data.
433
434       Example I (intended use):
435
436           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
443       Example II (you don't want to do this):
444
445           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
453       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
457       See also resetRawData().
458

uint QMemArray::size () const

460       Returns the size of the array (maximum number of elements).
461
462       The array is a null array if size() == 0.
463
464       See also isNull() and resize().
465

void QMemArray::sort ()

467       Sorts the array elements in ascending order, using bitwise comparison
468       (memcmp()).
469
470       See also bsearch().
471

bool QMemArray::truncate ( uint pos )

473       Truncates the array at position pos.
474
475       Returns TRUE if successful, i.e. if the memory can be allocated;
476       otherwise returns FALSE.
477
478       Equivalent to resize(pos).
479
480       See also resize().
481

QDataStream & operator<< ( QDataStream & s, const QByteArray & a )

484       Writes byte array a to the stream s and returns a reference to the
485       stream.
486
487       See also Format of the QDataStream operators.
488

QDataStream & operator>> ( QDataStream & s, QByteArray & a )

490       Reads a byte array into a from the stream s and returns a reference to
491       the stream.
492
493       See also Format of the QDataStream operators.
494

Q_UINT16 qChecksum ( const char * data, uint len )

496       Returns the CRC-16 checksum of len bytes starting at data.
497
498       The checksum is independent of the byte order (endianness).
499
500

SEE ALSO

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

AUTHOR

511       Generated automatically from the source code.
512

BUGS

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
518       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
524       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).
527
528
529
530Trolltech AS                    2 February 2007                 QMemArray(3qt)
Impressum