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

// All rights reserved.

// This component and the accompanying materials are made available

// under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

// which accompanies this distribution, and is available

// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

//

// Initial Contributors:

// Nokia Corporation - initial contribution.

//

// Contributors:

//

// Description:

// e32\include\e32std.inl

// 

//

// Global leaving operator new

inline TAny* operator new(TUint aSize, TLeave)

	{return User::AllocL(aSize);}

inline TAny* operator new(TUint aSize, TLeave, TUint aExtraSize)

	{return User::AllocL(aSize + aExtraSize);}

#if !defined(__VC32__) || defined (__MSVCDOTNET__)

inline TAny* operator new[](TUint aSize, TLeave)

	{return User::AllocL(aSize);}

#endif

// class Mem

inline TUint8* Mem::Copy(TAny* aTrg, const TAny* aSrc, TInt aLength)

/**

Copies data from a source location to a target location and returns a pointer 

to the end of the copied data.

The source and target areas can overlap.

The copy operation is optimised so that if both source and target locations 

are aligned on a word boundary, the operation performs the copy on a word 

by word basis.

@param aTrg    A pointer to the target location for the copy operation. 

@param aSrc    A pointer to the source location for the copy operation. 

@param aLength The number of bytes to be copied. This value must not

               be negative. 

@return A pointer to a location aLength bytes beyond aTrg (i.e. the location 

        aTrg+aLength).

@panic USER 90 In debug builds only, if aLength is negative. 

*/

	{ return (TUint8*)memmove(aTrg, aSrc, aLength) + aLength; }

inline TUint8* Mem::Move(TAny* aTrg, const TAny* aSrc, TInt aLength)

/**

Moves a block of data from a source location to a target location and returns 

a pointer to the end of the moved data.

The source and target areas can overlap.

Both source and target locations must be aligned on a word boundary. 

The specified length must also be a multiple of 4.

@param aTrg    A pointer to the target location for the move operation. This 

               pointer must be word aligned. 

@param aSrc    A pointer to the source location for the move operation. This

               pointer must be word aligned.

@param aLength The number of bytes to be copied. This value must be a multiple 

               of 4.

@return A pointer to a location aLength bytes beyond aTrg (i.e. the location 

        aTrg+aLength).

@panic USER 93 In debug builds only, if aTrg is not word aligned.

@panic USER 92 In debug builds only, if aSrc is not word aligned.

@panic USER 91 In debug builds only, if aLength is not a multiple of 4.

*/

	{ return (TUint8*)wordmove(aTrg, aSrc, aLength) + aLength; }

inline void Mem::Fill(TAny* aTrg, TInt aLength, TChar aChar)

/**

Fills a specified block of data with a specified character, replacing

any existing content.

The function assumes that the fill character is a non-Unicode character.

@param aTrg    A pointer to the location where filling is to start. 

@param aLength The number of bytes to be filled. This value must not

               be negative. 

@param aChar   The fill character.

@panic USER 95 In debug builds only, if aLength is negative.  

*/

	{ memset(aTrg, (TInt)(aChar.operator TUint()), aLength); }

inline void Mem::FillZ(TAny* aTrg,TInt aLength)

/**

Fills a specified block of data with binary zeroes (i.e. 0x00), replacing any 

existing content.

@param aTrg    A pointer to the location where filling is to start. 

@param aLength The number of bytes to be filled. This value must not

               be negative. 

@panic USER 95 In debug builds only, if aLength is negative.  

*/

	{ memclr(aTrg, aLength); }

#ifndef __GCC32__

inline TInt Mem::Compare(const TUint8* aLeft, TInt aLeftL, const TUint8* aRight, TInt aRightL)

