When +to choose the RArray and RPointerArray types

diff -r 43e37759235e -r 51a74ef9ed63 Symbian3/SDK/Source/GUID-F50003D0-402A-59E1-8F6F-8C999DC81735.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-F50003D0-402A-59E1-8F6F-8C999DC81735.dita Wed Mar 31 11:11:55 2010 +0100 @@ -0,0 +1,61 @@ + + + + + +When +to choose the RArray and RPointerArray typesDescribes 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.

+ \ No newline at end of file