// 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 <e32base.h>

#include <estring.h>

const TUint KDefaultExpandSize = 16;

/**

Aligns the supplied capacity to the nearest growth factor

For performance reasons the growth factor, KDefaultExpandSizeShift,

is expressed as an exponent of 2 so shifting can be used to achieve the

alignment. 

a KDefaultExpandSizeShift value of 4 is equivalent to 16; 

giving newCapacity = ((newCapacity / 16) + 1) * 16

@param aNewCapacity The size to be aligned

@return The new, aligned capacity

*/

static inline TInt AlignCapacity(TInt aNewCapacity)

	{

	const TUint KDefaultExpandSizeShift = 4;

	return (TInt)((((TUint)aNewCapacity >> KDefaultExpandSizeShift) + 1) << KDefaultExpandSizeShift);

	}

/**

Guarantees that MaxLength() is greater than or equal to the supplied

capacity, reallocating the supplied capacity if necessary.

The actual value of MaxLength() after a call may differ from the exact

value requested, but if it does differ it will always be greater. This

flexibility allows the implementation to manage heap buffers more

efficiently.

The string descriptor's heap buffer may be reallocated in order to

accommodate the new size. As a

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

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

invalidated.

@param aMinRequiredCapacity The minimum value of MaxLength() required

@leave KErrNoMemory if the underlying buffer needs to be

grown and there are insufficient resources to do so

*/

void LString8::ReserveL(TInt aMinRequiredCapacity)

	{

	if (MaxLength() < aMinRequiredCapacity)

		{

		ReAllocL(AlignCapacity(aMinRequiredCapacity));

		}

	}

/**

Guarantees that MaxLength() is greater than or equal to the supplied

integer parameter, growing the underlying heap buffer if necessary.

The growth is exponential; maxLength *= 1.5

This is reported to give an amortised complexity of O(n) when adding

n characters. 

If the required capacity is larger than the expanded size then the

required capacity is used instead.

The actual value of MaxLength() after a call may differ from the exact

value requested, but if it does differ it will always be greater. This

flexibility allows the implementation to manage heap buffers more

efficiently.

@param aRequiredCapacity The minimum value of MaxLength() required

@leave KErrNoMemory if the underlying buffer needs to be

grown and there are insufficient resources to do so

*/

void LString8::ReserveCapacityGrowExponentialL(TInt aRequiredCapacity)

	{

	//work in unsigned int for the appropriate shift operation

	TUint max_length = MaxLength();

	TUint requiredCapacity = aRequiredCapacity; 

	if (max_length < requiredCapacity)

		{

		// max_length *= 3/2;

		max_length = (max_length + (max_length << 1)) >> 1;

		// take the bigger of the extended buffer or the required capactiy 

		ReAllocL(AlignCapacity((TInt)(max_length > requiredCapacity ? max_length : requiredCapacity)));

		}

	}

/**

Guarantees that free space in the buffer greater than or equal the 

supplied integer parameter, growing the underlying heap buffer 

if necessary.

@param aRequiredEmptySpace The minimum value of free space required

@leave KErrNoMemory if the underlying buffer needs to be

grown and there are insufficient resources to do so

*/

void LString8::ReserveFreeCapacityGrowExponentialL(TInt aRequiredEmptySpace)

	{

	ReserveCapacityGrowExponentialL(Length() + aRequiredEmptySpace);

	}

/**

Grows the underlying buffer using the exponential growth 

function. Guarantees that MaxLength() is greater than or 

equal to 1.5 * the current MaxLength.

@leave KErrNoMemory if the underlying buffer needs to be

grown and there are insufficient resources to do so

*/

void LString8::ReserveCapacityGrowExponentialL()

	{

	ReserveCapacityGrowExponentialL(MaxLength() + 1);

	}

/**

Default constructor.

Constructs a zero-length 8-bit resizable string descriptor.

Note that the resulting object owns no allocated memory yet. This

default constructor never leaves.

*/

EXPORT_C LString8::LString8() 

	: iReserved(0)

	{

	}

/**

Destructor.

Frees any heap-allocated resources owned by this string descriptor. It

is safe to rely on this destructor to perform all necessary cleanup;

it is not necessary use the cleanup stack or to call Close() manually.

@see RBuf8::Close

*/

EXPORT_C LString8::~LString8()

	{

	RBuf8::Close();

	}

