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

//

#ifndef ESTRING_H

#define ESTRING_H

#include <e32std.h>

// this macro is defined only if the target is WINSCW and wchar_t is ON

// (i.e OPTION CW -wchar_t on)

// and  if the target is any thing other than WINSCW 

// it is being assumed that wchar_t is ON(OPTION CW -wchar_t on by 

// default or other wise)

#define NATIVE_WCHAR // most platforms do wchar_t properly

#if defined __cplusplus && defined __WINSCW__

#if !__option(wchar_type) // without the wchar_type option

typedef unsigned short wchar_t; // needs a typedef

#undef NATIVE_WCHAR // which is not native

#endif

#endif

// Since the LStrings can leave in their constructors, we have to make

// sure to avoid the operator new/delete ELeave mismatch problem that

// can result in the top level LString object heap being

// leaked. These operator delete overloads match the global operator

// new overloads applicable to the LString classes (which are

// non-CBase derived).

//

// Note that when allocating a native C++ array of LStrings, only the

// default constructor is invoked which cannot leave. So there are no

// issues related to the array case.

#define LSTRING_CONSTRUCTORS_MAY_LEAVE \

	static void operator delete(TAny* aPtr) __NO_THROW \

		{ \

		return ::operator delete(aPtr); \

		} \

	\

	static void operator delete(TAny* aPtr, TLeave) __NO_THROW \

		{ \

		return ::operator delete(aPtr); \

		} \

	\

	static void operator delete(TAny*, TAny*) __NO_THROW \

		{ \

		} 

/**

	@file

	A self-managing descriptor class

   	@publishedAll

   	@released

*/