/**

Compares a block of data at one specified location with a block of data at 

another specified location.

The comparison proceeds on a byte for byte basis, the result of the comparison 

is based on the difference of the first bytes to disagree.

The data at the two locations are equal if they have the same length and content. 

Where the lengths are different and the shorter section of data is the same 

as the first part of the longer section of data, the shorter is considered 

to be less than the longer.

@param aLeft   A pointer to the first (or left) block of 8 bit data

               to be compared.

@param aLeftL  The length of the first (or left) block of data to be compared,  

               i.e. the number of bytes.

@param aRight  A pointer to the second (or right) block of 8 bit data to be 

               compared.

@param aRightL The length of the second (or right) block of data to be compared 

               i.e. the number of bytes.

@return Positive, if the first (or left) block of data is greater than the 

        second (or right) block of data.

        Negative, if the first (or left) block of data is less than the

        second (or right) block of data.

        Zero, if both the first (or left) and second (or right) blocks of data

        have the same length and the same content.

*/

	{ return memcompare(aLeft, aLeftL, aRight, aRightL); }

#endif

// class RHeap

inline TInt RHeap::SetBrk(TInt aBrk)

	{ return ((RChunk*)&iChunkHandle)->Adjust(aBrk); }

// class TChar

#ifndef __KERNEL_MODE__

inline void TChar::SetChar(TUint aChar)

	{iChar=aChar;}

inline void TChar::Fold()

/**

Converts the character to a form which can be used in tolerant comparisons 

without control over the operations performed. 

Tolerant comparisons are those which ignore character differences like case 

and accents.

This function can be used when searching for a string in a text file or a 

file in a directory. Folding performs the following conversions: converts 

to lowercase, strips accents, converts all digits representing the values 

0..9 to the ordinary digit characters '0'..'9', converts all spaces (standard, 

non-break, fixed-width, ideographic, etc.) to the ordinary space character 

(0x0020), converts Japanese characters in the hiragana syllabary to katakana, 

and converts East Asian halfwidth and fullwidth variants to their ordinary 

forms. You can choose to perform any subset of these operations by using the 

other function overload.

@see User::Fold

*/

	{iChar=User::Fold(iChar);}

inline void TChar::LowerCase()

/**

Converts the character to its lowercase form.

Characters lacking a lowercase form are unchanged.

@see User::LowerCase

*/

	{iChar=User::LowerCase(iChar);}

inline void TChar::UpperCase()

/**

Converts the character to its uppercase form.

Characters lacking an uppercase form are unchanged.

@see User::UpperCase

*/

	{iChar=User::UpperCase(iChar);}

#ifdef _UNICODE

inline void TChar::Fold(TInt aFlags)

/**

Converts the character to a form which can be used in tolerant comparisons 

allowing selection of the specific fold operations to be performed.

@param aFlags Flags which define the operations to be performed. The values 

              are defined in the enum beginning with EFoldCase.

@see TChar::EFoldCase

@see User::Fold

*/

	{iChar=User::Fold(iChar,aFlags);}

inline void TChar::TitleCase()

/**

Converts the character to its titlecase form.

The titlecase form of a character is identical to its uppercase form unless 

a specific titlecase form exists. Characters lacking a titlecase form are 

unchanged.

*/

	{iChar=User::TitleCase(iChar);}

#endif

inline TBool TChar::Eos() const

/**

Tests whether the character is the C/C++ end-of-string character - 0.

@return True, if the character is 0; false, otherwise.

*/

	{return(iChar==0);}

#endif // _UNICODE

// Class TCallBack

inline TCallBack::TCallBack()

/**

Default constructor.

Sets the function pointer to Null.

*/

	{iFunction=NULL;}

inline TCallBack::TCallBack(TInt (*aFunction)(TAny *aPtr))

	: iFunction(aFunction),iPtr(NULL)

/**

Constructs the callback object with the specified callback function.

@param aFunction A pointer to the callback function. It takes an argument of

                 type TAny* and returns a TInt.

				 It must be either a static member of a class or a function

				 which is not a member of any class. 

*/

	{}

inline TCallBack::TCallBack(TInt (*aFunction)(TAny *aPtr),TAny *aPtr)

	: iFunction(aFunction),iPtr(aPtr)

/**

Constructs the callback object with the specified callback function and

a pointer to any object.

@param aFunction A pointer to the callback function. It takes an argument of

                 type TAny* and returns a TInt.

				 It must be either a static member of a class or a function

				 which is not a member of any class. 

@param aPtr      A pointer which is always passed to the callback function.

*/

	{}

