// Copyright (c) 2008-2009 Nokia Corporation and/or its subsidiary(-ies).

// All rights reserved.

// This component and the accompanying materials are made available

// under the terms of "Eclipse Public License v1.0"

// which accompanies this distribution, and is available

// at the URL "http://www.eclipse.org/legal/epl-v10.html".

//

// Initial Contributors:

// Nokia Corporation - initial contribution.

//

// Contributors:

//

// Description:

//

#include <e32std.h>

#include <f32file.h>

#include <e32test.h>

#include <euserhl.h>

// Note: Methods are defined inline within classes here simply to make

// the code shorter, keep related code closer together, and hopefully

// make things easier to follow.

RTest test(_L("EuserHl Walkthrough"));

// Some dummy methods and data used in the walkthroughs below

_LIT(KFill, "XXX");

_LIT(KPath, "c:\\a\\b\\c");

_LIT(KOne, "One ");

_LIT(KTwo, "Two ");

_LIT(KTesting, "Testing ");

void MaybeLeaveL()

	{

	// Some code that may leave

	}

HBufC* AllocateNameL(const TDesC& aDes)

	{

	return aDes.AllocL();

	}

void ReadToMax(TDes& aDes)

	{

	aDes.SetMax();

	aDes.Repeat(KFill);

	}

void GetCurrentPath(TDes& aDes)

	{

	aDes = KPath;

	}

void GetCurrentPathStringL(LString& aString)

	{

	aString = L"c:\\a\\b\\c"; // Will auto-grow if necessary, may leave

	}

LString AppendCurrentPathStringL(LString aString)

	{

	return aString+= L"c:\\a\\b\\c";

	}

class CTicker : public CBase

	{

public:

	void Tick() { ++iTicks; }

	void Tock() { ++iTocks; }

	void Zap() { delete this; }

public:

	TInt iTicks;

	TInt iTocks;

	};

// Defines a custom pointer cleanup policy that calls the Zap member

class TTickerZapStrategy

	{

public:

	static void Cleanup(CTicker* aPtr)

		{

		// The general template/class scaffolding remains the same

		// for all custom cleanups, just this cleanup body varies

		aPtr->Zap();

		test.Printf(_L("Zapped CTicker\n"));

		}

	};

void RegisterTicker(CTicker& aTicker)

	{

	(void)aTicker;

	}

void RegisterTickerPtr(CTicker* aTicker)

	{

	(void)aTicker;

	}

void TakeTickerOwnership(CTicker* aTicker)

	{

	delete aTicker;

	}

void RegisterTimer(RTimer& aTimer)

	{

	(void)aTimer;

	}

// Defines a custom handle cleanup policy that calls Cancel then Close

class TCancelClose

	{

public:

	template <class T>

	static void Cleanup(T* aHandle)

		{

		// The general template/class scaffolding remains the same

		// for all custom cleanups, just this cleanup body varies

		aHandle->Cancel();

		aHandle->Close();

		test.Printf(_L("Cancel Closed RTimer\n"));

		}

	};

void BespokeCleanupFunction(TAny* aData)

	{

	(void)aData;

	test.Printf(_L("BespokeCleanupFunction\n"));

	}

// The walkthroughs themselves

// This class demonstrates the use of an embedded LString in the

// conventional Symbian two-phase construction pattern. We've chosen

// to implement the temporary leave protection in NewL in terms of

// LCleanedupPtr instead of the the CleanupStack API in this example.

class CStringUserTwoPhase : public CBase

	{

public:

	static CStringUserTwoPhase* NewL(const TDesC& aName)

		{

		// We can use the resource management utility classes in

		// two-phase if we want to

		LCleanedupPtr<CStringUserTwoPhase> self(new(ELeave) CStringUserTwoPhase);

		self->ConstructL(aName);

		// Calling Unmanage() disables cleanup and yields the

		// previously managed pointer so that it can be safely

		// returned

		return self.Unmanage(); 

		}

	virtual void ConstructL(const TDesC& aName)

		{

		// This assignment may leave if LString fails to allocate a

		// heap buffer large enough to hold the data in aName

		iName = aName; 

		}

	~CStringUserTwoPhase()

		{

		// The iName LString cleans up after itself automatically 

		}

	const TDesC& Name() 

		{

		// We can just return an LString directly as a const TDesC

		return iName; 

		}

protected:

	CStringUserTwoPhase()

		{

		// Everything interesting happens in ConstructL in this

		// version. 

		// Default initialization of the iName LString does not

		// allocate a heap buffer, and so cannot leave. As long as

		// initialization is deferred to ConstructL, LStrings can be

		// used safely with two-phase construction.

		}

protected:

	LString iName;

	};