/**

@class LString8

LString8 is a convenient, general-purpose 8 bit string class derived

from RBuf8. LString8 adds automatic cleanup and on-demand buffer

resize facilities.

@par L-Classes

Note: The L prefix denotes that construction, copying, passing and

returning by value, assignment, and manipulation via operators should

all be considered potentially leaving operations unless otherwise

explicitly documented. Code that uses LString8 should be written

accordingly, in leave-safe style.

@par Descriptor Relationships

Like an RBuf8, an LString8 can be passed to any function that is

prototyped to take a TDes8 or a TDesC8 reference. Again like an

RBuf8, an LString8 maintains its string data in a heap buffer.

@par Value-Type Behaviour

Unlike RBuf8, an LString8 may be used much like a simple T class;

LString8 typed variables will automatically clean up after themselves

when they go out of scope, and LString8 typed fields will similarly

automatically release all owned resources when their containing object

is destroyed.

For example, where:

@code

RBuf8 buf;

buf.CleanupClosePushL();

...

CleanupStack::PopAndDestroy();

@endcode

would be required, with LString8:

@code

LString8 buf;

...

@endcode

will suffice. Pushing an LString8 onto the cleanup stack is not

necessary or recommended, but the effects of doing so are

benign. LString8 instances can also be passed and returned by value,

but note that doing so may trigger implicit heap allocation and cause

a leave with KErrNoMemory.

@code

void TakeString(LString8 aString)

	{

	// ...

	}

LString8 ReturnString(LString8 aString)

	{

	TakeString(aString); // Statement may leave with KErrNoMemory

	return aString; // Statement may leave with KErrNoMemory

	}

@endcode

As with other descriptors, passing by reference when possible is more

efficient.

@par On-Demand Growth

In addition to the value-type semantics described above, LString8

also supports automatic in-place resizing. All standard descriptor

methods are available, but for any non-leaving descriptor method that

may panic due to buffer overflow, LString8 adds a corresponding

leaving method that automatically expands the underlying buffer

on-demand. For example, Append() will panic if the new data overflows

available buffer space, while AppendL() will attempt to realloc the

buffer as necessary. The new leaving variants may therefore leave with

KErrNoMemory, may invalidate any existing raw pointers into the data

buffer (e.g. those previously returned by Ptr()), and may change the

value returned by MaxLength().

@code

LString8 message; // Zero length

message.FormatL(_L("This is message %n from %S"), n, &s); // FormatL automatically grows the buffer

User::InfoPrint(message);

@endcode

It is important to note that LString8 only supports automatic growth

when being manipulated directly as an LString8. When an LString8 is

passed to a function accepting a TDes8, that function will operate on

it as if it is a fixed-max-length descriptor. In that case, adequate

capacity must be reserved within the LString8 prior to calling the

function. This can either be achieved using the appropriate constructor or ReserveFreeCapacityL().

@code

extern void GetLastQuery(TDes8& aQuery);

extern void GetLastAuxQuery(TDes8& aQuery);

LString8 query(KMaxQuerySize); // Guarantees query.MaxLength() >= KMaxQuerySize

GetLastQuery(query);

// ...

previousQueryMaxLength = query.MaxLength(); 

query.ReserveFreeCapacityL(KExtraRequiredSize); // Guarantees query.MaxLength() >= KExtraRequiredSize + previousQueryMaxLength;

GetLastAuxQuery(query);

@endcode

@par Relationship with TDes and RBuf

LString8 derives from RBuf8 in order to achieve maximum

interoperability with existing descriptor-accepting APIs. This

derivation forces some unusual API compromises, however, due to the

unique characteristics of LString8 compared to other descriptors.

Some of the mutating methods on the base classes, TDes8 and RBuf8,

panic when called with insufficient buffer space.  Sufficient space is

a precondition of these base classes which LString8 relaxes with

its capability to start with zero length.  LString8 defines new

leaving variants of these methods with auto-growth behaviour

(e.g. AppendL), but at the same time inherits the original methods

(e.g. Append).  This makes it too easy for developers to call the

wrong method inadvertently. In order to address this, the original 

non-leaving methods have been made private in LString8. Developers 

should use the leaving LString8 versions.

Note that, if required for any reason, the non-leaving method variants 

may be accessed by explicitly qualifying the method name to the 

appropriate parent type. For example: aString.TDes::Append(...). When 

working with an LString8 but doing so via a TDes& typed variable, all 

TDes8 APIs are directly available.

Hiding these methods does not remove the problem entirely.  The same

problem can happen if an LString object of insufficient size in passed

into a any API accepting a TDes. The advice is that developers always

ensure there is sufficient space before passing LString as a TDes.

@par Performance Concerns

While being simpler to use than existing descriptors in many cases,

LString8's use of heap allocation and its resizing variant methods

clearly come with associated costs. Their use in performance-critical

code should be carefully considered. On the other hand, LString8's

small stack footprint and ability to better-handle inputs of

unpredictable size may make them a better choice when the alternative

is a large, fixed-max-size TBuf or HBufC.

@par Buffer Ownership

Typically an LString8 will automatically allocate its own buffer, but

like RBuf8 it can also take ownership of a pre-existing raw memory

buffer or heap descriptor.

The class is intended for instantiation.

@see RBuf8

@see TBuf8

@see TPtr8

@see HBufC8

@see TDesC8

@see TDes8

@see LString

*/

