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

// e32\include\e32std.h

// 

//

#ifndef __E32STD_H__

#define __E32STD_H__

#ifdef __KERNEL_MODE__

#error !! Including e32std.h in kernel code !!

#endif

#include <e32cmn.h>

/**

@publishedAll

@released

*/

class TFunctor

	{

public:

	IMPORT_C virtual void operator()() =0;

	};

/**

@publishedAll

@released

Encapsulates a general call-back function.

The class encapsulates:

1. a pointer to a function which takes an argument of type TAny* and returns 

   a TInt.

2. a pointer which is passed to the function every time it is called.

   The pointer can point to any object. It can also be NULL.

The callback function can be a static function of a class,

e.g. TInt X::Foo(TAny *) or it can be a function which is not a member of

any class, e.g. TInt Foo(TAny *).

When used with the CIdle and the CPeriodic classes, the callback function

is intended to be called repeatedly; the encapsulated pointer is passed on

each call. Typically, the pointer refers to an object which records the state

of the task across each call. When used with CIdle, the callback function

should also return a true (non-zero) value if it is intended to be called

again, otherwise it should return a false (zero) value.

@see CIdle

@see CPeriodic

*/

class TCallBack

	{

public:

	inline TCallBack();

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

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

	inline TInt CallBack() const;

public:

	/**

	A pointer to the callback function.

	*/

	TInt (*iFunction)(TAny* aPtr);

	/**

	A pointer that is passed to the callback function when

	the function is called.

	*/

	TAny* iPtr;

	};

/**

@publishedAll

@released

An object embedded within a class T so that objects of type T can form part 

of a singly linked list.

A link object encapsulates a pointer to the next link object in the list.

@see TSglQue

*/

class TSglQueLink

	{

#if defined _DEBUG

public:

	inline TSglQueLink() : iNext(NULL)

	/**

	An explicitly coded default constructor that is only defined for DEBUG builds.

	It sets the pointer to the next link object to NULL.

	@see iNext

	*/

	{}

#endif

private:

	IMPORT_C void Enque(TSglQueLink* aLink);

public:

	/**

	A pointer to the next link object in the list.

	*/

	TSglQueLink* iNext;

	friend class TSglQueBase;

	};

/**

@publishedAll

@released

A base class that provides implementation for the link object of a doubly

linked list.

It also encapsulates pointers both to the next and the previous link 

objects in the doubly linked list.

The class is abstract and is not intended to be instantiated.

@see TDblQueLink

*/

class TDblQueLinkBase

	{

public:

	inline TDblQueLinkBase() : iNext(NULL)

	/**

	Default constructor.

	It sets the pointer to the next link object to NULL.

	@see iNext

	*/

	{}

	IMPORT_C void Enque(TDblQueLinkBase* aLink);

	IMPORT_C void AddBefore(TDblQueLinkBase* aLink);

public:

	/**

	A pointer to the next link object in the list.

	*/

	TDblQueLinkBase* iNext;

	/**

	A pointer to the previous link object in the list.

	*/

	TDblQueLinkBase* iPrev;

	};

/**

@publishedAll

@released

An object embedded within a class T so that objects of type T can form part 

of a doubly linked list.

*/

class TDblQueLink : public TDblQueLinkBase

	{

public:

	IMPORT_C void Deque();

	};

/**

@publishedAll

@released

An object embedded within a class T so that objects of type T can form part

of an ordered doubly linked list.

Objects are added to the doubly linked list in descending priority order.

*/

class TPriQueLink : public TDblQueLink

	{

public:

	/**

	The priority value.

    Objects are added to the doubly linked list in descending order of this value.

	*/

	TInt iPriority;

	};

/**

@publishedAll

@released

An object embedded within a class T so that objects of type T can form part 

of a delta doubly linked list.

*/

class TDeltaQueLink : public TDblQueLinkBase

	{

public:

	/**

	The delta value.

	*/

	TInt iDelta;

	};

/**

@publishedAll

@released

An object embedded within a class T so that objects of type T can form part 

of a doubly linked list sorted by tick count.

*/

class TTickCountQueLink : public TDblQueLink

	{

public:

	/**

	The tick count.

	*/

	TUint iTickCount;

	};

/**

@publishedAll

@released

A base class that provides implementation for the singly linked list header. 

It also encapsulates the offset value of a link object.

The class is abstract and is not intended to be instantiated.

@see TSglQue

*/