// This class demonstrates the use of an embedded LString in the

// single-phase construction pattern, where a leave-safe constructor

// fully initializes the object. 

//

// Note that where a class's constructor forms part of its exported

// public or protected contract, switching from a non-leaving to a

// potentially leaving constructor would be a BC break. On the other

// hand, if instantiation is entirely encapsulated within factory

// functions like NewL, there is no such BC restriction.

class CStringUserSinglePhase : public CBase

	{

public:

	// This macro is necessary to ensure cleanup is correctly handled

	// in the event that a constructor may leave beneath a call to

	// new(ELeave)

	CONSTRUCTORS_MAY_LEAVE

	static CStringUserSinglePhase* NewL(const TDesC& aName)

		{

		return new(ELeave) CStringUserSinglePhase(aName);

		}

	~CStringUserSinglePhase()

		{

		// The iName LString cleans up after itself automatically

		}

	const TDesC& Name() 

		{

		// We can just return an LString directly as a const TDesC

		return iName;

		}

protected:

	CStringUserSinglePhase(const TDesC& aName)

		// This initialization of iName may leave because LString

		// needs to allocate a heap buffer to copy the aName string

		// data into

		: iName(aName) 

		{

		// If iName initialization is successful but the constructor

		// then goes on to leave later, iName (like all fields fully

		// constructed at the point of a leave in a constructor) will

		// be destructed, and so clean up after itself

		MaybeLeaveL();

		}

protected:

	LString iName;

	};

void WalkthroughStringsL()

	{

		{

		// Trivially exercise the LString using classes defined above

		LCleanedupPtr<CStringUserTwoPhase> one(CStringUserTwoPhase::NewL(KOne));

		test.Printf(_L("Single phase name: %S\n"), &one->Name());

		LCleanedupPtr<CStringUserSinglePhase> two(CStringUserSinglePhase::NewL(KTwo));

		test.Printf(_L("Two phase name: %S\n"), &two->Name());

		// Both instances are automatically deleted as we go out of scope

		}

		{

		// A default constructed LString starts empty, doesn't

		// allocate any memory on the heap, and therefore the

		// following cannot leave

		LString s;

		// But it will grow on demand if you assign to it, so it has

		// enough space to hold the copied string data, and so

		// assignment may leave

		s = L"One ";

		// Similarly if you append to it with the leaving variant of

		// Append, AppendL, if may grow on demand

		s.AppendL(L"Two ");

		// The += operator for LString also maps to AppendL

		s += L"Three ";

		// You can also use new leaving format methods that also grow

		// on demand

		s.AppendFormatL(KTesting);

		// This general style of use of LString may be preferable to

		// typical descriptor use for a number of reasons e.g. it

		// avoids the common temptation to set an artificial maximum

		// buffer size; it avoids massive conservative over-allocation

		// when the average case length of a string is far less than

		// the worst-case maximum; it will not surprise you (compared

		// to the alternative of a large stack-allocated TBuf) by

		// triggering stack overflow.

		// An LString can be printed the same way as any descriptor

		test.Printf(_L("Value: %S\n"), &s);

		// An LString supports all TDesC and TDes methods

		// LString findToken(L"Two ");

		test(s.Find(L"Two ") == 4);

		// LString matchPattern(L"*Two* ");

		test(s.Match(L"*Two*") == 4);

		test(s.Match(L"*T?o*") == 4);

		// LString compare(L"some string");

		test(s.Compare(L"One Two Three Testing ") == 0);

		test(s.Compare(L"One Two Three Testing! ") < 0);

		test(s.Compare(L"One Two Testing ") > 0);

		// also LString ==,!=,>,<,<=,>=(L"some string");

		test(s == L"One Two Three Testing ");

		test(s < L"One Two Three Testing! ");

		test(s > L"One Two Testing ");

		test(s != L"not equal");

		// An LString supports all TDesC and TDes operators

		test(s[4] == TChar('T'));

		TInt untrimmed = s.Length();

		s.Trim();

		test(s.Length() == untrimmed - 1);

		s.UpperCase();

		test.Printf(_L("UpperCase: %S\n"), &s);

		s.LowerCase();

		test.Printf(_L("LowerCase: %S\n"), &s);

		// The underlying heap allocated buffer is released

		// automatically when the LString goes out of scope, either

		// normally or through a leave

		}

		{

		// Copy, Append,Insert,Replace,Justify the same way as TDesC and TDes

		LString s;

		// Copies data into this 8-bit string descriptor, replacing any existing

		// data, and expanding its heap buffer to accommodate if necessary.

		// leaves on not being able to accomodate the new content

		// both AssignL and += use CopyL internally

		s.CopyL(L"new way of dealing with strings");

		s.CopyUCL(L"new way of dealing with strings");

		test(s == L"NEW WAY OF DEALING WITH STRINGS");

		// Insert data into this descriptor.

		// The length of this descriptor is changed to reflect the extra data.

		// This leaving variant of the standard, non-leaving descriptor method

		// differs in that this operation may cause the string descriptor's heap

		// buffer to be reallocated in order to accommodate the new data. As a

		// result, MaxLength() and Ptr() may return different values afterwards,

		// and any existing raw pointers to into the descriptor data may be

		// invalidated.

		s.CopyL(L"Some Content Can Be Into This String");

		s.InsertL(20,L"Inserted ");

		test(s == L"Some Content Can Be Inserted Into This String");

		// Replace data in this descriptor.

		// The specified length can be different to the length of the replacement data.

		// The length of this descriptor changes to reflect the change of data.

		// This leaving variant of the standard, non-leaving descriptor method

		// differs in that this operation may cause the string descriptor's heap

		// buffer to be reallocated in order to accommodate the new data. As a

		// result, MaxLength() and Ptr() may return different values afterwards,

		// and any existing raw pointers to into the descriptor data may be

		// invalidated.

		s.CopyL(L"Some Content Can Be Decalper");

		s.ReplaceL(20,8,L"Replaced");

		test(s == L"Some Content Can Be Replaced");

		// Append data onto the end of this descriptor's data.

		// The length of this descriptor is incremented to reflect the new content.

		// This leaving variant of the standard, non-leaving descriptor method

		// differs in that this operation may cause the string descriptor's heap

		// buffer to be reallocated in order to accommodate the new data. As a

		// result, MaxLength() and Ptr() may return different values afterwards,

		// and any existing raw pointers to into the descriptor data may be

		// invalidated.

		s.CopyL(L"Try appending ");

		s.AppendL(L"Try appending some more",3);

		test(s == L"Try appending Try");

		// Copy data into this descriptor and justifies it, replacing any existing data.

		// The length of this descriptor is set to reflect the new data.

		// The target area is considered to be an area of specified width positioned at

		// the beginning of this descriptor's data area. Source data is copied into, and

		// aligned within this target area according to the specified alignment

		// instruction.

		// If the length of the target area is larger than the length of the source, then

		// spare space within the target area is padded with the fill character.

		// This leaving variant of the standard, non-leaving descriptor method

		// differs in that this operation may cause the string descriptor's heap

		// buffer to be reallocated in order to accommodate the new data. As a

		// result, MaxLength() and Ptr() may return different values afterwards,

		// and any existing raw pointers to into the descriptor data may be

		// invalidated.

		s.CopyL(L"Justified");

		s.JustifyL(L"Just",9,ERight,'x');

		test(s == L"xxxxxJust");

		// Append data onto the end of this descriptor's data and justifies it.

		// The source of the appended data is a memory location.

		// The target area is considered to be an area of specified width, immediately 

		// following this descriptor's existing data. Source data is copied into, and 

		// aligned within, this target area according to the specified alignment instruction.

		// If the length of the target area is larger than the length of the source, 

		// then spare space within the target area is padded with the fill character.

		// This leaving variant of the standard, non-leaving descriptor method

		// differs in that this operation may cause the string descriptor's heap

		// buffer to be reallocated in order to accommodate the new data. As a

		// result, MaxLength() and Ptr() may return different values afterwards,

		// and any existing raw pointers to into the descriptor data may be

		// invalidated.

		s.CopyL(L"One ");

		s.AppendJustifyL(L"Two Three",3,7,ERight,'x');

		test(s == L"One xxxxTwo" );

		}

		{

		// You can initialize with a MaxLength value

		LString s(KMaxFileName); // This operation may leave

		test(s.MaxLength() == KMaxFileName);

		// And you can dynamically adjust MaxLength later using 

		// SetMaxLengthL if you want an exact allocated size

		// Setting MaxLength on construction or via SetMaxLengthL is

		// exact; calling MaxLength() immediately afterwards is

		// guaranteed to return exactly the value you specified

		s.SetMaxLengthL(2 * KMaxFileName);

		test(s.MaxLength() == 2 * KMaxFileName);

		// Pre-setting MaxLength is important when passing an LString

		// as a TDes to a library function, because the LString can't

		// be auto-grown via the TDes API

		}

		{

		// You can initialize from any descriptor/literal/[wide]character string and the

		// string data is copied into the LString

		LString s(L"One "); // From a character string

		s += L"Two ";

		LString half(s.Left(s.Length() / 2)); // Left returns a TPtrC

		test.Printf(_L("All: %S, Half: %S\n"), &s, &half);

		// On the other hand, you can initialize from a returned

		// HBufC* and the LString automatically takes ownership

		LString own(AllocateNameL(KTesting));

		test.Printf(_L("What I own: %S\n"), &own);

		// Following that you can re-assign an HBufC to an existing

		// string using the assignment operator 

		// taking ownership of the new content. 

		own = AllocateNameL(KTesting);

		// Following that you can re-assign an HBufC to an existing

		// string. The string destroys its original content before

		// taking ownership of the new content. 

		own.Assign(AllocateNameL(KTesting));

		// The content of one string can similarly be assigned

		// to another to avoid copying. In this example, the content 

		// is detached from 's' and transfered to 'own'.  

		own.Assign(s);

		// The same content transfer can be achieved from an RBuf to a

		// string. You may need to do this if a legacy method returns

		// you an RBuf. The RBuf is emptied of its content.

		RBuf16 buf;

		buf.CreateL(KOne);

		own.Assign(buf);

		// You can also assign a simple text array to a string as its

		// new buffer. This method initialises the length to zero.   

		own.Assign((TText*)User::Alloc(24*(TInt)sizeof(TText)), 24);

		// If the buffer has already been filled with some characters

		// then you supply the length in this alternative Assign method.   

		own.Assign((TText*)User::Alloc(24*(TInt)sizeof(TText)), 12,24);

		// Each Assign destroys the old content before assuming ownership

		// of the new.

		// As usual the last content of the string is destroyed when the 

		// LString goes out of scope

		}

		{

		// You can reserve extra free space in preparation for an 

		// operation that adds characters to the string. You may

		// need to do this when you cannot use any of the auto-buffer

		// extending LString methods to achieve your objective.

		LString s(L"One ");

		s.ReserveFreeCapacityL(4);

		test(s.Length() == 4);

		test(s.MaxLength() >= 8);

		// Almost all the methods that may extended the string buffer,

		// including the explicit ReserveFreeCapacityL, but excluding

		// SetMaxLengthL, attempt to grow the size exponentially. 

		// The Exponential growth pattern is expected to give better 

		// performance at an amortised complexity of O(n) when adding n characters.

		// If the exponential growth is less than the supplied extra size

		// then the supplied size is used instead to save time.

		// The exponential growth is used in anticipation of further additions

		// to a string. This trades-off speed efficiency for space efficiency.

		// If required you may be able to swap the oversized buffer for 

		// a more compact one using:

		s.Compress();

		test(s.MaxLength() >= 4);	//note indefinite test

		// Resize attempts to re-allocate a smaller buffer to copy

		// the content into. If the new memory cannot be allocated then the

		// original string is left unaffected. 

		// When you have finished using the content of a string you can

		// get its buffer released without destroying the string itself. 

		// You may want to do this when using member declared strings.

		// Automatic strings are destroyed when they go out of scope.

		s.Reset();

		test(s.Length() == 0);

		test(s.MaxLength() == 0);

		}

		{

		// An LString can be passed directly to any function requiring

		// a const TDesC&

		TInt year = 2009;

		LString s;

		s.FormatL(_L("Happy New Year %d"), year);

		// InfoPrint takes a const TDesC&

		User::InfoPrint(s);

		LString pattern;

		pattern.FormatL(_L("*Year %d"), year);

		// Match takes a const TDesC& as a pattern

		TInt loc = s.Match(pattern);

		test(loc == 10);

		}

		{

		// An LString can be passed directly to any function requiring

		// a TDes& but care must always be taken to pre-set MaxLength

		// since LStrings can't be automatically grown via the TDes

		// interface

		LString s;

		// Calling GetCurrentPath(s) now would panic because LStrings

		// are initialized by default to MaxLength 0.  Although s is

		// an LString GetCurrentPath takes a TDes& and so inside the function

		// s behaves as a TDes and would panic with USER 11 if the resulting 

		// new length of s is greater than its maximum length.

		test(s.MaxLength() == 0);

		// Calling SetMaxLengthL will automatically realloc the

		// underlying buffer if required, and is guaranteed to leave

		// MaxLength() equal to the specified value

		s.SetMaxLengthL(KMaxFileName);

		GetCurrentPath(s);

		//LString pathString(L"c:\\a\\b\\c");

		test.Printf(_L("Path: %S\n"), &s);

		test(s == L"c:\\a\\b\\c");

		// If SetMaxLengthL adjusts MaxLength lower than the current

		// Length, the data is truncated to the new MaxLength and

		// Length set to the new MaxLength

		s.SetMaxLengthL(s.Length() / 2);

		test.Printf(_L("Truncated path: %S\n"), &s);

		test(s.Length() == s.MaxLength());

		// An initial MaxLength can be specified when constructing an

		// LString. Note that unlike the default constructor, this

		// variant allocates and may leave.

		LString s2(KMaxFileName);

		GetCurrentPath(s2);

		test.Printf(_L("Path: %S\n"), &s2);

		test(s2 == L"c:\\a\\b\\c");

		// Your code and APIs can benefit from LString's auto-growth

		// behaviour by accepting an LString to fill in as an output

		// parameter. Using LString rather than TDes parameters means 

		// that the function is able to safely increase the size of the 

		// string as the LString will re-allocate as necessary

		LString s3;

		// GetCurrentPathStringL takes an LString&

		GetCurrentPathStringL(s3);

		test.Printf(_L("Path: %S\n"), &s3);

		test(s3 == L"c:\\a\\b\\c");

		// As a well-defined value class, if you want to, LStrings can

		// be passed and returned by value. This is relatively

		// inefficient however due to the amount of copying and heap

		// reallocation involved. 

		LString s4(AppendCurrentPathStringL(s3));

		test.Printf(_L("Appended path: %S\n"), &s4);

		test(s4.Length() == s3.Length() * 2);

		}

		{

		// LStrings can be allocated on the heap if necessary. 

		// Then it can managed as part of an array of string pointers

		TInt n = 5;

		LCleanedupHandle<RPointerArray<LString>, TResetAndDestroy> sarray;

		for (TInt i = 0; i < n; ++i) 

			{

			LString* s = new(ELeave) LString;

			s->FormatL(_L("String %d"), i);

			sarray->Append(s);

			}

		for (TInt i = 0, n = sarray->Count(); i < n; ++i) 

			{

			LString tmp;

			tmp.FormatL(_L("String %d"), i);

			test(tmp == *(*sarray)[i]);

			test.Printf(_L("String %d = %S\n"), i, (*sarray)[i]);

			}

		}

		{

		// Any allocation failure in new(ELeave)LString throws

		// KErrNoMemory and cleans up after itself fully

		__UHEAP_MARK;

		//coverity[resource_leak]

		//As mentioned in the comment above any allocation failure is taken care of

		TRAPD(status, new(ELeave) LString(100 * 1024 * 1024));

		test(status == KErrNoMemory);

		__UHEAP_MARKEND;

		}

		{

		// Native C arrays (both heap and stack allocated) of LStrings

		// also work, although their use is not recommended

		TInt n = 5;

		LCleanedupArray<LString> sarray(new(ELeave) LString[n]);

		for (TInt i = 0; i < n; ++i) 

			{

			sarray[i].FormatL(_L("String %d"), i);

			}

		for (TInt i = 0; i < n; ++i) 

			{

			LString tmp;

			tmp.FormatL(_L("String %d"), i);

			test(tmp == sarray[i]);

			test.Printf(_L("String %d = %S\n"), i, &sarray[i]);

			}

		}

		{

		// 8-bit wide null terminated character string support

		// A default constructed LString8 starts empty, doesn't

		// allocate any memory on the heap, and therefore the

		// following cannot leave

		LString8 s;

		// But it will grow on demand if you assign to it, so it has

		// enough space to hold the copied string data, and so

		// assignment may leave

		s ="One ";

		// Similarly if you append to it with the leaving variant of

		// Append, AppendL, if may grow on demand

		s.AppendL("Two ");

		// The += operator for LString8 also maps to AppendL

		s +="Three ";

		s +="Testing ";

		// An LString8 can be printed the same way as any descriptor

		test.Printf(_L("Value: %S \n"), &s);

		// An LString8 can be compared the same way as any descriptor

		test(s == "One Two Three Testing ");

		// An LString8 supports all TDesC and TDes methods

		// LString findToken("Two ");

		test(s.Find("Two ") == 4);

		// LString8 matchPattern("*Two* ");

		test(s.Match("*Two*") == 4);

		test(s.Match("*T?o*") == 4);

		// LString8 compare("some string");

		test(s.Compare("One Two Three Testing ") == 0);

		test(s.Compare("One Two Three Testing! ") < 0);

		test(s.Compare("One Two Testing ") > 0);

		// also LString8 ==,!=,>,<,<=,>=(L"some string");

		test(s == "One Two Three Testing ");

		test(s < "One Two Three Testing! ");

		test(s > "One Two Testing ");

		test(s != "not equal");

		// Copies data into this 8-bit string descriptor, replacing any existing

		// data, and expanding its heap buffer to accommodate if necessary.

		// leaves on not being able to accomodate the new content

		// both AssignL and += use CopyL internally

		s.CopyL("new way of dealing with strings");

		// Copy, Append,Insert,Replace,Justify the same way as TDesC8 and TDes8

		// Copies data into this 8-bit string descriptor, replacing any existing

		// data, and expanding its heap buffer to accommodate if necessary.

		// leaves on not being able to accomodate the new content

		// both AssignL and += use CopyL internally

		s.CopyL("new way of dealing with strings");

		s.CopyUCL("new way of dealing with strings");

		test(s == "NEW WAY OF DEALING WITH STRINGS");

		// Insert data into this descriptor.

		// The length of this descriptor is changed to reflect the extra data.

		// This leaving variant of the standard, non-leaving descriptor method

		// differs in that this operation may cause the string descriptor's heap

		// buffer to be reallocated in order to accommodate the new data. As a

		// result, MaxLength() and Ptr() may return different values afterwards,

		// and any existing raw pointers to into the descriptor data may be

		// invalidated.

		s.CopyL("Some Content Can Be Into This String");

		s.InsertL(20,"Inserted ");

		test(s == "Some Content Can Be Inserted Into This String");

		// Replace data in this descriptor.

		// The specified length can be different to the length of the replacement data.

		// The length of this descriptor changes to reflect the change of data.

		// This leaving variant of the standard, non-leaving descriptor method

		// differs in that this operation may cause the string descriptor's heap

		// buffer to be reallocated in order to accommodate the new data. As a

		// result, MaxLength() and Ptr() may return different values afterwards,

		// and any existing raw pointers to into the descriptor data may be

		// invalidated.

		s.CopyL("Some Content Can Be Decalper");

		s.ReplaceL(20,8,"Replaced");

		test(s == "Some Content Can Be Replaced");

		// Append data onto the end of this descriptor's data.

		// The length of this descriptor is incremented to reflect the new content.

		// This leaving variant of the standard, non-leaving descriptor method

		// differs in that this operation may cause the string descriptor's heap

		// buffer to be reallocated in order to accommodate the new data. As a

		// result, MaxLength() and Ptr() may return different values afterwards,

		// and any existing raw pointers to into the descriptor data may be

		// invalidated.

		s.CopyL("Try appending ");

		s.AppendL("Try appending some more",3);

		test(s == "Try appending Try");

		// Copy data into this descriptor and justifies it, replacing any existing data.

		// The length of this descriptor is set to reflect the new data.

		// The target area is considered to be an area of specified width positioned at

		// the beginning of this descriptor's data area. Source data is copied into, and

		// aligned within this target area according to the specified alignment

		// instruction.

		// If the length of the target area is larger than the length of the source, then

		// spare space within the target area is padded with the fill character.

		// This leaving variant of the standard, non-leaving descriptor method

		// differs in that this operation may cause the string descriptor's heap

		// buffer to be reallocated in order to accommodate the new data. As a

		// result, MaxLength() and Ptr() may return different values afterwards,

		// and any existing raw pointers to into the descriptor data may be

		// invalidated.

		s.CopyL("Justified");

		s.JustifyL("Just",9,ERight,'x');

		test(s == "xxxxxJust");

		// Append data onto the end of this descriptor's data and justifies it.

		// The source of the appended data is a memory location.

		// The target area is considered to be an area of specified width, immediately 

		// following this descriptor's existing data. Source data is copied into, and 

		// aligned within, this target area according to the specified alignment instruction.

		// If the length of the target area is larger than the length of the source, 

		// then spare space within the target area is padded with the fill character.

		// This leaving variant of the standard, non-leaving descriptor method

		// differs in that this operation may cause the string descriptor's heap

		// buffer to be reallocated in order to accommodate the new data. As a

		// result, MaxLength() and Ptr() may return different values afterwards,

		// and any existing raw pointers to into the descriptor data may be

		// invalidated.

		s.CopyL("One ");

		s.AppendJustifyL("Two Three",3,7,ERight,'x');

		test(s == "One xxxxTwo" );

		}

	}

// This class demonstrates the use of the embeddable management

// classes in a conventional Symbian two-phase construction

// pattern. 

class CManagedUserTwoPhase : public CBase

	{

public:

	static CManagedUserTwoPhase* NewL(CTicker* aTicker)

		{

		// We can use the resource management utility classes in

		// two-phase if we want to

		LCleanedupPtr<CManagedUserTwoPhase> self(new(ELeave) CManagedUserTwoPhase);

		self->ConstructL(aTicker);

		// Calling Unmanage() disables cleanup and yields the

		// previously managed pointer so that it can be safely

		// returned

		return self.Unmanage(); 

		}

	~CManagedUserTwoPhase()

		{

		// The iTicker manager will automatically delete the CTicker

		// The iTimer manager will automatically Close() the RTimer

		}

	CTicker& Ticker()

		{

		// If we dereference the management object we get a CTicker&

		return *iTicker;

		}

	RTimer& Timer()

		{

		// If we dereference the management object we get an RTimer&

		return *iTimer;

		}

private:

	virtual void ConstructL(CTicker* aTicker)

		{

		// Take ownership and manage aTicker 

		iTicker = aTicker; 

		// Note use of -> to indirect through the management wrapper

		iTimer->CreateLocal() OR_LEAVE; 

		}

	CManagedUserTwoPhase()

		{

		// Everything interesting happens in ConstructL in this

		// version. 

		// Default initialization of the iName LString does not

		// allocate a heap buffer, and so cannot leave. As long as

		// initialization is deferred to ConstructL, LStrings can be

		// used safely with two-phase construction.

		}

private:

	// We have to use LManagedXxx for fields, not LCleanedupXxx

	LManagedPtr<CTicker> iTicker;

	LManagedHandle<RTimer> iTimer;

	};

// This class demonstrates the use of embedded management classes in

// the single-phase construction pattern, where a leave-safe

// constructor fully initializes the object.

//

// Note that where a class's constructor forms part of its exported

// public or protected contract, switching from a non-leaving to a

// potentially leaving constructor would be a BC break. On the other

// hand, if instantiation is entirely encapsulated within factory

// functions like NewL, there is no such BC restriction.

class CManagedUserSinglePhase : public CBase

	{

public:

	// This macro is necessary to ensure cleanup is correctly handled

	// in the event that a constructor may leave beneath a call to

	// new(ELeave)

	CONSTRUCTORS_MAY_LEAVE

	static CManagedUserSinglePhase* NewL(CTicker* aTicker)

		{

		return new(ELeave) CManagedUserSinglePhase(aTicker);

		}

	~CManagedUserSinglePhase()

		{

		// The iTicker manager destructor will automatically Zap() the CTicker

		// The iTimer manager destructor will automatically Close() the RTimer

		}

	CTicker& Ticker()

		{

		// If we dereference the management object we get a CTicker&

		return *iTicker;

		}

	RTimer& Timer()

		{

		// If we dereference the management object we get an RTimer&

		return *iTimer;

		}

private:

	CManagedUserSinglePhase(CTicker* aTicker)

		// Take ownership and manage aTicker. Note that initialization

		// of the LManagedXxx classes does not actually leave, but

		// initialization of the LCleanedupXxx classes can.

		: iTicker(aTicker)

		{

		// If iTicker initialization is successful but the constructor

		// then goes on to leave later, iTicker (like all fields fully

		// constructed at the point of a leave in a constructor) will

		// be destructed, and the manager will cleanup the CTicker

		// Note use of -> to indirect through the management wrapper

		iTimer->CreateLocal() OR_LEAVE; 

		// Likewise if we leave here, both iTicker and iTimer will

		// undergo managed cleanup

		MaybeLeaveL();

		}

private:

	// We have to use LManagedXxx for fields, not LCleanedupXxx

	LManagedPtr<CTicker, TTickerZapStrategy> iTicker;

	LManagedHandle<RTimer> iTimer;

	};

//Class definition of trivial R-Class

class RSimple

	{

public:

	RSimple(){iData = NULL;}

	//Open function sets value

	void OpenL(TInt aValue)

		{

		iData = new(ELeave) TInt(aValue);

		}

	//Cleanup function – frees resource

	void Close()

		{

		delete iData;

		iData = NULL;

		}

	//Cleanup function – frees resource

	void Free()

		{

		delete iData;

		iData = NULL;

		}

	//Cleanup function – frees resource

	void ReleaseData()

		{

		delete iData;

		iData = NULL;

		}

	//static cleanup function – frees aRSimple resources

	static void Cleanup(TAny* aRSimple)

		{

		static_cast<RSimple*>(aRSimple)->Close();

		}

private:

	TInt* iData;

	};

//This sets the default cleanup behaviour for the RSimple class to 

//be RSimple::ReleaseData.

//If this Macro is not used then the default cleanup behaviour

//would be to call RSimple::Close().

DEFINE_CLEANUP_FUNCTION(RSimple, ReleaseData);

void WalkthroughManagedL()

	{

		{

		// Trivially exercise the manager-using classes defined above

		CTicker* ticker1 = new(ELeave) CTicker;

		LCleanedupPtr<CManagedUserTwoPhase> one(CManagedUserTwoPhase::NewL(ticker1));

		test(&one->Ticker() == ticker1);

		one->Timer().Cancel(); // Just to check we can get at it

		CTicker* ticker2 = new(ELeave) CTicker;

		LCleanedupPtr<CManagedUserSinglePhase> two(CManagedUserSinglePhase::NewL(ticker2));

		test(&two->Ticker() == ticker2);

		two->Timer().Cancel(); // Just to check we can get at it

		// Both instances are automatically deleted as we go out of scope

		}

		// Always use LCleanedupXxx for locals, not LManagedXxx

		{

		// Begin the scenes the LCleanedupXxx constructors push a

		// cleanup item onto the cleanup stack and so may leave. If

		// there is a leave during construction, the supplied pointer

		// will still get cleaned up.