/**

Calls the callback function.

@return The value returned by the callback function. The meaning of this value

        depends entirely on the context in which the callback function

        is called.

        For example, when used with the CIdle class, a false (zero) value

        indicates that the callback function should not be 	called again.

        As another example, when used with the CPeriodic class, the return

        value is ignored and is irrelevant in that context.

@see CIdle

@see CPeriodic        

*/

inline TInt TCallBack::CallBack() const

	{ return (iFunction ? (*iFunction)(iPtr) : 0); }

// Class TSglQue

template <class T>

inline TSglQue<T>::TSglQue()

/**

Constructs an empty list header and sets the offset value of the link object 

to zero.

In practice, never assume that the offset of the link object from the start 

of a list element is zero, even if the link object is declared as the first 

data member in the list element class.

If this default constructor is used, then call the SetOffset() function of 

the base class to ensure that the offset value is set correctly.

@see TSglQueBase::SetOffset

*/

	{}

template <class T>

inline TSglQue<T>::TSglQue(TInt aOffset)

	: TSglQueBase(aOffset)

/**

Constructs an empty list header and sets the offset of the link object to the 

specified value.

@param aOffset The offset of the link object from the start of a list element. 

                The macro _FOFF can be used to calculate this value.

@panic USER 75, if aOffset is not divisible by four.

@see _FOFF

*/

	{}

template <class T>

inline void TSglQue<T>::AddFirst(T &aRef)

/**

Inserts the specified list element at the front of the singly linked list.

If the list is not empty, the specified element becomes the first in the list. 

What was previously the first element becomes the second in the list.

@param aRef The list element to be inserted at the front of the singly linked 

            list.

*/

	{DoAddFirst(&aRef);}

template <class T>

inline void TSglQue<T>::AddLast(T &aRef)

/**

Inserts the specified list element at the back of the singly linked list.

If the list is not empty, the specified element becomes the last in the list. 

What was previously the last element becomes the next to last element in the 

list.

@param aRef The list element to be inserted at the back of the singly linked 

            list.

*/

	{DoAddLast(&aRef);}

template <class T>

inline TBool TSglQue<T>::IsFirst(const T *aPtr) const

/**

Tests whether the specified element is the first in the singly linked list.

@param aPtr A pointer to the element whose position in the list is to be

            checked.

@return True, if the element is the first in the list; false, otherwise.

*/

	{return(PtrAdd(aPtr,iOffset)==(T *)iHead);}

template <class T>

inline TBool TSglQue<T>::IsLast(const T *aPtr) const

/**

Tests whether the specified element is the last in the singly linked list.

@param aPtr A pointer to the element whose position in the list is 

            to be checked.

@return True, if the element is the last in the list; false, otherwise.

*/

	{return(PtrAdd(aPtr,iOffset)==(T *)iLast);}

template <class T>

inline T *TSglQue<T>::First() const

/**

Gets a pointer to the first list element in the singly linked list.

@return A pointer to the first list element in the singly linked list. If 

        the list is empty, this pointer is not necessarily NULL and must not

		be assumed to point to a valid object.

*/

	{return(PtrSub((T *)iHead,iOffset));}

template <class T>

inline T *TSglQue<T>::Last() const

/**

Gets a pointer to the last list element in the singly linked list.

@return A pointer to the last list element in the singly linked list. If the 

        list is empty, this pointer is not necessarily NULL and must not be

		assumed to point to a valid object.

*/

	{return(PtrSub((T *)iLast,iOffset));}

template <class T>

inline void TSglQue<T>::Remove(T &aRef)

/**

Removes the specified element from the singly linked list.

The singly linked list must not be empty.

@param aRef A list element to be removed from the singly linked list.

@panic USER 76, if the element to be removed is not in the list

*/

	{DoRemove(&aRef);}

// Class TDblQue

template <class T>

inline TDblQue<T>::TDblQue()

/**

Constructs an empty list header and sets the offset value of the link object 

to zero.

In practice, never assume that the offset of the link object from the start 

of a list element is zero, even if the link object is declared as the first 

data member in the list element class.

If this default constructor is used, then call the SetOffset() function of 

the base class to ensure that the offset value is set correctly.

@see TDblQueBase::SetOffset()

*/

	{}

