Q3MemArray Class Reference
[Qt3Support module]

Detailed Description

The Q3MemArray class is a template class that provides arrays of simple types.

Q3MemArray is implemented as a template class. Define a template instance Q3MemArray<X> to create an array that contains X items.

Q3MemArray stores the array elements directly in the array. It can only deal with simple types (i.e. C++ types, structs, and classes that have no constructors, destructors, or virtual functions). Q3MemArray uses bitwise operations to copy and compare array elements.

The Q3PtrVector collection class is also a kind of array. Like most old Qt collection classes, it uses pointers to the contained items.

Q3MemArray uses explicit sharing with a reference count. If more than one array shares common data and one of the arrays is modified, all the arrays are modified.

The benefit of sharing is that a program does not need to duplicate data when it is not required, which results in lower memory use and less copying of data.

Example:

 #include <q3memarray.h>
 #include <stdio.h>

 Q3MemArray<int> fib( int num ) // returns fibonacci array
 {
     Q_ASSERT( num > 2 );
     Q3MemArray<int> f( num ); // array of ints

     f[0] = f[1] = 1;
     for ( int i = 2; i < num; i++ )
         f[i] = f[i-1] + f[i-2];

     return f;
 }

 int main()
 {
     Q3MemArray<int> a = fib( 6 ); // get first 6 fibonaccis
     for ( int i = 0; i < a.size(); i++ )
         qDebug( "%d: %d", i, a[i] );

     qDebug( "1 is found %d times", a.contains(1) );
     qDebug( "5 is found at index %d", a.find(5) );

     return 0;
 }

Program output:

 0: 1
 1: 1
 2: 2
 3: 3
 4: 5
 5: 8
 1 is found 2 times
 5 is found at index 4

Note concerning the use of Q3MemArray for manipulating structs or classes: Compilers will often pad the size of structs of odd sizes up to the nearest word boundary. This will then be the size Q3MemArray will use for its bitwise element comparisons. Because the remaining bytes will typically be uninitialized, this can cause find() etc. to fail to find the element. Example:

 // MyStruct may be padded to 4 or 8 bytes
 struct MyStruct
 {
     short i; // 2 bytes
     char c;  // 1 byte
 };

 Q3MemArray<MyStruct> a(1);
 a[0].i = 5;
 a[0].c = 't';

 MyStruct x;
 x.i = '5';
 x.c = 't';
 int i = a.find( x ); // may return -1 if the pad bytes differ

To work around this, make sure that you use a struct where sizeof() returns the same as the sum of the sizes of the members either by changing the types of the struct members or by adding dummy members.

Q3MemArray data can be traversed by iterators (see begin() and end()). The number of items is returned by count(). The array can be resized with resize() and filled using fill().

You can make a shallow copy of the array with assign() (or operator=()) and a deep copy with duplicate().

Search for values in the array with find() and contains(). For sorted arrays (see sort()) you can search using bsearch().

You can set the data directly using setRawData() and resetRawData(), although this requires care.

Member Type Documentation

 static char bindata[] = { 231, 1, 44, ... };
 QByteArray      a;
 a.setRawData( bindata, sizeof(bindata) );       // a points to bindata
 QDataStream s( a, IO_ReadOnly );                // open on a's data
 s >> <something>;                               // read raw bindata
 a.resetRawData( bindata, sizeof(bindata) ); // finished

 static char bindata[] = { 231, 1, 44, ... };
 QByteArray      a, b;
 a.setRawData( bindata, sizeof(bindata) );       // a points to bindata
 a.resize( 8 );                          // will crash
 b = a;                                  // will crash
 a[2] = 123;                                     // might crash
 // forget to resetRawData: will crash