class TSglQueBase

	{

public:

	IMPORT_C TBool IsEmpty() const;

	IMPORT_C void SetOffset(TInt aOffset);

	IMPORT_C void Reset();

protected:

	IMPORT_C TSglQueBase();

	IMPORT_C TSglQueBase(TInt aOffset);

	IMPORT_C void DoAddFirst(TAny* aPtr);

	IMPORT_C void DoAddLast(TAny* aPtr);

	IMPORT_C void DoRemove(TAny* aPtr);

protected:

	/**

	A pointer to the first element in the list.

	*/

	TSglQueLink* iHead;

	/**

	A pointer to the last element in the list.

	*/

	TSglQueLink* iLast;

	/**

	The offset of a component link object within elements that form the list.

	*/

	TInt iOffset;

private:

	TSglQueBase(const TSglQueBase& aQue);

	TSglQueBase &operator=(const TSglQueBase& aQue);

	friend class TSglQueIterBase;

	};

/**

@publishedAll

@released

A base class that provides implementation for the doubly linked list header. 

It also encapsulates the offset value of a link object.

The class is abstract and is not intended to be instantiated.

@see TDblQue

*/

class TDblQueBase

	{

public:

	IMPORT_C TBool IsEmpty() const;

	IMPORT_C void SetOffset(TInt aOffset);

	IMPORT_C void Reset();

protected:

	IMPORT_C TDblQueBase();

	IMPORT_C TDblQueBase(TInt aOffset);

	IMPORT_C void DoAddFirst(TAny* aPtr);

	IMPORT_C void DoAddLast(TAny* aPtr);

	IMPORT_C void DoAddPriority(TAny* aPtr);

	IMPORT_C void __DbgTestEmpty() const;

protected:

	/**

	The head, or anchor point of the queue.

	*/

	TDblQueLink iHead;

	/**

	The offset of a component link object within elements that form the list.

	*/

	TInt iOffset;

private:

	TDblQueBase(const TDblQueBase& aQue);

	TDblQueBase& operator=(const TDblQueBase& aQue);

	friend class TDblQueIterBase;

	};

/**

@publishedAll

@released

A base class that provides implementation for the TDeltaQue template class.

The class is abstract and is not intended to be instantiated.

@see TDeltaQue

*/

class TDeltaQueBase : public TDblQueBase

	{

public:

	IMPORT_C TBool CountDown();

	IMPORT_C TBool CountDown(TInt aValue);

	IMPORT_C TBool FirstDelta(TInt& aValue);

	IMPORT_C void Reset();

protected:

	IMPORT_C TDeltaQueBase();

	IMPORT_C TDeltaQueBase(TInt aOffset);

	IMPORT_C void DoAddDelta(TAny* aPtr,TInt aDelta);

	IMPORT_C void DoRemove(TAny* aPtr);

	IMPORT_C TAny* DoRemoveFirst();

protected:

	/**

	Pointer to the delta value in the first link element.

	*/

	TInt* iFirstDelta;

	};

/**

@publishedAll

@released

A templated class that provides the behaviour for managing a singly linked 

list.

It also acts as the head of the list, maintaining the pointers into the list.

The template parameter defines the type of element that forms the singly linked 

list and is the class that acts as host to the link object.

@see TSglQueLink

*/

template <class T>

class TSglQue : public TSglQueBase

	{

public:

	inline TSglQue();

	inline explicit TSglQue(TInt aOffset);

	inline void AddFirst(T& aRef);

	inline void AddLast(T& aRef);

	inline TBool IsFirst(const T* aPtr) const;

	inline TBool IsLast(const T* aPtr) const;

	inline T* First() const;

	inline T* Last() const;

	inline void Remove(T& aRef);

	};

/**

@publishedAll

@released

A templated class that provides the behaviour for managing a doubly linked 

list. 

It also acts as the head of the list, maintaining the pointers into the list.

The template parameter defines the type of element that forms the doubly linked 

list and is the class that acts as host to the link object.

@see TDblQueLink

*/

template <class T>

class TDblQue : public TDblQueBase

	{

public:

	inline TDblQue();

	inline explicit TDblQue(TInt aOffset);

	inline void AddFirst(T& aRef);

	inline void AddLast(T& aRef);

	inline TBool IsHead(const T* aPtr) const;

	inline TBool IsFirst(const T* aPtr) const;

	inline TBool IsLast(const T* aPtr) const;

	inline T* First() const;

	inline T* Last() const;

	};

