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

// which accompanies this distribution, and is available

// at the URL "http://www.symbianfoundation.org/legal/sfl-v10.html".

//

// Initial Contributors:

// Nokia Corporation - initial contribution.

//

// Contributors:

//

// Description:

// e32\include\e32base.h

// 

//

#ifndef __E32BASE_H__

#define __E32BASE_H__

#include <e32std.h>

/**

 * Container Base Class

 */

class CBase

/**

@publishedAll

@released

Base class for all classes to be instantiated on the heap.

By convention, all classes derived from CBase have a name beginning with the 

letter 'C'.

The class has two important features:

1. A virtual destructor that allows instances of derived classes to be destroyed 

   and properly cleaned up through a CBase* pointer. All CBase derived objects 

   can be pushed, as CBase* pointers, onto the cleanup stack, and destroyed through 

   a call to CleanupStack::PopAndDestroy().

2. Initialisation of the CBase derived object to binary zeroes through a specific 

   CBase::operator new() - this means that members, whose initial value should 

   be zero, do not have to be initialised in the constructor. This allows safe 

   destruction of a partially-constructed object.

Note that using C++ arrays of CBase-derived types is not recommended, as objects 

in the array will not be zero-initialised (as there is no operator new[] member). 

You should use an array class such as RPointerArray instead for arrays of 

CBase-derived types.

@see CleanupStack

*/

	{

public:

	/**

	Default constructor

	*/

	inline CBase()	{}

	IMPORT_C virtual ~CBase();

	inline TAny* operator new(TUint aSize, TAny* aBase) __NO_THROW;

	inline TAny* operator new(TUint aSize) __NO_THROW;

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

	inline TAny* operator new(TUint aSize, TUint aExtraSize) __NO_THROW;

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

	IMPORT_C static void Delete(CBase* aPtr);

protected:

	IMPORT_C virtual TInt Extension_(TUint aExtensionId, TAny*& a0, TAny* a1);

private:

	CBase(const CBase&);

	CBase& operator=(const CBase&);

private:

	};

class CBufBase : public CBase

/**

@publishedAll

@released

Defines the interface for dynamic buffers. 

The basic functions, InsertL(), Read(), Write(), Delete(), Reset() and Size(), 

transfer data between the buffer and other places, and allow that data to 

be deleted

The ExpandL() and Resize() functions allow some operations to be carried out 

with greater efficiency

A Compress() function frees (back to the heap) any space which may have been 

allocated, but not used

Ptr() and BackPtr() allow look-up of contiguous data from any given position, 

forward or backward

*/

	{

public:

	IMPORT_C ~CBufBase();

	inline TInt Size() const;

	IMPORT_C void Reset();

	IMPORT_C void Read(TInt aPos,TDes8& aDes) const;

	IMPORT_C void Read(TInt aPos,TDes8& aDes,TInt aLength) const;

	IMPORT_C void Read(TInt aPos,TAny* aPtr,TInt aLength) const;

	IMPORT_C void Write(TInt aPos,const TDesC8& aDes);

	IMPORT_C void Write(TInt aPos,const TDesC8& aDes,TInt aLength);

	IMPORT_C void Write(TInt aPos,const TAny* aPtr,TInt aLength);

	IMPORT_C void InsertL(TInt aPos,const TDesC8& aDes);

	IMPORT_C void InsertL(TInt aPos,const TDesC8& aDes,TInt aLength);

	IMPORT_C void InsertL(TInt aPos,const TAny* aPtr,TInt aLength);

	IMPORT_C void ExpandL(TInt aPos,TInt aLength);

	IMPORT_C void ResizeL(TInt aSize);

// Pure virtual

	/**

	Compresses the buffer so as to occupy minimal space.

	Normally, you would call this when a buffer has reached its final size,

	or when you know it will not expand again for a while, or when an

	out-of-memory error has occurred and your program is taking measures to

	save space. Compression in these circumstances releases memory for other

	programs to use, but has no adverse effect on performance.

	Derived classes provide the implementation.

	@see CBufFlat::Compress

	@see CBufSeg::Compress

	*/

    virtual void Compress()=0;

	/**

	Deletes data from the buffer.

	Derived classes provide the implementation.

	@param aPos    Buffer position where the deletion will begin; must be in the 

                   range zero to (Size() minus the length of the data

                   to be deleted). 

	@param aLength The number of bytes to be deleted; must be non-negative.

	@see CBufFlat::Delete

	@see CBufSeg::Delete

	*/

	virtual void Delete(TInt aPos,TInt aLength)=0;

	/**

	Gets a pointer descriptor to represent the data from the specified position to  

	the end of the contiguous region containing that byte.

	Derived classes provide the implementation.

	@param aPos Buffer position: must be in range zero to Size().

	@return Descriptor representing the data starting at aPos, and whose length

	        indicates the number of contiguous bytes stored in the buffer, 

            forward from that point. The length will be non-zero unless aPos==Size().

	@see CBufFlat::Ptr

	@see CBufSeg::Ptr

	*/

	virtual TPtr8 Ptr(TInt aPos)=0;

	/**

	Gets a pointer descriptor to represent data from just before the specified 

	data byte backward to the beginning of the contiguous region containing 

	that byte.

	Derived classes provide the implementation.

	@param aPos Buffer position: must be in range zero to Size().

	@return Descriptor representing the back contiguous region. 

	        The address in the descriptor is the pointer to the bytes at the

	        buffer position, unless the buffer position was at the beginning of

	        a non-first segment in the buffer: in this case, the address is a

	        pointer just beyond the last data byte in the previous segment.

	        The length is the number of contiguous bytes from the address

	        backwards to the beginning of the segment.

	@see CBufFlat::BackPtr

	@see CBufSeg::BackPtr

	*/

	virtual TPtr8 BackPtr(TInt aPos)=0;

private:

	virtual void DoInsertL(TInt aPos,const TAny* aPtr,TInt aLength)=0;

protected:

	IMPORT_C CBufBase(TInt anExpandSize);

protected:

	TInt iSize;

	TInt iExpandSize;

	};

