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

// All rights reserved.

// This component and the accompanying materials are made available

// which accompanies this distribution, and is available

//

// Initial Contributors:

// Nokia Corporation - initial contribution.

//

// Contributors:

//

// Description:

// e32\include\e32base.inl

// 

//

// Class CBase

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

/**

Initialises the object to binary zeroes.

@param aSize The size of the derived class. This parameter is specified

             implicitly by C++ in all circumstances in which a derived

			 class is allocated.

@param aBase Indicates a base address which is returned as the object's

             address. 

@return A pointer to the base address.

*/

	{ Mem::FillZ(aBase, aSize); return aBase; }

inline TAny* CBase::operator new(TUint aSize) __NO_THROW

/**

Allocates the object from the heap and then initialises its contents

to binary zeroes.

@param aSize The size of the derived class. This parameter is specified

             implicitly by C++ in all circumstances in which a derived class

			 is allocated.

@return      A pointer to the allocated object; NULL if memory could not

             be allocated.

*/

	{ return User::AllocZ(aSize); }

inline TAny* CBase::operator new(TUint aSize, TLeave)

/**

Allocates the object from the heap and then initialises its contents

to binary zeroes.

@param aSize  The size of the derived class. This parameter is specified

              implicitly by C++ in all circumstances in which a derived class

			  is allocated.

@return       A pointer to the allocated object; the TLeave parameter indicates

              that the operation leaves if allocation fails with out-of-memory.

*/

	{ return User::AllocZL(aSize); }

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

/**

Allocates the object from the heap and then initialises its contents

to binary zeroes.

Use of this overload is rare.

@param aSize  The size of the derived class. This parameter is specified

              implicitly by C++ in all circumstances in which a derived class

			  is allocated.

@param aExtraSize Indicates additional size beyond the end of the base class.

@return      A pointer to the allocated object; NULL if memory could not

             be allocated.

*/

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

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

/**

Allocates the object from the heap and then initialises its contents

to binary zeroes.

Use of this overload is rare.

@param aSize  The size of the derived class. This parameter is specified

              implicitly by C++ in all circumstances in which a derived class

			  is allocated.

@param aExtraSize Indicates additional size beyond the end of the base class.

@return      A pointer to the allocated object; the TLeave parameter indicates

              that the operation leaves if allocation fails with out-of-memory.

*/

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

// Class CBufBase

inline TInt CBufBase::Size() const

/**

Gets the number of data bytes in the buffer.

Note that the number of heap bytes used by the buffer may be greater than its

size, because there is typically extra room to allow for expansion. Use the

Compress() function to reduce the extra allocation as much as possible.

@return The number of data bytes in the buffer.

*/

	{return(iSize);}

// Class CBufFlat

inline TInt CBufFlat::Capacity() const

/**

Gets the size to which the buffer may expand without re-allocation.

@return The size of the allocated cell associated with the buffer. This is 

        the maximum size the buffer may be expanded to without re-allocation.

*/

	{return(iMaxSize);}

// Class CArrayFixBase

inline TInt CArrayFixBase::Count() const

/**

Gets the number of elements held in the array.

@return The number of array elements

*/

	{return(iCount);}

inline TInt CArrayFixBase::Length() const

/**

Gets the length of an element.

@return The length of an element of type class T.

*/

	{return(iLength);}

// Template class CArrayFix

template <class T>

inline CArrayFix<T>::CArrayFix(TBufRep aRep,TInt aGranularity)

	: CArrayFixBase(aRep,sizeof(T),aGranularity)

/**

@internalComponent

*/

	{}

template <class T>

inline const T &CArrayFix<T>::operator[](TInt anIndex) const

/**

Gets a const reference to the element located at the specified position 

within the array.

Note that if a pointer to the returned referenced class T object is taken,

be aware that the pointer value becomes invalid once elements have been added

to, or removed from the array. Always refresh the pointer.

@param anIndex The position of the element within the array. The position 

               is relative to zero; i.e. zero implies the first element in

			   the array.

@return A const reference to the required element.

@panic E32USER-CBase 21, if anIndex is negative or greater than or equal to the

                         number of objects currently within the array.

*/

	{return(*((const T *)CArrayFixBase::At(anIndex)));}

template <class T>

inline T &CArrayFix<T>::operator[](TInt anIndex)