/**

Constructor to create a 8-bit resizable string descriptor with an

initial capacity.

The function allocates sufficient memory to contain descriptor data up to

the specified initial maximum length. 

The current length of the descriptor is set to zero. The maximum length of

the descriptor is set to the specified value.

@param aMaxLength  The maximum length of the descriptor.

@leave KErrNoMemory If there is insufficient memory.

@see RBuf8::CreateL

*/

EXPORT_C LString8::LString8(TInt aMaxLength)

	: iReserved(0)

	{

	RBuf8::CreateL(aMaxLength);

	}

/**

Constructor to create a 8-bit resizable string descriptor from a

pre-allocated heap descriptor.

Transfers ownership of the specified heap descriptor to this object.

@param aHBuf  The heap descriptor to be transferred to this object.

              This pointer can be NULL, which means that a zero length

              8-bit resizable string descriptor is created.

@see RBuf8::RBuf8(HBufC8*)

*/

EXPORT_C LString8::LString8(HBufC8* aHBuf)

	: iReserved(0)

	{

	if (aHBuf)

		RBuf8::Assign (aHBuf);

	}

/**

Constructor to create a 8-bit resizable string descriptor from a

pre-allocated raw heap buffer.

The allocated memory forms the buffer for this string descriptor. The

current length of the descriptor is set to zero.

@param aHeapCell  The allocated memory to be assigned to this object. This

                  pointer can be NULL, which means that a zero length 8-bit

                  resizable buffer descriptor is created.

@param aMaxLength The maximum length of the constructed string descriptor.

@panic USER 8 If the specified maximum length is greater then the size of

              the allocated heap cell, or the specified maximum length

              is NOT zero when the pointer to the heap cell is NULL.

@see RBuf8::Assign()

*/

EXPORT_C LString8::LString8(TUint8* aHeapCell,TInt aMaxLength)

	: iReserved(0)

	{

	RBuf8::Assign(aHeapCell, aMaxLength);

	}

/**

Constructor to create a 8-bit resizable string descriptor from a

pre-allocated raw heap buffer.

The allocated memory forms the buffer for this string descriptor. The

current length of the descriptor is set to the value of the second

parameter.

@param aHeapCell  The allocated memory to be assigned to this object.

@param aLength	  The length of the resulting string descriptor.

@param aMaxLength The maximum length of the resulting string descriptor.

@panic USER 8 If the specified maximum length is greater then the size of

              the allocated heap cell, or the specified length is greater then

              the specified	maximum length, or the specified maximum length

              is NOT zero when the pointer to the heap cell is NULL.

@see RBuf8::Assign()

*/

EXPORT_C LString8::LString8(TUint8* aHeapCell,TInt aLength,TInt aMaxLength)

	: iReserved(0)

	{

	RBuf8::Assign(aHeapCell, aLength, aMaxLength);

	}

/**

Constructor to create a 8-bit resizable string descriptor to contain

a copy of the specified (source) descriptor, or leave on failure.

The constructor allocates sufficient memory so that this string

descriptor's maximum length is the same as the length of the source

descriptor. Both the current length and the maximum length of this

string descriptor are set to the length of the source descriptor.

The data contained in the source descriptor is copied into this string

descriptor.

@param aDes Source descriptor to be copied into this object.

@leave KErrNoMemory If there is insufficient memory.

@see RBuf8::CreateL()

*/

EXPORT_C LString8::LString8(const TDesC8& aDes)

	: iReserved(0)

	{

	RBuf8::CreateL(aDes);

	}

/**

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

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

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

This operation may cause the target 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.

Note that the automatic resizing performed is a change to the

functionality of this operation compared to other descriptor

classes. This change is only active on objects directly declared

LString8; when LString8 instances are instead manipulated via

references to TDes8 or TDesC8, the standard (non-resizing, panicing)

variant is invoked.

@param aDes A 8-bit non-modifiable descriptor.

@return A reference to this 8-bit string descriptor.

@@leave KErrNoMemory If the heap buffer of the string descriptor being

              assigned to needs to be expanded, but there is

              insufficient memory to do so

@see LString8::CopyL

*/

EXPORT_C LString8& LString8::operator=(const TDesC8& aDes)

	{

	CopyL(aDes);

	return *this;

	}

/**

Transfers ownership of the specified 8-bit descriptor to this object. 

@param aBuf The source 8-bit buffer. The ownership of this

             object's buffer is to be transferred.

@see Assign()

*/

EXPORT_C LString8& LString8::operator=(HBufC8* aBuf)

	{

	Assign(aBuf); 

	return *this;

	}