class CBufFlat : public CBufBase

/**

@publishedAll

@released

Provides a flat storage dynamic buffer.

This class should be used when high-speed pointer lookup is an important

consideration, and you are reasonably confident that the insertion of

data will not fail. 

This class is an implementation of the abstract buffer interface provided 

by CBufBase and uses a single heap cell to contain the data.

*/

	{

public:

	IMPORT_C ~CBufFlat();

	IMPORT_C static CBufFlat* NewL(TInt anExpandSize);

	inline TInt Capacity() const;

	IMPORT_C void SetReserveL(TInt aSize);

	IMPORT_C void Compress();

	IMPORT_C void Delete(TInt aPos,TInt aLength);

	IMPORT_C TPtr8 Ptr(TInt aPos);

	IMPORT_C TPtr8 BackPtr(TInt aPos);

protected:

	IMPORT_C CBufFlat(TInt anExpandSize);

private:

	IMPORT_C void DoInsertL(TInt aPos,const TAny* aPtr,TInt aLength);

private:

	TInt iMaxSize;

	TUint8* iPtr;

	};

class TBufSegLink;

class CBufSeg : public CBufBase

/**

@publishedAll

@released

Provides a segmented dynamic buffer.

This class should be used when the object has a long life-time and an

unpredictable number of insertions, or there is concern about the performance

of insertion and deletion operations into large buffers.

This class is an implementation of the abstract buffer interface provided 

by CBufBase and uses doubly-linked list of heap cells to contain the data; 

each cell containing a segment of the buffer.

Its (private) data members include an anchor for the doubly-linked list, and also a 

reference to the buffer position used by the last operation. This reference 

acts as a cache; if the next operation uses a similar buffer position, then 

calculation of the pointer corresponding to its buffer position is much faster.

*/

	{

public:

	IMPORT_C ~CBufSeg();

	IMPORT_C static CBufSeg* NewL(TInt anExpandSize);

    IMPORT_C void Compress();

	IMPORT_C void Delete(TInt aPos,TInt aLength);

	IMPORT_C TPtr8 Ptr(TInt aPos);

	IMPORT_C TPtr8 BackPtr(TInt aPos);

protected:

	IMPORT_C CBufSeg(TInt anExpandSize);

	void InsertIntoSegment(TBufSegLink* aSeg,TInt anOffset,const TAny* aPtr,TInt aLength);

	void DeleteFromSegment(TBufSegLink* aSeg,TInt anOffset,TInt aLength);

	void FreeSegment(TBufSegLink* aSeg);

    void SetSBO(TInt aPos);

	void AllocSegL(TBufSegLink* aSeg,TInt aNumber);

private:

	IMPORT_C void DoInsertL(TInt aPos,const TAny* aPtr,TInt aLength);

private:

    TDblQue<TBufSegLink> iQue;

	TBufSegLink* iSeg;

	TInt iBase;

	TInt iOffset;

	};