/**

@publishedAll

@released

A templated class that provides the behaviour for managing a doubly linked

list in which the elements are added in descending priority order.

Priority is defined by the value of the TPriQueLink::iPriority member of

the link element.

The template parameter defines the type of element that forms the doubly linked

list and is the class that acts as host to the link object.

@see TPriQueLink

@see TPriQueLink::iPriority

*/

template <class T>

class TPriQue : public TDblQueBase

	{

public:

	inline TPriQue();

	inline explicit TPriQue(TInt aOffset);

	inline void Add(T& aRef);

	inline TBool IsHead(const T* aPtr) const;

	inline TBool IsFirst(const T* aPtr) const;

	inline TBool IsLast(const T* aPtr) const;

	inline T* First() const;

	inline T* Last() const;

	};

/**

@publishedAll

@released

A templated class that provides the behaviour for managing a doubly linked 

list in which elements represent values which are increments, or deltas, on 

the value represented by a preceding element.

The list is ordered so that the head of the queue represents a nominal zero 

point.

The delta value of a new element represents its 'distance' from the nominal 

zero point. The new element is added into the list, and the delta values of 

adjacent elements (and of the new element, if necessary) are adjusted, so 

that the sum of all deltas, up to and including the new element, is the same 

as the new element's intended 'distance' from the nominal zero point.

A common use for a list of this type is as a queue of timed events, where 

the delta values represent the intervals between the events.

The delta value is defined by the value of the TDeltaQueLink::iDelta member 

of the link element.

The template parameter defines the type of element that forms the doubly linked 

list and is the class that acts as host to the link object.

@see TDeltaQueLink

@see TDeltaQueLink::iDelta

*/

template <class T>

class TDeltaQue : public TDeltaQueBase

	{

public:

	inline TDeltaQue();

	inline explicit TDeltaQue(TInt aOffset);

	inline void Add(T& aRef,TInt aDelta);

	inline void Remove(T& aRef);

	inline T* RemoveFirst();

	};

// Forward declaration

class TTickCountQueLink;

/**

@internalComponent

@released

A class that provides the behaviour for managing a doubly linked list

in which elements are added in order of the time until their tick count.

A common use for a list of this type is as a queue of timed events, where 

the tick counts are the expiry times of the events.

The tick count is defined by the value of the TTickCountQueLink::iTickCount

member of the link element.

@see TTickCountQueLink

@see TTickCountQueLink::iTickCount

*/

class TTickCountQue : public TDblQueBase

	{

public:

	TTickCountQue();

	void Add(TTickCountQueLink& aRef);

	TTickCountQueLink* First() const;

	TTickCountQueLink* RemoveFirst();

	TTickCountQueLink* RemoveFirst(TUint aTickCount);

	};

/**

@publishedAll

@released

A base class that provides implementation for the singly linked list iterator. 

It also encapsulates a pointer to the current link link list element.

The class is abstract and is not intended to be instantiated.

*/

class TSglQueIterBase

	{

public:

	IMPORT_C void SetToFirst();

protected:

	IMPORT_C TSglQueIterBase(TSglQueBase& aQue);

	IMPORT_C TAny* DoPostInc();

	IMPORT_C TAny* DoCurrent();

	IMPORT_C void DoSet(TAny* aLink);

protected:

	TInt iOffset;

	TSglQueLink* iHead;

	TSglQueLink* iNext;

	};

/**

@publishedAll

@released

A templated class that provides the behaviour for iterating through a set of 

singly linked list elements.

The template parameter defines the type of element that forms the singly linked 

list. The class defined in the template parameter contains the link object.

*/

template <class T>

class TSglQueIter : public TSglQueIterBase

	{

public:

	inline TSglQueIter(TSglQueBase& aQue);

	inline void Set(T& aLink);

	inline operator T*();

	inline T* operator++(TInt);

	};

/**

@publishedAll

@released

A base class that provides implementation for the doubly linked list iterator.

It also encapsulates a pointer to the current link list element.

The class is abstract and is not intended to be instantiated.

*/

class TDblQueIterBase

	{

public:

	IMPORT_C void SetToFirst();

	IMPORT_C void SetToLast();

protected:

	IMPORT_C TDblQueIterBase(TDblQueBase& aQue);

	IMPORT_C TAny* DoPostInc();

	IMPORT_C TAny* DoPostDec();

	IMPORT_C TAny* DoCurrent();

	IMPORT_C void DoSet(TAny* aLink);

protected:

	/**

	The offset of a component link object within elements that form the list.

	*/

	TInt iOffset;

	/**

	Pointer to the anchor for the list.

	*/

	TDblQueLinkBase* iHead;

	/**

	Pointer to the current element.

	*/

	TDblQueLinkBase* iNext;

	};

/**

@publishedAll

@released

A templated class that provides the behaviour for iterating through a set of 

doubly linked list elements.

The template parameter defines the type of element that forms the doubly linked 

list. The class defined in the template parameter contains the link object.

*/

template <class T>

class TDblQueIter : public TDblQueIterBase

	{

public:

	inline TDblQueIter(TDblQueBase& aQue);

	inline void Set(T& aLink);

	inline operator T*();

	inline T* operator++(TInt);

	inline T* operator--(TInt);

	};

/**

@publishedAll

@released

Governs the type of comparison to be made between descriptor keys or between 

text keys.

@see TKeyArrayFix

@see TKeyArrayVar

@see TKeyArrayPak

*/

enum TKeyCmpText

	{

	/**

	For a Unicode build, this is the same as ECmpNormal16.

	For a non-Unicode build, this is the same as ECmpNormal8.

	Using the build independent names (i.e. TPtrC, TPtr, TBufC, TBuf or TText) 

	allows the compiler to chose the correct variant according to the build.

	*/

	ECmpNormal,

	/**

	For descriptor keys, the key is assumed to be the 8 bit variant, derived

	from TDesc8. A simple comparison is done between the content of the

	descriptors; the data is not folded and collation rules are not applied for

	the purpose of the comparison.

	For text keys, the key is assumed to be the 8 bit variant, of type TText8. 

	A normal comparison is done between the text data; the data is not folded 

	and collation rules are not applied for the purpose of the comparison.

	*/

	ECmpNormal8,

	/**

	For descriptor keys, the key is assumed to be the 16 bit variant, derived

	from TDesc16. A simple comparison is done between the content of the

	descriptors; the data is not folded and collation rules are not applied for

	the purpose of the comparison.

	For text keys, the key is assumed to be the 16 bit variant, of type

	TText16. A normal comparison is done between the text data; the data is

	not folded 	and collation rules are not applied for the purpose of the

	comparison.

	*/

	ECmpNormal16,

	/**

	For a Unicode build, this is the same as EcmpFolded16.

    For a non-Unicode build, this is the same as EcmpFolded8.

    Using the build independent names (i.e. TPtrC, TPtr, TBufC, TBuf or TText)

    allows the compiler to chose the correct variant according to the build. 

	*/

	ECmpFolded,

	/**

	For descriptor keys, the key is assumed to be the 8 bit variant,

	derived from TDesc8. The descriptor contents are folded for the purpose

	of the comparison.

    For text keys, the key is assumed to be the 8 bit variant, of type

    TText8. The text data is folded for the purpose of the comparison.

	*/

	ECmpFolded8,

	/**

	For descriptor keys, the key is assumed to be the 16 bit variant,

	derived from TDesc16. The descriptor contents are folded for the purpose

	of the comparison.

    For text keys, the key is assumed to be the 16 bit variant, of type

    TText16. The text data is folded for the purpose of the comparison.

	*/

	ECmpFolded16,

	/**

	For a Unicode build, this is the same as EcmpCollated16.

    For a non-Unicode build, this is the same as EcmpCollated8.

    Using the build independent names (i.e. TPtrC, TPtr, TBufC, TBuf or TText)

    allows the compiler to chose the correct variant according to the build.

	*/

	ECmpCollated,

	/**

	For descriptor keys, the key is assumed to be the 8 bit variant,

	derived from TDesc8. Collation rules are applied for the purpose of

	the comparison.

    For text keys, the key is assumed to be the 8 bit variant, of type 

    TText8. Collation rules are applied for the purpose of the comparison.

	*/

	ECmpCollated8,

	/**

	For descriptor keys, the key is assumed to be the 16 bit variant,

	derived from TDesc16. Collation rules are applied for the purpose of

	the comparison.

    For text keys, the key is assumed to be the 16 bit variant,

    of type TText16. Collation rules are applied for the purpose of

    the comparison.

	*/

	ECmpCollated16

	};

/**

@publishedAll

@released

Governs the type of comparison to be made between numeric keys.

@see TKeyArrayFix

@see TKeyArrayVar

@see TKeyArrayPak

*/

enum TKeyCmpNumeric

	{

	/**

	The key is assumed to be of type TInt8.

	*/

	ECmpTInt8=((ECmpCollated16+1)<<1),

	/**

	The key is assumed to be of type TInt16.

	*/

	ECmpTInt16,

	/**

	The key is assumed to be of type TInt32.

	*/

	ECmpTInt32,

	/**

	The key is assumed to be of type TInt.

	*/

	ECmpTInt,

	/**

	The key is assumed to be of type TUint8.

	*/

	ECmpTUint8,

	/**

	The key is assumed to be of type TUint16.

	*/

	ECmpTUint16,

	/**

	The key is assumed to be of type TUint32.

	*/

	ECmpTUint32,

	/**

	The key is assumed to be of type TUint.

	*/

	ECmpTUint,

	/**

	The key is assumed to be of type TInt64.

	*/

	ECmpTInt64

	};

/**

@publishedAll

@released

Defines the characteristics of a key used to access the elements of an array.

The class is abstract and cannot be instantiated. A derived class must be 

defined and implemented.

The classes TKeyArrayFix, TKeyArrayVar and TKeyArrayPak, derived from TKey, 

are already supplied to implement keys for the fixed length element, variable 

length element and packed arrays.

A derived class would normally be written to define the characteristics of 

a key for a non standard array.

@see TKeyArrayFix

@see TKeyArrayVar

@see TKeyArrayPak

*/

class TKey

	{

public:

	inline void SetPtr(const TAny* aPtr);

	IMPORT_C virtual TInt Compare(TInt aLeft,TInt aRight) const;

	IMPORT_C virtual TAny* At(TInt anIndex) const;

protected:

	IMPORT_C TKey();

	IMPORT_C TKey(TInt aOffset,TKeyCmpText aType);

	IMPORT_C TKey(TInt aOffset,TKeyCmpText aType,TInt aLength);

	IMPORT_C TKey(TInt aOffset,TKeyCmpNumeric aType);

protected:

	TInt iKeyOffset;

	TInt iKeyLength;

	TInt iCmpType;

	const TAny* iPtr;

	};

/**

@publishedAll

@released

Defines the basic behaviour for swapping two elements of an array.

The class is abstract. A derived class must be defined and implemented to 

use the functionality.

A derived class can define how to swap two elements of an array. In practice, 

this means providing an implementation for the virtual function Swap().

To support this, the derived class is also likely to need a pointer to the 

array itself and suitable constructors and/or other member functions to set 

such a pointer.

*/

class TSwap

	{

public:

	IMPORT_C TSwap();

	IMPORT_C virtual void Swap(TInt aLeft,TInt aRight) const;

	};

/**

@publishedAll

@released

Folds a specified character and provides functions to fold additional

characters after construction of the object.

Folding 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. 

Note that folding is locale-independent behaviour. It is also important to 

note that there can be no guarantee that folding is in any way culturally 

appropriate, and should not be used for matching characters in

natural language.

@see User::Fold

*/

class TCharF : public TChar

	{

public:

	inline TCharF(TUint aChar);

	inline TCharF(const TChar& aChar);

	inline TCharF& operator=(TUint aChar);

	inline TCharF& operator=(const TChar& aChar);

	};

/**

@publishedAll

@released

Converts a specified character to lower case and provides functions to convert 

additional characters after construction of the object.

*/

class TCharLC : public TChar

	{

public:

	inline TCharLC(TUint aChar);

	inline TCharLC(const TChar& aChar);

	inline TCharLC& operator=(TUint aChar);

	inline TCharLC& operator=(const TChar& aChar);

	};

/**

@publishedAll

@released

Converts a specified character to upper case and provides functions to convert 

additional characters after construction of the object.

*/

class TCharUC : public TChar

	{

public:

	inline TCharUC(TUint aChar);

	inline TCharUC(const TChar& aChar);

	inline TCharUC& operator=(TUint aChar);

	inline TCharUC& operator=(const TChar& aChar);

	};

/**

@publishedAll

@released

Defines the character representation of a real number type such

as a TReal or a TRealX.

An object of this type is used by functions that convert real values to

character format, for example, the descriptor functions:

Num(), AppendNum() and Format().

There are three constructors for constructing a suitable object.

The data members of the class, however, are public and can be

explicitly set after construction.

*/