/**

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

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

The length of this descriptor is set to reflect the new 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.

@param aDes A 8-bit non-modifiable descriptor.

@leave KErrNoMemory If the heap buffer of the string descriptor being

              assigned to needs to be expanded, but there is

              insufficient memory to do so

@see LString8::operator=

@see TDes8::Copy

*/

EXPORT_C void LString8::CopyL(const TDesC8& aDes)

	{

	ReserveL(aDes.Length());

	RBuf8::Copy(aDes);

	}

/**

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

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

The length of this descriptor is set to reflect the new 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.

@param aDes A 16-bit non-modifiable descriptor.A 16-bit non-modifiable descriptor.

			Each double-byte value can 

            only be copied into the corresponding single byte when the

            double-byte value is less than decimal 256. A double-byte value of

            256 or greater cannot be  copied and the corresponding single byte

            is set to a value of decimal 1.

@leave KErrNoMemory If the heap buffer of the string descriptor being

       assigned to needs to be expanded, but there is

       insufficient memory to do so

@see TDes8::Copy

*/

EXPORT_C void LString8::CopyL(const TDesC16& aDes)

{

	ReserveL(aDes.Length());

	RBuf8::Copy(aDes);

}

/**

Copy constructor to create a 8-bit resizable string descriptor to

contain a copy of the specified (source) string descriptor's data, or

leave on failure.

The constructor allocates sufficient memory so that this string

descriptor's maximum length is the same as the length of the source

string descriptor. Both the current length and the maximum length of

this string descriptor are set to the length of the source descriptor.

The data contained in the source string descriptor is copied into this

string descriptor.

@param aDes Source string descriptor to be copied into this object.

@leave KErrNoMemory If there is insufficient memory.

@see RBuf8::CreateL()

*/

EXPORT_C LString8::LString8(const LString8& aDes)

	: iReserved(0)

	{

	RBuf8::CreateL(aDes);

	}

/**

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

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

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

This operation may cause the target 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.

Note that the automatic resizing performed is a change to the

functionality of this operation compared to other descriptor

classes. This change is only active on objects directly declared

LString8; when LString8 instances are instead manipulated via

references to TDes8 or TDesC8, the standard (non-resizing, panicing)

variant is invoked.

@param aDes A 8-bit string descriptor.

@return A reference to this 8-bit string descriptor.

@leave KErrNoMemory If the heap buffer of the string descriptor being

              assigned to needs to be expanded, but there is

              insufficient memory to do so

@see LString8::CopyL

*/

EXPORT_C LString8& LString8::operator=(const LString8& aDes)

	{

	CopyL(aDes);

	return *this;

	}

/**

Constructor to create a 8-bit resizable string descriptor containing

a copy of the specified (source) zero-terminated string data, or leave

on failure.

The constructor allocates sufficient memory so that this string

descriptor's maximum length is the same as the length of the source

string. Both the current length and the maximum length of this string

descriptor are set to the length of the source string. 

The data contained in the source string is copied into this string

descriptor. The zero terminator is not copied.

@param aZeroTerminatedString A pointer to a zero-terminated string

@leave KErrNoMemory If there is insufficient memory.

@see LString8::CopyL

*/

EXPORT_C LString8::LString8(const TUint8* aZeroTerminatedString)

	: iReserved(0)

	{

	CopyL(aZeroTerminatedString);

	}

/**

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

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

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

This operation may cause the target 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.

Note that the automatic resizing performed is a change to the

functionality of this operation compared to other descriptor

classes. This change is only active on objects directly declared

LString8; when LString8 instances are instead manipulated via

references to TDes8 or TDesC8, the standard (non-resizing, panicing)

variant is invoked.

@param aZeroTerminatedString A pointer to a zero-terminated string

@return A reference to this 8-bit string descriptor.

@leave KErrNoMemory If the heap buffer of the string descriptor being

              assigned to needs to be expanded, but there is

              insufficient memory to do so

@see LString8::CopyL

*/

EXPORT_C LString8& LString8::operator=(const TUint8* aZeroTerminatedString)

	{

	CopyL(aZeroTerminatedString);

	return *this;

	}

/**

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

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

The length of this descriptor is set to reflect the new 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.

@param aZeroTerminatedString A pointer to a zero-terminated string

@leave KErrNoMemory If the heap buffer of the string descriptor being

              assigned to needs to be expanded, but there is

              insufficient memory to do so

@see LString8::operator=

@see TDes8::Copy

*/