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: