// 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