/**

Gets a non-const reference to the element located at the specified position 

within the array.

Note that if a pointer to the returned referenced class T object is taken,

be aware that the pointer value becomes invalid once elements have been added

to, or removed from the array. Always refresh the pointer.

@param anIndex The position of the element within the array. The position 

               is relative to zero; i.e. zero implies the first element in

			   the array.

@return A non-const reference to the required element.

@panic E32USER-CBase 21, if anIndex is negative or greater than or equal to the

                         number of objects currently within the array.

*/

	{return(*((T *)CArrayFixBase::At(anIndex)));}

template <class T>

inline const T &CArrayFix<T>::At(TInt anIndex) const

/** 

Gets a const reference to the element located at the specified position 

within the array.

Note that if a pointer to the returned referenced class T object is taken,

be aware that the pointer value becomes invalid once elements have been added

to, or removed from the array. Always refresh the pointer.

@param anIndex The position of the element within the array. The position 

               is relative to zero; i.e. zero implies the first element in

			   the array.

@return A const reference to the required element.

@panic E32USER-CBase 21, if anIndex is negative or greater than or equal to the

                         number of objects currently within the array.

*/

	{return(*((const T *)CArrayFixBase::At(anIndex)));}

template <class T>

inline const T *CArrayFix<T>::End(TInt anIndex) const

/**

Gets a pointer to the (const) first byte following the end of the 

contiguous region containing the element at the specified position within

the array.

For arrays implemented using flat buffers, the pointer always points to the 

first byte following the end of the buffer.

For arrays implemented using segmented buffers, the pointer always points 

to the first byte following the end of the segment which contains the element.

@param anIndex The position of the element within the array. The position 

               is relative to zero; i.e. zero implies the first element

			   in the array.

@return A pointer to the constant byte following the end of the contiguous 

        region. 

@panic E32USER-CBase 21, if anIndex is negative or greater than or equal to the

                         number of objects currently within the array.

*/

	{return((const T *)CArrayFixBase::End(anIndex));}

template <class T>

inline const T *CArrayFix<T>::Back(TInt anIndex) const

/**

Gets a pointer to the (const) beginning of a contiguous region.

For arrays implemented using flat buffers, the function always returns a

pointer to the beginning of the buffer.

For arrays implemented using segmented buffers, the function returns a pointer 

to the beginning of the segment for all elements in that segment except the 

first. If the element at position anIndex is the first in a segment, then 

the function returns a pointer the beginning of the previous segment.

For the first element in the array, the function returns a NULL pointer.

@param anIndex The position of the element within the array. The position 

               is relative to zero; i.e. zero implies the first element

			   in the array.

@return A pointer to the (const) beginning of the contiguous region.

@panic E32USER-CBase 21, if anIndex is negative or greater than or equal to the

                         number of objects currently within the array.

*/

	{return((const T *)CArrayFixBase::Back(anIndex));}

template <class T>

inline T &CArrayFix<T>::At(TInt anIndex)

/**

Gets a non-const reference to the element located at the specified position 

within the array.

Note that if a pointer to the returned referenced class T object is taken,

be aware that the pointer value becomes invalid once elements have been added

to, or removed from the array. Always refresh the pointer.

@param anIndex The position of the element within the array. The position 

               is relative to zero; i.e. zero implies the first element in

			   the array.

@return A non-const reference to the required element.

@panic E32USER-CBase 21, if anIndex is negative or greater than or equal to the

                         number of objects currently within the array.

*/

	{return(*((T *)CArrayFixBase::At(anIndex)));}

template <class T>

inline T *CArrayFix<T>::End(TInt anIndex)

/**

Gets a pointer to the first byte following the end of the contiguous region 

containing the element at the specified position within the array.

For arrays implemented using flat buffers, the pointer always points to the 

first byte following the end of the buffer.

For arrays implemented using segmented buffers, the pointer always points 

to the first byte following the end of the segment which contains the element.

@param anIndex The position of the element within the array. The position 

               is relative to zero; i.e. zero implies the first element

			   in the array.

@return A pointer to the byte following the end of the contiguous region.

@panic E32USER-CBase 21, if anIndex is negative or greater than or equal to the

                         number of objects currently within the array.

*/

	{return(((T *)CArrayFixBase::End(anIndex)));}

template <class T>

inline T *CArrayFix<T>::Back(TInt anIndex)

/**

Gets a pointer to the beginning of a contiguous region.

For arrays implemented using flat buffers, the function always returns a pointer 

to the beginning of the buffer.

For arrays implemented using segmented buffers, the function returns a pointer 

to the beginning of the segment for all elements in that segment except the 

first. If the element at position anIndex is the first in a segment, then 

the function returns a pointer the beginning of the previous segment.

For the first element in the array, the function returns a NULL pointer.

@param anIndex The position of the element within the array. The position 

               is relative to zero; i.e. zero implies the first element

			   in the array.

@return A pointer to the beginning of the contiguous region.

@panic E32USER-CBase 21, if anIndex is negative or greater than or equal to the

                         number of objects currently within the array.

*/

	{return(((T *)CArrayFixBase::Back(anIndex)));}