template <class T>

inline TDblQue<T>::TDblQue(TInt aOffset)

	: TDblQueBase(aOffset)

/**

Constructs an empty list header and sets the offset of the link object to the 

specified value.

@param aOffset The offset of the link object from the start of a list element. 

                The macro _FOFF can be used to calculate this value.

@panic USER 78. if aOffset is not divisble by 4.

@see _FOFF

*/

	{}

template <class T>

inline void TDblQue<T>::AddFirst(T &aRef)

/**

Inserts the specified list element at the front of the doubly linked list.

If the list is not empty, the specified element becomes the first in the list. 

What was previously the first element becomes the second in the list.

@param aRef The list element to be inserted at the front of the doubly linked 

            list.

*/

	{DoAddFirst(&aRef);}

template <class T>

inline void TDblQue<T>::AddLast(T &aRef)

/**

Inserts the specified list element at the back of the doubly linked list.

If the list is not empty, the specified element becomes the last in the list. 

What was previously the last element becomes the next to last element in the 

list.

@param aRef The list element to be inserted at the back of the doubly linked 

            list.

*/

	{DoAddLast(&aRef);}

template <class T>

inline TBool TDblQue<T>::IsHead(const T *aPtr) const

/**

Tests whether the end of a list has been reached.

A doubly linked list is circular; in following the chain of elements in a 

list (e.g. using the iterator operator++ or operator--), the chain eventually 

reaches the end of the list and aPtr corresponds to the header (although it 

will not point to a valid T object).

@param aPtr The pointer value to be checked. 

@return True, if the end of the list has been reached. False, if the end of 

        the list has not been reached; aPtr points to an element in the list.

*/

	{return(PtrAdd(aPtr,iOffset)==(T *)&iHead);}

template <class T>

inline TBool TDblQue<T>::IsFirst(const T *aPtr) const

/**

Tests whether the specified element is the first in the doubly linked list.

@param aPtr A pointer to the element whose position in the list is to be checked.

@return True, if the element is the first in the list; false, otherwise.

*/

	{return(PtrAdd(aPtr,iOffset)==(T *)iHead.iNext);}

template <class T>

inline TBool TDblQue<T>::IsLast(const T *aPtr) const

/**

Tests whether the specified element is the last in the doubly linked list.

@param aPtr A pointer to the element whose position in the list is to be checked.

@return True, if the element is the last in the list; false, otherwise.

*/

	{return(PtrAdd(aPtr,iOffset)==(T *)iHead.iPrev);}

template <class T>

inline T *TDblQue<T>::First() const

/**

Gets a pointer to the first list element in the doubly linked list.

@return A pointer to the first list element in the doubly linked list. If 

        the list is empty, this pointer is not necessarily NULL and must not

		be assumed to point to a valid object.

*/

	{

#if defined (_DEBUG)

	__DbgTestEmpty();

#endif

    return(PtrSub((T *)iHead.iNext,iOffset));

    }

template <class T>

inline T *TDblQue<T>::Last() const

/**

Gets a pointer to the last list element in the doubly linked list.

@return A pointer to the last list element in the doubly linked list. If the 

        list is empty, this pointer is not necessarily NULL and must not be assumed 

        to point to a valid object.

*/

	{

#if defined (_DEBUG)

	__DbgTestEmpty();

#endif

	return(PtrSub((T *)iHead.iPrev,iOffset));

	}

// Class TPriQue

template <class T>

inline TPriQue<T>::TPriQue()

/**

Default constructor.

Constructs an empty list header and sets the offset value of the link

object to zero.

In practice, never assume that the offset of the link object from the start

of a list element is zero, even if the link object is declared as the first

data member in the list element class.

If this default constructor is used, then call the SetOffset() function of

the base class to ensure that the offset value is set correctly.

@see TDblQueBase::SetOffset

*/

	{}

template <class T>

inline TPriQue<T>::TPriQue(TInt aOffset)

	: TDblQueBase(aOffset)