class LString8 : public RBuf8

	{

public:

	/*

	 * We add leaving (auto-resizing) variants of the standard TDes

	 * methods where appropriate, and enhance the behaviour of the

	 * corresponding operators to match

	 */

	LSTRING_CONSTRUCTORS_MAY_LEAVE

	IMPORT_C LString8();

	IMPORT_C ~LString8();

	// Construct with initial capacity

	IMPORT_C explicit LString8(TInt aInitialCapacity);

	// Construct by data copying

	IMPORT_C LString8(const TDesC8& aDes);

	IMPORT_C LString8(const TUint8* aZeroTerminatedString);

	IMPORT_C LString8(const LString8& aDes);

	// Construction thru transfer of ownership

	IMPORT_C explicit LString8(HBufC8* aHBuf);

	IMPORT_C explicit LString8(TUint8 *aHeapCell,TInt aMaxLength);

	IMPORT_C explicit LString8(TUint8 *aHeapCell,TInt aLength,TInt aMaxLength);

	// Assignment thru payload copying

	IMPORT_C LString8& operator=(const TDesC8& aDes);

	IMPORT_C LString8& operator=(const LString8& aDes);

	IMPORT_C LString8& operator=(const TUint8* aZeroTerminatedString);

	// Assignment by transfer of payload to this object;

	// supplied object is destroyed or zeroed.

	IMPORT_C LString8& operator=(HBufC8* aHBuf);

	// Assign by transfer of payload ownership to this object;

	// supplied object is destroyed or zeroed.

	IMPORT_C void Assign(const LString8& aString);

	IMPORT_C void Assign(const RBuf8& aRBuf);

	IMPORT_C void Assign(HBufC8* aHBuf);

	IMPORT_C void Assign(TUint8 *aHeapCell,TInt aMaxLength);

	IMPORT_C void Assign(TUint8 *aHeapCell,TInt aLength,TInt aMaxLength);

	IMPORT_C void CreateL(RReadStream& aStream,TInt aMaxLength);

	IMPORT_C LString8& operator+=(TChar aChar);

	IMPORT_C LString8& operator+=(const TDesC8 &aDes);

	IMPORT_C void CopyL(const TDesC8 &aDes);

	IMPORT_C void CopyL(const TDesC16 &aDes);

	IMPORT_C void CopyL(const TUint8 *aZeroTerminatedString);

	IMPORT_C void CopyL(const TUint8 *aBuf,TInt aLength);

 	IMPORT_C void SetLengthL(TInt aLength);

 	IMPORT_C void SetMaxLengthL(TInt aMaxLength);

	IMPORT_C void Compress(); // deprecated; to be removed

	IMPORT_C void ReserveFreeCapacityL(TInt aExtraSpaceLength);

	IMPORT_C void Reset();

	IMPORT_C void AppendL(TChar aChar);

	IMPORT_C void AppendL(const TDesC8 &aDes);

	IMPORT_C void AppendL(const TUint8 *aBuf,TInt aLength);

	IMPORT_C void FillL(TChar aChar,TInt aLength);

	IMPORT_C void FillZL(TInt aLength);

	IMPORT_C void NumFixedWidthL(TUint aVal,TRadix aRadix,TInt aWidth);

	IMPORT_C void AppendNumFixedWidthL(TUint aVal,TRadix aRadix,TInt aWidth);

	IMPORT_C const TUint8 *PtrZL();

	IMPORT_C void CopyFL(const TDesC8 &aDes);

	IMPORT_C void CopyCL(const TDesC8 &aDes);

	IMPORT_C void CopyLCL(const TDesC8 &aDes);

	IMPORT_C void CopyUCL(const TDesC8 &aDes);

	IMPORT_C void CopyCPL(const TDesC8 &aDes);

	IMPORT_C void AppendFillL(TChar aChar,TInt aLength);

	IMPORT_C void ZeroTerminateL();

	IMPORT_C void SwapL(TDes8 &aDes);

	IMPORT_C void SwapL(LString8 &aDes); // Added overload

	IMPORT_C void InsertL(TInt aPos,const TDesC8 &aDes);

	IMPORT_C void ReplaceL(TInt aPos,TInt aLength,const TDesC8 &aDes);

	IMPORT_C void JustifyL(const TDesC8 &aDes,TInt aWidth,TAlign anAlignment,TChar aFill);

	IMPORT_C void NumFixedWidthUCL(TUint aVal,TRadix aRadix,TInt aWidth);

	IMPORT_C void NumUCL(TUint64 aVal, TRadix aRadix=EDecimal);

	IMPORT_C TInt NumL(TReal aVal,const TRealFormat &aFormat) __SOFTFP;

	IMPORT_C void NumL(TInt64 aVal);

	IMPORT_C void NumL(TUint64 aVal, TRadix aRadix);

	IMPORT_C void FormatL(TRefByValue<const TDesC8> aFmt,...);

	IMPORT_C void FormatListL(const TDesC8 &aFmt,VA_LIST aList);

	IMPORT_C void AppendJustifyL(const TDesC8 &Des,TInt aWidth,TAlign anAlignment,TChar aFill);

	IMPORT_C void AppendJustifyL(const TDesC8 &Des,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill);

	IMPORT_C void AppendJustifyL(const TUint8 *aZeroTerminatedString,TInt aWidth,TAlign anAlignment,TChar aFill);

	IMPORT_C void AppendJustifyL(const TUint8 *aString,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill);

	IMPORT_C void AppendNumFixedWidthUCL(TUint aVal,TRadix aRadix,TInt aWidth);

	IMPORT_C void AppendNumUCL(TUint64 aVal, TRadix aRadix=EDecimal);

	IMPORT_C TInt AppendNumL(TReal aVal,const TRealFormat &aFormat) __SOFTFP;

	IMPORT_C void AppendNumL(TInt64 aVal);

	IMPORT_C void AppendNumL(TUint64 aVal, TRadix aRadix);

	IMPORT_C void AppendFormatL(TRefByValue<const TDesC8> aFmt,...);

	IMPORT_C void AppendFormatListL(const TDesC8 &aFmt,VA_LIST aList);

	using RBuf8::operator==;

	IMPORT_C TBool operator==( const TUint8* aZeroTerminatedString) const;

	using RBuf8::operator<;

	IMPORT_C TBool operator<( const TUint8* aZeroTerminatedString) const;

	using RBuf8::operator<=;

	IMPORT_C TBool operator<=( const TUint8* aZeroTerminatedString) const;

	using RBuf8::operator>;

	IMPORT_C TBool operator>( const TUint8* aZeroTerminatedString) const;

	using RBuf8::operator>=;

	IMPORT_C TBool operator>=( const TUint8* aZeroTerminatedString) const;

	using RBuf8::operator!=;

	IMPORT_C TBool operator!=( const TUint8* aZeroTerminatedString) const;

	using RBuf8::Compare;

	IMPORT_C TInt Compare(const TUint8* aZeroTerminatedString) const;

	using RBuf8::CompareF;

	IMPORT_C TInt CompareF(const TUint8* aZeroTerminatedString) const;

	using RBuf8::Match;

	IMPORT_C TInt Match(const TUint8* aZeroTerminatedString) const;

	using RBuf8::MatchF;

	IMPORT_C TInt MatchF(const TUint8* aZeroTerminatedString) const;

	using RBuf8::Find;

	IMPORT_C TInt Find(const TUint8* aZeroTerminatedString) const;

	using RBuf8::FindF;

	IMPORT_C TInt FindF(const TUint8* aZeroTerminatedString) const;

	IMPORT_C void CopyFL(const TUint8* aZeroTerminatedString);

	IMPORT_C void CopyLCL(const TUint8* aZeroTerminatedString);

	IMPORT_C void CopyUCL(const TUint8* aZeroTerminatedString);

	IMPORT_C void CopyCPL(const TUint8* aZeroTerminatedString);

	IMPORT_C void InsertL(TInt aPos,const TUint8* aZeroTerminatedString);

	IMPORT_C void ReplaceL(TInt aPos,TInt aLength,const TUint8* aZeroTerminatedString);

	IMPORT_C void JustifyL(const TUint8* aZeroTerminatedString,TInt aWidth,TAlign anAlignment,TChar aFill);

	IMPORT_C void AppendL(const TUint8* aZeroTerminatedString);

	IMPORT_C LString8& operator+=(const TUint8* aZeroTerminatedString);

	IMPORT_C LString8(const char* aCharStr);

	IMPORT_C TBool operator==( const char* aCharStr) const;

	IMPORT_C TBool operator<( const char* aCharStr) const;

	IMPORT_C TBool operator<=( const char* aCharStr) const;

	IMPORT_C TBool operator>( const char* aCharStr) const;

	IMPORT_C TBool operator>=( const char* aCharStr) const;

	IMPORT_C TBool operator!=( const char* aCharStr) const;

	IMPORT_C TInt Compare(const char* aCharStr) const;

	IMPORT_C TInt CompareF(const char* aCharStr) const;

	IMPORT_C TInt Match(const char* aCharStr) const;

	IMPORT_C TInt MatchF(const char* aCharStr) const;

	IMPORT_C TInt Find(const char* aCharStr) const;

	IMPORT_C TInt Find(const char* aCharStr,TInt aLenS ) const;

	IMPORT_C TInt FindF(const char* aCharStr) const;

	IMPORT_C TInt FindF(const char* aCharStr,TInt aLenS) const;

	IMPORT_C LString8& operator=(const char* aCharStr);

	IMPORT_C LString8& operator+=(const char* aCharStr);

	IMPORT_C void CopyL(const char* aCharStr);

	IMPORT_C void CopyFL(const char* aCharStr);

	IMPORT_C void CopyLCL(const char* aCharStr);

	IMPORT_C void CopyUCL(const char* aCharStr);

	IMPORT_C void CopyCPL(const char* aCharStr);

	IMPORT_C void InsertL(TInt aPos,const char* aCharStr);

	IMPORT_C void ReplaceL(TInt aPos,TInt aLength,const char* aCharStr);

	IMPORT_C void AppendL(const char* aCharStr, TInt aLength);

	IMPORT_C void AppendL(const char *aCharStr );

	IMPORT_C void JustifyL(const char* aCharStr,TInt aWidth,TAlign anAlignment,TChar aFill);

	IMPORT_C void AppendJustifyL(const char* aCharStr,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill);

	IMPORT_C void AppendJustifyL(const char* aCharStr,TInt aWidth,TAlign anAlignment,TChar aFill);

protected:

private:

	/*

	 * capacity management methods

	 */

	void ReserveL(TInt aMinRequiredCapacity);

	void ReserveCapacityGrowExponentialL(TInt aRequiredCapacity);

	void ReserveCapacityGrowExponentialL();

	void ReserveFreeCapacityGrowExponentialL(TInt aRequiredEmptySpace);

	//----------------------------------------------------------

	// These mutable TDes8 methods panic when called with an insufficient

	// buffer space.

	// A precondition for TDes8 use is that a sufficient

	// sufficient buffer is allocated before making calls that write to the

	// buffer. LString invalidates this precondition.

	// LString inheriting these TDes methods makes it easy

	// for developers to call them inadvertently. They have been made

	// private to ensure the misunderstanding never happens. Developers should

	// use the leaving (L suffixed) LString equivalents.

	void SetLength(TInt aLength);

	void SetMax();

	void Copy(const TDesC8 &aDes);

	void Copy(const TDesC16 &aDes);

	void Copy(const TUint8 *aBuf,TInt aLength);

	void Copy(const TUint8 *aString);

	void Append(TChar aChar);

	void Append(const TDesC8 &aDes);

	void Append(const TUint8 *aBuf,TInt aLength);

	void Fill(TChar aChar,TInt aLength);

	void FillZ(TInt aLength);

	void NumFixedWidth(TUint aVal,TRadix aRadix,TInt aWidth);

	void AppendNumFixedWidth(TUint aVal,TRadix aRadix,TInt aWidth);

	const TUint8 *PtrZ();

	void CopyF(const TDesC8 &aDes);

	void CopyC(const TDesC8 &aDes);

	void CopyLC(const TDesC8 &aDes);

	void CopyUC(const TDesC8 &aDes);

	void CopyCP(const TDesC8 &aDes);

	void AppendFill(TChar aChar,TInt aLength);

	void ZeroTerminate();

	void Swap(TDes8 &aDes);

	void Insert(TInt aPos,const TDesC8 &aDes);

	void Replace(TInt aPos,TInt aLength,const TDesC8 &aDes);

	void Justify(const TDesC8 &aDes,TInt aWidth,TAlign anAlignment,TChar aFill);

	void NumFixedWidthUC(TUint aVal,TRadix aRadix,TInt aWidth);

	void NumUC(TUint64 aVal, TRadix aRadix=EDecimal);

	TInt Num(TReal aVal,const TRealFormat &aFormat) __SOFTFP;

	void Num(TInt64 aVal);

	void Num(TUint64 aVal, TRadix aRadix);

	void Format(TRefByValue<const TDesC8> aFmt,...);

	void FormatList(const TDesC8 &aFmt,VA_LIST aList);

	void AppendJustify(const TDesC8 &Des,TInt aWidth,TAlign anAlignment,TChar aFill);

	void AppendJustify(const TDesC8 &Des,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill);

	void AppendJustify(const TUint8 *aZeroTerminatedString,TInt aWidth,TAlign anAlignment,TChar aFill);

	void AppendJustify(const TUint8 *aZeroTerminatedString,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill);

	void AppendNumFixedWidthUC(TUint aVal,TRadix aRadix,TInt aWidth);

	void AppendNumUC(TUint64 aVal, TRadix aRadix=EDecimal);

	TInt AppendNum(TReal aVal,const TRealFormat &aFormat) __SOFTFP;

	void AppendNum(TInt64 aVal);

	void AppendNum(TUint64 aVal, TRadix aRadix);

	void AppendFormat(TRefByValue<const TDesC8> aFmt,TDes8Overflow *aOverflowHandler,...);

	void AppendFormat(TRefByValue<const TDesC8> aFmt,...);

	void AppendFormatList(const TDesC8 &aFmt,VA_LIST aList,TDes8Overflow *aOverflowHandler=NULL);

	// end of TDes8 methods

	//---------------------------------------------------

	//----------------------------------------------------------

	// These mutable RBuf8 methods have been privatised because

	// they make assumptions which are incompatible with the 

	// general use pattern of LString16.

	void Swap(RBuf8& aRBuf);

	TInt Create(TInt aMaxLength);

	void CreateL(TInt aMaxLength);

	TInt CreateMax(TInt aMaxLength);

	void CreateMaxL(TInt aMaxLength);

	TInt Create(const TDesC8& aDes);

	void CreateL(const TDesC8& aDes);

	TInt Create(const TDesC8& aDes,TInt aMaxLength);

	void CreateL(const TDesC8& aDes,TInt aMaxLength);

	void Close();

	void CleanupClosePushL();

	// end of privated RBuf16 methods

	//---------------------------------------------------

	void EnsureCapacityIncrementL(TInt aLengthIncrement);

	void IncreaseCapacityL();

private:

	//reserved data member for future-proofing

	TInt iReserved;

	};

/**

This is the 16-bit version of LString8. All the comments on LString8 apply equally.

@see LString8

@see RBuf16

@see TBuf16

@see TPtr16

@see HBufC16

@see TDesC16

@see TDes16

@see LString

*/

class LString16 : public RBuf16

	{

public:

	/*

	 * We add leaving (auto-resizing) variants of the standard TDes

	 * methods where appropriate, and enhance the behaviour of the

	 * corresponding operators to match

	 */

	LSTRING_CONSTRUCTORS_MAY_LEAVE

	IMPORT_C LString16();

	IMPORT_C ~LString16();

	// Construct with initial capacity

	IMPORT_C explicit LString16(TInt aInitialCapacity);

	// Construct by data copying

	IMPORT_C LString16(const TDesC16& aDes);

	IMPORT_C LString16(const TUint16* aZeroTerminatedString);