LCleanedupArray Class Reference

#include <emanaged.h>

class LCleanedupArray : protected LAutoPtrBase

Inherits from

Detailed Description

A class template that provides CleanupStack-based local-scope automatic management of arrays.

Note:

This class can only be used to define locals, never data members. See below for an explanation and links to management classes suitable for use in different contexts. It should never be used in the same function as code that uses the CleanupStack API directly

Note:

This class can only be used with raw arrays, which are used only rarely on Symbian OS. Instances of Symbian array container classes (e.g. RArray, RPointerArray) should be managed using the automatic management template classes appropriate for the array's type (LCleanedupHandle template classes for Symbian R arrays or LCleanedupPtr template classes for Symbian C arrays).

This class template can be used to protect a heap-allocated array of objects of type T such that the array of T referred to is automatically cleaned up when either of the following occur:
  • The referring local variable goes out of scope normally

  • The referring local variable goes out of scope due to an untrapped leave causing the scope to be exited non-locally

The default cleanup strategy is to deallocate the managed array using arrray delete (delete[]), assuming that the array is heap-allocated. An alternative cleanup strategy can be selected by specifying a cleanup strategy template class as the optional second template argument (corresponding to the CleanupStrategy template parameter).

The constructors of this class may leave.

As a convenience, the elements of the managed array may be accessed via "[]" notation directly on the management object.

Automatic cleanup may be disabled at any time by calling Unmanage(), while cleanup may be forced at any time by calling ReleaseResource().

	// block scope example
	{
	LCleanedupArray<TValue> arrayp(new(ELeave) TValue[KArraySize]);
	arrayp[0].DoSomethingL(); // leave-safe
	if (arrayp[0].Finished())
		return; //	the array is deleted automatically when exiting from scope
	arrayp[1].DoSomethingElseL(); // leave-safe
	//	the array is deleted automatically when exiting from scope
	}

Behind the scenes, this class template is implemented in terms of the thread-local CleanupStack, restricting its use to locals on the stack. This use of the CleanupStack ensures a consistent cleanup order between functions that call one another, even if they use different cleanup idioms.

This class template together with the cleanup strategy class templates provide a template-based implementation of the Strategy design pattern (See also: Policy-based design).

See also: LManagedArray which has the same interface, but does not use the cleanup stack and is suitable for protecting the data members of classes

Member Type Definition Documentation

Typedef CleanupStrategy

typedef CleanupStrategyTypeCleanupStrategy

Typedef ManagedType

typedef TManagedType

Constructor & Destructor Documentation

LCleanedupArray ( )

LCleanedupArray()[inline]

Default constructor. Constructs an empty LCleanedupArray object.

Post-condition
Get() == NULL

LCleanedupArray ( T * )

LCleanedupArray(T *aPtr)[inline, explicit]

Explicit constructor. Constructs a LCleanedupArray object that manages an array of objects of type T that can be cleaned up using the cleanup strategy of the LCleanedupArray class. The default cleanup strategy is to deallocate the heap-allocated array by using array delete. An alternative cleanup strategy can be selected by specifying a cleanup strategy template class as the optional second template argument (corresponding to the CleanupStrategy template parameter).

Pre-condition
The array can be cleaned up using the cleanup strategy.
Post-condition
Get() == aPtr
Parameters
aPtrA pointer to the first element of an array of objects of type T, array that can be cleaned up using the cleanup strategy of the the LCleanedupArray class.

~LCleanedupArray ( )

~LCleanedupArray()[inline]

Destructor. When automatic resource management is enabled, the destructor invokes the specified cleanup strategy for the managed pointer.

Member Function Documentation

Cleanup ( TAny * )

voidCleanup(TAny *aPtr)[static, inline]

ReleaseResource ( )

voidReleaseResource()[inline]

If automatic resource management is enabled, the specified cleanup strategy is invoked for the managed pointer and the automatic resource management is then disabled. The underlying pointer is reset to NULL.

Post-condition
Get() == NULL

Swap ( LCleanedupArray & )

voidSwap(LCleanedupArray &aArray)[inline]

operator= ( T * )

LCleanedupArray &operator=(T *aPtr)[inline]

Reimplemented from LAutoPtrBase::operator=(T *)

Assigns a new array of objects of type T to be managed. It needs to be be possible to use the cleanup strategy of the LCleanedupArray object for the cleanup of the new managed array. The default cleanup strategy is to delete the heap-allocated array by using array delete (delete[]). If the LCleanedupArray object already manages an array, then the cleanup strategy is invoked with the managed array before assigning the new managed array.

Pre-condition
The new array to be managed can be cleaned up using the cleanup strategy.
Post-condition
Get() == aPtr
Parameters
aPtrA pointer to the first element of the array of objects of type T - array that can be cleaned up using the cleanup strategy.

operator[] ( TInt )

T &operator[](TIntaIndex)const [inline]

Overloaded subscript operator.

Return Value
A reference to the object of type T at the position aIndex.