class TKeyArrayFix : public TKey

/**

@publishedAll

@released

Defines the characteristics of a key used to access the elements of arrays 

of fixed length objects.

An object of this type can represent three categories of key, depending on 

the constructor used:

1. a descriptor key 

2. a text key

3. a numeric key.

The Sort(), InsertIsqL(), Find() and FindIsqL() member functions of the CArrayFixFlat 

and CArrayFixSeg class hierarchies need a TKeyArrayFix object as an argument 

to define the location and type of key within an array element.

@see CArrayFixFlat

@see CArrayFixSeg

*/

	{

public:

	IMPORT_C TKeyArrayFix(TInt anOffset,TKeyCmpText aType);

	IMPORT_C TKeyArrayFix(TInt anOffset,TKeyCmpText aType,TInt aLength);

	IMPORT_C TKeyArrayFix(TInt anOffset,TKeyCmpNumeric aType);

protected:

	IMPORT_C virtual void Set(CBufBase* aBase,TInt aRecordLength);

	IMPORT_C TAny* At(TInt anIndex) const;

protected:

	TInt iRecordLength;

	CBufBase* iBase;

	friend class CArrayFixBase;

	};

typedef CBufBase*(*TBufRep)(TInt anExpandSize);

class CArrayFixBase : public CBase

/**

@publishedAll

@released

Base class for arrays of fixed length objects.

It provides implementation and public functions which are common to all arrays

of this type.

The class is always derived from and is never instantiated explicitly.

*/

	{

public:

	IMPORT_C ~CArrayFixBase();

	inline TInt Count() const;

	inline TInt Length() const;

	IMPORT_C void Compress();

	IMPORT_C void Reset();

	IMPORT_C TInt Sort(TKeyArrayFix& aKey);

	IMPORT_C TAny* At(TInt anIndex) const;

	IMPORT_C TAny* End(TInt anIndex) const;

	IMPORT_C TAny* Back(TInt anIndex) const;

	IMPORT_C void Delete(TInt anIndex);

	IMPORT_C void Delete(TInt anIndex,TInt aCount);

	IMPORT_C TAny* ExpandL(TInt anIndex);

	IMPORT_C TInt Find(const TAny* aPtr,TKeyArrayFix& aKey,TInt& anIndex) const;

	IMPORT_C TInt FindIsq(const TAny* aPtr,TKeyArrayFix& aKey,TInt& anIndex) const;

	IMPORT_C void InsertL(TInt anIndex,const TAny* aPtr);

	IMPORT_C void InsertL(TInt anIndex,const TAny* aPtr,TInt aCount);

	IMPORT_C TInt InsertIsqL(const TAny* aPtr,TKeyArrayFix& aKey);

	IMPORT_C TInt InsertIsqAllowDuplicatesL(const TAny* aPtr,TKeyArrayFix& aKey);

	IMPORT_C void ResizeL(TInt aCount,const TAny* aPtr);

protected:

	IMPORT_C CArrayFixBase(TBufRep aRep,TInt aRecordLength,TInt aGranularity);

	IMPORT_C void InsertRepL(TInt anIndex,const TAny* aPtr,TInt aReplicas);

	IMPORT_C void SetKey(TKeyArrayFix& aKey) const;

	IMPORT_C void SetReserveFlatL(TInt aCount);

	IMPORT_C static TInt CountR(const CBase* aPtr);

	IMPORT_C static const TAny* AtR(const CBase* aPtr,TInt anIndex);

private:

	TInt iCount;

	TInt iGranularity;

	TInt iLength;

	TBufRep iCreateRep;

	CBufBase* iBase;

	};

template <class T>

class CArrayFix : public CArrayFixBase