/**

Constructs an empty list header and sets the offset of the link object

to the specified value.

@param aOffset The offset of the link object from the start of a list element.

                The macro _FOFF can be used to calculate this value.

@panic USER 78 if aOffset is not divisible by four.		  

*/

	{}

template <class T>

inline void TPriQue<T>::Add(T &aRef)

/**

Inserts the specified list element in descending priority order.

If there is an existing list element with the same priority, then the new

element is added after the existing element.

@param aRef The list element to be inserted.

*/

	{DoAddPriority(&aRef);}

template <class T>

inline TBool TPriQue<T>::IsHead(const T *aPtr) const

/**

Tests whether the end of a list has been reached.

A doubly linked list is circular; in following the chain of elements in a list

(e.g. using the iterator operator++ or operator--), the chain eventually

reaches the end of the list and aPtr corresponds to the header (although it

will not point to a valid T object).

@param aPtr The pointer value to be checked.

@return True, if the end of the list has been reached. False, if the end of the

        list has not been reached; aPtr points to an element in the list.

*/

	{return(PtrAdd(aPtr,iOffset)==(T *)&iHead);}

template <class T>

inline TBool TPriQue<T>::IsFirst(const T *aPtr) const

/**

Tests whether the specified element is the first in the linked list.

@param aPtr A pointer to the element whose position in the list is to

            be checked.

@return True, if the element is the first in the list; false, otherwise.

*/

	{return(PtrAdd(aPtr,iOffset)==(T *)iHead.iNext);}

template <class T>

inline TBool TPriQue<T>::IsLast(const T *aPtr) const

/**

Tests whether the specified element is the last in the linked list.

@param aPtr A pointer to the element whose position in the list is to

            be checked.

@return True, if the element is the last in the list; false, otherwise.

*/

	{return(PtrAdd(aPtr,iOffset)==(T *)iHead.iPrev);}

template <class T>

inline T *TPriQue<T>::First() const

/**

Gets a pointer to the first list element in the linked list.

@return A pointer to the first list element in the linked list.

        If the list is empty, this pointer is not necessarily NULL and must

		not be assumed to point to a valid object.

*/

	{return(PtrSub((T *)iHead.iNext,iOffset));}

template <class T>

inline T *TPriQue<T>::Last() const

/**

Gets a pointer to the last list element in the linked list.

@return A pointer to the last list element in the linked list.

        If the list is empty, this pointer is not necessarily NULL and must

		not be assumed to point to a valid object.

*/

	{return(PtrSub((T *)iHead.iPrev,iOffset));}

// Class TDeltaQue

template <class T>

inline TDeltaQue<T>::TDeltaQue()

/**

Constructs an empty list header and sets the offset value of the link object 

to zero.

In practice, never assume that the offset of the link object from the start 

of a list element is zero, even if the link object is declared as the first 

data member in the list element class.

If this default constructor is used, then call the TDblQueBase::SetOffset() 

function in the base class to ensure that the offset value is set correctly.

TDeltaQueBase::iFirstDelta is set to NULL.

@see TDblQueBase::SetOffset

*/

	{}

template <class T>

inline TDeltaQue<T>::TDeltaQue(TInt aOffset)

	: TDeltaQueBase(aOffset)

/**

Constructs an empty list header and sets the offset of the link object to the 

specified value.

TDeltaQueBase::iFirstDelta is set to NULL.

@param aOffset The offset of the link object from the start of a list element. 

                The macro _FOFF can be used to calculate this value. 

@panic USER 78, if aOffset is not divisible by four.

@see _FOFF

*/

	{}

template <class T>

inline void TDeltaQue<T>::Add(T &aRef,TInt aDelta)

/**

Adds the specified list element, having the specified 'distance' from the

nominal zero point, into the list.

The element is added into the list, the adjacent delta values adjusted, and 

a suitable delta value assigned to the new element, so that the new element 

is at the specified 'distance' from the nominal zero point.

@param aRef   The list element to be inserted.

@param aDelta The 'distance' from the nominal zero point.

*/

	{DoAddDelta(&aRef,aDelta);}

template <class T>

inline void TDeltaQue<T>::Remove(T &aRef)

