When to choose the RArray and RPointerArray types

Describes the occasions to use the RArray and RPointerArray types.

The classes RArray, RPointerArray and the specialisation classes for arrays of 32-bit integers, RArray<TInt> and RArray<TUint>, provide behaviour equivalent to the CArrayFixFlat andCArrayPtrFlat classes.

In general, the implementation of the CArray... classes reuses the CBufBase framework to provide two alternative storage structures for the array data with very little CArray... specific code. There are two assertions for every array access, one in the CArray... code and one in the CBufBase code.

In addition, the CBufBase code operates in terms of byte buffers, and these appear in the API as descriptors. In the implementation, this requires a TPtr8 to be constructed, returned and inspected for every array access.

Also, a number of TRAP harnesses are used to catch allocation failure.

This means that, although very powerful, the implementation of the CArray... classes can add considerable overhead for simple vector-like flat arrays of fixed length objects.

The RArray... classes were developed to overcome these problems. In addition, the generic searching and ordering capabilities are faster and easier to use. These classes should be used whenever an array of fixed length objects or an array of pointers is required, and the array has the following characteristics:

• the size of an array element is bounded (the current implementation imposes an upper limit of 640)

• insertions into the array are infrequent

In contrast, the main benefit to be derived from the CArray... classes is their support for segmented storage and their ability to handle arrays of variable length objects. However, the latter is a rare requirement.

Note that for performance reasons, RArray stores objects in the array as word (4 byte) aligned quantities. This means that some member functions do not work when RArray is instantiated for classes of less than 4 bytes in size, or when the class's alignment requirement is not 4. Be aware that it is possible to get an unhandled exception on hardware that enforces strict alignment.

The affected functions are:

• the constructor: RArray(TInt, T*, TInt)

• Append(const T&)

• Insert(const T&, TInt)

• the [] operator, and then using the pointer to iterate through the array as you would with a C array.