/**

@publishedAll

@released

A thin templated base class for arrays of fixed length objects. 

The public functions provide standard array behaviour.

The class is always derived from and is never instantiated explicitly.

*/

	{

public:

	inline CArrayFix(TBufRep aRep,TInt aGranularity);

	inline const T& operator[](TInt anIndex) const;

	inline T& operator[](TInt anIndex);

	inline const T& At(TInt anIndex) const;

	inline const T* End(TInt anIndex) const;

	inline const T* Back(TInt anIndex) const;

	inline T& At(TInt anIndex);

	inline T* End(TInt anIndex);

	inline T* Back(TInt anIndex);

	inline void AppendL(const T& aRef);

	inline void AppendL(const T* aPtr,TInt aCount);

	inline void AppendL(const T& aRef,TInt aReplicas);

	inline T& ExpandL(TInt anIndex);

	inline T& ExtendL();

	inline TInt Find(const T& aRef,TKeyArrayFix& aKey,TInt& anIndex) const;

	inline TInt FindIsq(const T& aRef,TKeyArrayFix& aKey,TInt& anIndex) const;

	inline void InsertL(TInt anIndex,const T& aRef);

	inline void InsertL(TInt anIndex,const T* aPtr,TInt aCount);

	inline void InsertL(TInt anIndex,const T& aRef,TInt aReplicas);

	inline TInt InsertIsqL(const T& aRef,TKeyArrayFix& aKey);

	inline TInt InsertIsqAllowDuplicatesL(const T& aRef,TKeyArrayFix& aKey);

	inline void ResizeL(TInt aCount);

	inline void ResizeL(TInt aCount,const T& aRef);

	inline const TArray<T> Array() const;

	};

TEMPLATE_SPECIALIZATION class CArrayFix<TAny> : public CArrayFixBase

/**

@publishedAll

@released

A template specialisation base class for arrays of fixed length

untyped objects.

The public functions provide standard array behaviour.

The class is always derived from and is never instantiated explicitly.

*/

	{

public:

	inline CArrayFix(TBufRep aRep,TInt aRecordLength,TInt aGranularity);

	inline const TAny* At(TInt anIndex) const;

	inline const TAny* End(TInt anIndex) const;

	inline const TAny* Back(TInt anIndex) const;

	inline TAny* At(TInt anIndex);

	inline TAny* End(TInt anIndex);

	inline TAny* Back(TInt anIndex);

	inline void AppendL(const TAny* aPtr);

	inline void AppendL(const TAny* aPtr,TInt aCount);

	inline TAny* ExtendL();

	};

template <class T>

class CArrayFixFlat : public CArrayFix<T>

/**

@publishedAll

@released

Array of fixed length objects contained within a flat dynamic buffer.

The elements of the array are instances of the template class T.

The flat dynamic buffer is an instance of a CBufFlat.

The elements can be T or R type objects and must have an accessible default 

constructor.

Note that, where possible, use the RArray<class T> class as this is more

efficient.

@see CBufFlat

@see RArray

*/

	{

public:

	inline explicit CArrayFixFlat(TInt aGranularity);

	inline void SetReserveL(TInt aCount);

	};

TEMPLATE_SPECIALIZATION class CArrayFixFlat<TAny> : public CArrayFix<TAny>

/**

@publishedAll

@released

An array of fixed length untyped objects using a flat dynamic buffer.

The array elements are contained within a CBufFlat.

The class is useful for constructing an array of fixed length buffers, where 

the length is decided at run time.

This class is also useful as a data member of a base class in a thin template 

class/base class pair where the type of the array element is not known until 

the owning thin template class is instantiated.

@see CBufFlat

*/

	{

public:

	inline CArrayFixFlat(TInt aRecordLength,TInt aGranularity);

	inline void SetReserveL(TInt aCount);

	};

TEMPLATE_SPECIALIZATION class CArrayFixFlat<TInt> : public CArrayFix<TInt>

/**

@publishedAll

@released

Template specialisation base class for arrays of TInt types implemented in a 

flat dynamic buffer.

@see TInt 

*/

	{

public:

	IMPORT_C explicit CArrayFixFlat(TInt aGranularity);

	IMPORT_C ~CArrayFixFlat();

	inline void SetReserveL(TInt aCount);

	};

TEMPLATE_SPECIALIZATION class CArrayFixFlat<TUid> : public CArrayFix<TUid>

/**

@publishedAll

@released

Template specialisation base class for arrays of TUid types implemented in a 

flat dynamic buffer.

@see TUid