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