// 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 LString16::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 LString16::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 LString16::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 LString16::ReserveCapacityGrowExponentialL()

	{

	ReserveCapacityGrowExponentialL(MaxLength() + 1);

	}

/**

Default constructor.

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

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

default constructor never leaves.

*/

EXPORT_C LString16::LString16() 

	: 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 RBuf16::Close

*/

EXPORT_C LString16::~LString16()

	{

	RBuf16::Close();

	}

/**

Constructor to create a 16-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 RBuf16::CreateL

*/

EXPORT_C LString16::LString16(TInt aMaxLength)

	: iReserved(0)

	{

	RBuf16::CreateL(aMaxLength);

	}

/**

Constructor to create a 16-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

              16-bit resizable string descriptor is created.

@see RBuf16::RBuf16(HBufC16*)

*/

EXPORT_C LString16::LString16(HBufC16* aHBuf)

	: iReserved(0)

	{

	if (aHBuf)

		RBuf16::Assign (aHBuf);

	}

/**

Constructor to create a 16-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 16-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 RBuf16::Assign()

*/

EXPORT_C LString16::LString16(TUint16* aHeapCell,TInt aMaxLength)

	: iReserved(0)

	{

	RBuf16::Assign(aHeapCell, aMaxLength);

	}

/**

Constructor to create a 16-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 RBuf16::Assign()

*/

EXPORT_C LString16::LString16(TUint16* aHeapCell,TInt aLength,TInt aMaxLength)

	: iReserved(0)

	{

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

	}

/**

Constructor to create a 16-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 RBuf16::CreateL()

*/

EXPORT_C LString16::LString16(const TDesC16& aDes)

	: iReserved(0)

	{

	RBuf16::CreateL(aDes);

	}

/**

Copies data into this 16-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

LString16; when LString16 instances are instead manipulated via

references to TDes16 or TDesC16, the standard (non-resizing, panicing)

variant is invoked.

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

@return A reference to this 16-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 LString16::CopyL

*/

EXPORT_C LString16& LString16::operator=(const TDesC16& aDes)

	{

	CopyL(aDes);

	return *this;

	}

/**

Transfers ownership of the specified 16-bit resizable descriptor's this object. 

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

             object's buffer is to be transferred.

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

@see Assign()

*/

EXPORT_C LString16& LString16::operator=(HBufC16* aBuf)

	{

	Assign(aBuf); 

	return *this;

	}

/**

Copies data into this 16-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.

@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 LString16::operator=

@see TDes16::Copy

*/

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

	{

	ReserveL(aDes.Length());

	RBuf16::Copy(aDes);

	}

/**

Copy constructor to create a 16-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 RBuf16::CreateL()

*/

EXPORT_C LString16::LString16(const LString16& aDes)

	: iReserved(0)

	{

	RBuf16::CreateL(aDes);

	}

/**

Copies data into this 16-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

LString16; when LString16 instances are instead manipulated via

references to TDes16 or TDesC16, the standard (non-resizing, panicing)

variant is invoked.

@param aDes A 16-bit string descriptor.

@return A reference to this 16-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 LString16::CopyL

*/

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

	{

	CopyL(aDes);

	return *this;

	}

/**

Constructor to create a 16-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 LString16::CopyL

*/

EXPORT_C LString16::LString16(const TUint16* aZeroTerminatedString)

	: iReserved(0)

	{

	CopyL(aZeroTerminatedString);

	}

/**

Copies data into this 16-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

LString16; when LString16 instances are instead manipulated via

references to TDes16 or TDesC16, the standard (non-resizing, panicing)

variant is invoked.

@param aZeroTerminatedString A pointer to a zero-terminated string

@return A reference to this 16-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 LString16::CopyL

*/

EXPORT_C LString16& LString16::operator=(const TUint16* aZeroTerminatedString)

	{

	CopyL(aZeroTerminatedString);

	return *this;

	}

/**

Copies data into this 16-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 LString16::operator=

@see TDes16::Copy

*/

EXPORT_C void LString16::CopyL(const TUint16* aZeroTerminatedString)

	{

	ReserveL(User::StringLength(aZeroTerminatedString));

	RBuf16::Copy(aZeroTerminatedString);

	}

/**

Copies 8-bit descriptor data into this 16-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.

Each 8-bit character value is widened to a 16-bit character value as

part of the copying process.

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