/**

Removes the specified list element from the linked list.

The delta value of the element following the removed element is adjusted

so that its 'distance' from the nominal zero point remains the same.

@param aRef The list element to be removed.

*/

	{DoRemove(&aRef);}

template <class T>

inline T *TDeltaQue<T>::RemoveFirst()

/**

Removes the first list element from the linked list if its delta value is zero 

or negative.

@return A pointer to the element removed from the linked list. This is NULL, 

        if the first element has a positive delta value.

*/

	{return((T *) DoRemoveFirst());}

// Class TSglQueIter

template <class T>

inline TSglQueIter<T>::TSglQueIter(TSglQueBase &aQue)

	: TSglQueIterBase(aQue)

/**

Constructs the iterator for the specified singly linked list.

The iterator can be constructed whether or not the list contains any elements.

If the list does contain elements, the iterator pointer is set to the first one.

If the list has no elements, the iterator pointer is not set and the conversion 

operator T*() and the post increment operator ++ subsequently return NULL. 

Once elements have been added to the list, use either the

TSglQueIter::Set() function or the TSglQueIterBase::SetToFirst() function to set the 

iterator pointer.

@param aQue A reference to a singly linked list header.

@see TSglQueIter::Set

@see TSglQueIterBase::SetToFirst

*/

	{}

template <class T>

inline void TSglQueIter<T>::Set(T &aLink)

/**

Sets the iterator to point to a specific element in the list.

This function can be used to alter the pointer at any time during the iterator's 

existence. The referenced element must be in the list, otherwise the result 

is undefined.

@param aLink A reference to the element from where iteration is to continue.

*/

	{DoSet(&aLink);}

template <class T>

inline TSglQueIter<T>::operator T *()

/**

Gets a pointer to the iterator’s current element.

The operator is normally used implicitly; e.g. some member functions of the

list header class TSglQue require a pointer to an element (of type class T)

as a parameter, but in practice an iterator is often passed instead.

This operator performs the necessary conversion.

*/

	{return((T *)DoCurrent());}

template <class T>

inline T *TSglQueIter<T>::operator++(TInt)

/**

Gets a pointer to the iterator's current element and then sets the iterator 

to point to the next element.

Repeated use of this operator allows successive elements to be accessed.

@return A pointer to the current list element, if the iterator points to an 

        element. NULL, if the iterator does not point to an element; i.e. the

		iterator pointer has reached the end of the list.

*/

	{return((T *)DoPostInc());}

// Class TDblQueIter

template <class T>

inline TDblQueIter<T>::TDblQueIter(TDblQueBase &aQue)

	: TDblQueIterBase(aQue)

/**

Constructs the iterator for the specified doubly linked list

The iterator can be constructed whether or not the list contains any elements.

If the list does contain elements, the iterator pointer is set to the first one.

If the list has no elements, the iterator pointer is not set and the conversion 

operator T*(), the post increment operator++() and the post decrement operator 

--() subsequently return NULL. Once elements have been added to the list, use 

either the TDblQueIter::Set() function, the TDblQueIterBase::SetToFirst() 

function or the TDblQueIterBase::SetToLast() function to set the iterator 

pointer.

@param aQue A reference to a doubly linked list header.

@see TDblQueIter::Set

@see TDblQueIterBase::SetToFirst

@see TDblQueIterBase::SetToLast

*/

	{}

template <class T>

inline void TDblQueIter<T>::Set(T &aLink)

/**

Sets the iterator to point to a specific element in the list.

This function can be used to alter the pointer at any time during

the iterator's existence. The referenced element must be in the list,

otherwise the result is undefined.

@param aLink A reference to the element from where iteration is to continue.

*/

	{DoSet(&aLink);}

template <class T>

inline TDblQueIter<T>::operator T *()

/**

Gets a pointer to the iterator’s current element.

The operator is normally used implicitly; e.g. some member functions of the

list header class TDblQue require a pointer to an element (of type class T)

as a parameter but in practice, an iterator is often passed instead.

This operator performs the necessary conversion.

@return A pointer to the current element, if the iterator points to an element

        in the list. NULL, if the iterator does not point to an element;

		i.e. the iterator pointer has previously reached the end of the list