Using +RPointerArray<class T>

Freeing all +memory before the array goes out of scope

By convention, class +names starting with the letter R do not allocate memory on +the heap. RPointerArray<class T> is an exception and +this should be remembered when using the class.

If an array is declared +on the program stack, then its Close() or Reset() member +function must be called to ensure that allocated memory is freed.

Similarly, +if RPointerArray<class T> is a data member of another +class, then the destructor of that class must call Close() or Reset().

Another +issue to remember is the ownership of objects whose pointers are contained +within an RPointerArray<class T> array. If ownership of +the objects lies elsewhere, then calling Close() or Reset() before +the array goes out of scope is sufficient. If, however, ownership of these +objects is vested in the array, and it is the intention that these objects +be destroyed when the array is destroyed, then ResetAndDestroy() must +be called before the array goes out of scope.

Packaging the +algorithm for ordering array objects

A RPointerArray<class +T> array allows its contained pointers to be ordered so that the +objects themselves are in object order. The array provides the behaviour for +inserting and sorting instances of pointers to the template class. To help +with this, the template class must provide an algorithm for deciding how two +template class objects are ordered. This algorithm is implemented by a function +which must be wrapped in a TLinearOrder<class T> package.

The +function implementing the algorithm can be a static member of the class but +need not necessarily be so.

Here, we aim to build an array of CMyTest objects +ordered in a way which makes sense for the CTMyTest class.

class CMyTest + { +public + ~CMyTest(); + Static CMytest* NewL(const TDesC& aText); + static TInt Compare(const CMyTest& aFirst, const CMyTest& Second); +public: + HBufC* iText; + };

In this example, the algorithm is implemented by a static +function called Compare(). It takes const references to two CMyTest objects +and returns zero if the objects are equal, a negative value if aFirst is +less than aSecond and a positive value if aFirst is +greater than aSecond.

TInt CMyTest::Compare(const CMyTest& aFirst,const CMyTest& aSecond) + { + TInt ret = (aFirst.iText)->Compare(*aSecond.iText); + if (ret > 0) + return 1; + if (ret < 0) + return -1; + return 0; + }

Construct three CMyTest objects and then +construct an array object for an array of pointers to CMyTest objects; +the array has default granularity.

_LIT(KTextOne,"First Text"); +_LIT(KTextTwo,"Second Text"); +_LIT(KTextThree,"Third Text"); +... +CMyTest* one = CMyTest::NewL(KTextOne); +CMyTest* two = CMyTest::NewL(KTextTwo); +CMyTest* three = CMyTest::NewL(KTextThree); +... +RPointerArray<CMyTest> x;

There are at least three ways +of proceeding, some of which are more efficient than others.

Explicitly build a TLinearOrder<CMyTest> and +pass this as a parameter to InsertInOrder().

... +TLinearOrder<CMyTest> order(CMyTest::Compare); +... +x.InsertInOrder(one,order); +...

Construct a temporary TLinearOrder<CMyTest> on +the call to InsertInOrder().

... +x.InsertInOrder(one,TLinearOrder<CMyTest>(CMyTest::Compare)); +...

Implicitly construct +a temporary TLinearOrder<CMyTest> on the call to InsertOrder().

... +x.InsertInOrder(one,CMyTest::Compare); +...

This applies to all member functions of RPointerArray<class +T> which take a TLinearOrder<class T> argument.