template <class T>

inline void CArrayFix<T>::AppendL(const T &aRef)

/**

Appends a single element onto the end of the array.

@param aRef A reference to the class T element to be appended.

@leave KErrNoMemory The function may attempt to expand the array buffer. If 

       there is insufficient memory available, the function leaves, in which

	   case the array is left in the state it was in before the call.

*/

	{CArrayFixBase::InsertL(Count(),&aRef);}

template <class T>

inline void CArrayFix<T>::AppendL(const T *aPtr,TInt aCount)

/**

Appends one or more elements onto the end of the array.

@param aPtr   A pointer to a contiguous set of type <class T> objects to be

              appended.

@param aCount The number of contiguous objects of type <class T> located at 

              aPtr to be appended.

@leave KErrNoMemory The function may attempt to expand the array buffer. If 

       there is insufficient memory available, the function leaves, in which

	   case the array is left in the state it was in before the call.

@panic E32USER-CBase 23, if aCount is negative.

*/

	{CArrayFixBase::InsertL(Count(),aPtr,aCount);}

template <class T>

inline void CArrayFix<T>::AppendL(const T &aRef,TInt aReplicas)

/**

Appends replicated copies of an element onto the end of the array.

@param aRef      A reference to the <class T> object to be replicated and appended.

@param aReplicas The number of copies of the aRef element to be appended. 

@leave KErrNoMemory The function may attempt to expand the array buffer. If 

       there is insufficient memory available, the function leaves, in which

	   case the array is left in the state it was in before the call.

@panic E32USER-CBase 28 if aReplicas is negative.

*/

	{CArrayFixBase::InsertRepL(Count(),&aRef,aReplicas);}

template <class T>

inline T &CArrayFix<T>::ExpandL(TInt anIndex)

/**

Expands the array by one element at the specified position.

It:

1. expands the array by one element at the specified position

2. constructs a new element at that position

3. returns a reference to the new element.

All existing elements from position anIndex to the end of the array are moved 

up, so that the element originally at position anIndex is now at position 

anIndex + 1 etc.

The new element of type class T is constructed at position anIndex, using 

the default constructor of that class.

@param anIndex The position within the array where the array is to be expanded 

               and the new class T object is to be constructed. 

@leave KErrNoMemory The function may attempt to expand the array buffer. If 

       there is insufficient memory available, the function leaves, in which

	   case the array is left in the state it was in before the call.

@return A reference to the newly constructed class T object at position 

        anIndex within the array.

@panic E32USER-CBase 21 if anIndex is negative or greater than the number

                        of elements currently in the array.

*/

	{return(*new(CArrayFixBase::ExpandL(anIndex)) T);}

template <class T>

inline T &CArrayFix<T>::ExtendL()

/**

Expands the array by one element at the end of the array.

It:

1. expands the array by one element at the end of the array, i.e. at position 

   CArrayFixBase::Count()

2. constructs a new element at that position

3. returns a reference to the new element.

The new element of type class T is constructed at the end of the array, 

using the default constructor of that class.

@leave KErrNoMemory The function may attempt to expand the array buffer. If 

       there is insufficient memory available, the function leaves, in which

	   case the array is left in the state it was in before the call.

@return A reference to the newly constructed class T object at the end of 

        the array.

@see CArrayFixBase::Count

*/

	{return(*new(CArrayFixBase::ExpandL(Count())) T);}

template <class T>

inline TInt CArrayFix<T>::Find(const T &aRef,TKeyArrayFix &aKey,TInt &anIndex) const

/**

Finds the position of an element within the array, based on the matching of

keys, using a sequential search.

The array is searched sequentially for an element whose key matches the key of the

supplied class T object. The search starts with the first element in the array.

Note that where an array has elements with duplicate keys, the function only

supplies the position of the first element in the array with that key.

@param aRef    A reference to an object of type class T whose key is used

               for comparison.

@param aKey    A reference to a key object defining the properties of the key.

@param anIndex A reference to a TInt supplied by the caller. On return, if the

               element is found, the reference is set to the position of that

			   element within the array. The position is relative to zero, 

			   (i.e. the first element in the array is at position 0).

			   If the element is not found and the array is not empty, then