/*==========================================================================
 *
 *  Copyright (C) 1995 - 2000 Microsoft Corporation.  All Rights Reserved.
 *
 *  File:       OrderedArray.h
 *  Content:	COrderedArray / COrderedPtrArray Declarations
 *
 *  History:
 *   Date		By			Reason
 *   ======		==			======
 *  12-12-2001	simonpow	Created
 ***************************************************************************/


#ifndef __ORDEREDARRAY_H__
#define __ORDEREDARRAY_H__

#include "AutoArray.h"

/*
 * COrderedArray
 * Maintains an array of elements that can be inserted into and removed
 * from whilst maintaining element order. i.e. List like semantics
 * This class is useful when you want to maintain a list of items in
 * order and scan the data far more often than you modify the list.
 * If you perform lots of insert/remove operations, then a linked
 * list is probably more efficient. 
 * Memory management is handled through CAutoArray so see comments
 * in that header for more information
 *
 * If you need an array of pointers use the specialisation COrderedPtrArray
 * declared below the COrderedArray class.
 */
 

template <class T > class COrderedArray
{
public:

		//provides the type of entries held
	typedef T Entry;

		//array starts 0 zero and by default grows in multiples
		//of 16 elements at a time
	COrderedArray(DWORD dwSizeMultiple=16) : m_data(dwSizeMultiple), m_dwTopFreeSlot(0)
		{ };

		//standard d'tor
	~COrderedArray()
		{};

	/*
	 * Memory Management
	 */

		//Delete existing contents and reset the size multiplier
		//Pass 0 for size multiplier to retain the existing value
	void Reset(DWORD dwSizeMultiple=16)
		{ m_data.Reset(dwSizeMultiple); m_dwTopFreeSlot=0; };
	
		//ensure that there is enough space in the array to hold at least 
		//'numElements' without needing to re-create and copy the data
		//returns FALSE if fails due to memory allocation failure
	BOOL AllocAtLeast(DWORD dwNumElements)
		{	return m_data.AllocAtLeast(dwNumElements);	};

		//ensure there is enough space in the array to hold at least an 
		//extra 'numElements' without needing to re-create and copy the data
		//returns FALSE if fails due to memory allocation failure
	BOOL AllocExtra(DWORD dwNumElements)
		{	return m_data.AllocAtLeast(dwNumElements+m_dwTopFreeSlot);	};


	/*
	 * Adding/Modifying Elements
	 */

		//add an entry to end of array
		//returns FALSE if fails due to memory allocation failure
	BOOL AddElement(const T& elem)
		{	return m_data.SetElement(m_dwTopFreeSlot++, elem);	};

		//add a number of elements to the end of the array
		//N.B. Don't pass pointers into data in this array as 'pElem'!
		//e.g. Don't do array.AddElements(array.GetAllElements, array.GetNumElements());
		//returns FALSE if fails due to memory allocation failure
	BOOL AddElements(const T * pElem, DWORD dwNumElem);

		//add the entries from another ordered array to the end of this one
		//N.B. Don't pass array to itself (e.g. Don't do array.AddElements(array); )
		//returns FALSE if fails due to memory allocation failure
	BOOL AddElements(const COrderedArray<T>& array);
		
		//set the element at 'dwIndex' to 'elem. Upto caller to
		//ensure this doesn't create a hole in array (i.e. dwIndex must be<=Num Entries)
		//returns FALSE if fails due to memory allocation failure
	inline BOOL SetElement(DWORD dwIndex, const T& elem);
	
		//set 'dwNumElem' from 'dwIndex' to values specified by 'pElem'
		//Upto caller to ensure this doesn't create a hole in array
		//(i.e. dwIndex must be<=Num Entries)
		//N.B. Don't pass pointers into data in this array as 'pElem'!
		//e.g. Don't do array.SetElements(x, array.GetAllElements, array.GetNumElements());
		//returns FALSE if fails due to memory allocation failure
	inline BOOL SetElements(DWORD dwIndex, const T * pElem, DWORD dwNumElem);

		//insert element 'elem' at index 'dwIndex, shifting up
		//elements after 'dwIndex' if necessary
		//Upto caller to ensure this doesn't create a hole in the array
		//i.e. dwIndex is within the current range
		//returns FALSE if fails due to memory allocation failure
	BOOL InsertElement(DWORD dwIndex, const T& elem);

		//insert 'dwNumElem' elements pointed to be 'pElems' into array
		//at index 'dwIndex', shifting up any existing elements if necessary
		//Upto caller to ensure this doesn't create a hole in the array
		//i.e. dwIndex is within the current range
		//N.B. Don't pass pointers into data in this array as 'pElem'!
		//e.g. Don't do array.InsertElements(x, array.GetAllElements, array.GetNumElements());
		//returns FALSE if fails due to memory allocation failure
	BOOL InsertElements(DWORD dwIndex, const T * pElems, DWORD dwNumElem);


	/*
	 * Removing Entries
	 */

		//remove the single entry at 'dwIndex', shifting all the entries
		//between 'index'+1 and the last entry down by one.
		//Upto caller to ensure dwIndex falls within the current array range
	inline void RemoveElementByIndex(DWORD dwIndex);

		//remove a block of 'dwNumElem' elements starting at 'dwIndex', moving
		//down all entries between 'index'+1 and the last entry by 'dwNumElem'.
		//Upto caller to ensure specified block falls within the current array range
	inline void RemoveElementsByIndex(DWORD dwIndex, DWORD dwNumElem);

		//remove first entry in array that matches 'elem'
		//returns TRUE if a match is found and FALSE otherwise
	BOOL RemoveElementByValue(const T& elem);

		//remove all the current entries in the array
	void RemoveAll()
		{	m_dwTopFreeSlot=0;	};
	

	/*
	 * Accessing the array data
	 * N.B. Treat any pointers into array contents very carefully.
	 * Adding new elements to the array or using the Alloc* methods
	 * can cause them to become invalid
	 */

		//returns the number of entries
	DWORD GetNumElements() const
		{	return m_dwTopFreeSlot;	};

		//returns TRUE if array is empty
	BOOL IsEmpty() const
		{	return (m_dwTopFreeSlot==0);	};

		//return value at a specific index
	T GetElementValue(DWORD dwIndex) const
		{	return m_data.GetElementValue(dwIndex);	};

		//return reference to an element at specific index
	T& GetElementRef(DWORD dwIndex)
		{	return m_data.GetElementRef(dwIndex);	};

		//return constant reference to an element at specific index
	const T& GetElementRef(DWORD dwIndex) const
		{	return m_data.GetElementRef(dwIndex);	};

		//return a pointer to an element
	T * GetElementPtr(DWORD dwIndex)
		{	return m_data.GetElementPtr(dwIndex);	};

		//returns pointer to array of all elements
	T * GetAllElements()
		{	return m_data.GetAllElements();	};

	/*
	 * Searching Array
	 */

		//find an instance of 'elem' in array. If found returns TRUE
		//and sets 'pdwIndex' to index of element
	BOOL FindElement(const T& elem, DWORD * pdwIndex) const;

		//returns TRUE if 'elem' is present in bag
	BOOL IsElementPresent(const T& elem) const
		{	DWORD dwIndex; return (FindElement(elem, &dwIndex));	};

protected:


	CAutoArray<T> m_data;
	DWORD m_dwTopFreeSlot;

};

/*
 * Specialisation of COrderedArray for handling pointers
 * If you ever need to declare an ordered array of pointers (e.g. char *)
 * declare it as an COrderedPtrArray (e.g. COrderedPtrArray<char *>).
 * This specilisation uses a COrderedArray<void *> underneath and hence
 * re-uses the same code between all types of COrderedPtrArray.
 */ 

template <class T> class COrderedPtrArray : public COrderedArray<void * >
{
public:
	
	typedef T Entry;

	typedef COrderedArray<void * > Base;

	COrderedPtrArray(DWORD dwSizeMultiple=16) : COrderedArray<void*>(dwSizeMultiple)
		{ };
	
	BOOL AddElement(T elem)
		{	return Base::AddElement((void * ) elem);	};

	BOOL AddElements(const T * pElem, DWORD dwNumElem)
		{	return Base::AddElements((void **) pElem, dwNumElem);	};

	BOOL AddElements(const COrderedArray<T>& array)
		{	return Base::AddElements((COrderedArray<void*>&) array);	};

	BOOL SetElement(DWORD dwIndex, T elem)
		{	return Base::SetElement(dwIndex, (void * ) elem);	};
	
	BOOL SetElements(DWORD dwIndex, T * pElem, DWORD dwNumElem)
		{	return Base::SetElements(dwIndex, (void**) pElem, dwNumElem);	};

	BOOL InsertElement(DWORD dwIndex, T elem)
		{	return Base::InsertElement(dwIndex, (void * ) elem);	};

	BOOL InsertElements(DWORD dwIndex, const T * pElems, DWORD dwNumElem)
		{	return Base::InsertElements(dwIndex, (void **) pElems, dwNumElem);	};

	BOOL RemoveElementByValue(T elem)
		{	return Base::RemoveElementByValue((void *) elem);	};

	T GetElementValue(DWORD dwIndex) const
		{	return (T) m_data.GetElementValue(dwIndex);	};

	T& GetElementRef(DWORD dwIndex)
		{	return (T&) m_data.GetElementRef(dwIndex);	};
	const T& GetElementRef(DWORD dwIndex) const
		{	return (const T&) m_data.GetElementRef(dwIndex);	};

	T * GetElementPtr(DWORD dwIndex)
		{	return (T*) m_data.GetElementPtr(dwIndex);	};

	T * GetAllElements()
		{	return (T*) m_data.GetAllElements();	};

	BOOL FindElement(T elem, DWORD * pdwIndex) const
		{	return Base::FindElement((void * ) elem, pdwIndex);	};

	BOOL IsElementPresent(T elem) const
		{	DWORD dwIndex; return (Base::FindElement((void * ) elem, &dwIndex));	};
};

/* 
 * COrderedArray inline methods
 */

template <class T>
BOOL COrderedArray<T>::AddElements(const T * pElem, DWORD dwNumElem)
{
		//ensure pointer passed isn't into this arrays contents
	DNASSERT(!(pElem>=m_data.GetAllElements() && pElem<m_data.GetAllElements()+m_data.GetCurrentSize()));
	if (!m_data.AllocAtLeast(m_dwTopFreeSlot+dwNumElem))
		return FALSE;
	m_data.SetExistingElements(m_dwTopFreeSlot, pElem, dwNumElem);
	m_dwTopFreeSlot+=dwNumElem;
	return TRUE;
}

template <class T>
BOOL COrderedArray<T>::SetElement(DWORD dwIndex, const T& elem)
{
	DNASSERT(dwIndex<=m_dwTopFreeSlot);
	if (dwIndex==m_dwTopFreeSlot)
		return m_data.SetElement(m_dwTopFreeSlot++, elem);
	m_data.SetExistingElement(dwIndex, elem);
	return TRUE;
}

template <class T>
BOOL COrderedArray<T>::SetElements(DWORD dwIndex, const T * pElem, DWORD dwNumElem)
{
		//ensure pointer passed isn't into this arrays contents
	DNASSERT(!(pElem>=m_data.GetAllElements() && pElem<m_data.GetAllElements()+m_data.GetCurrentSize()));
		//ensure hole isn't created
	DNASSERT(dwIndex<=m_dwTopFreeSlot);
	if (!m_data.SetElements(dwIndex, pElem, dwNumElem))
		return FALSE;
	dwIndex+=dwNumElem;
	m_dwTopFreeSlot = dwIndex>m_dwTopFreeSlot ? dwIndex : m_dwTopFreeSlot;
	return TRUE;
}

template <class T>
void COrderedArray<T>::RemoveElementByIndex(DWORD dwIndex)
{
	DNASSERT(dwIndex<m_dwTopFreeSlot);
	m_data.MoveElements(dwIndex+1, m_dwTopFreeSlot-dwIndex-1, dwIndex, FALSE);
	m_dwTopFreeSlot--;
};

template <class T>
void COrderedArray<T>::RemoveElementsByIndex(DWORD dwIndex, DWORD dwNumElem)
{
	DNASSERT(dwIndex+dwNumElem<=m_dwTopFreeSlot);
	m_data.MoveElements(dwIndex+dwNumElem, m_dwTopFreeSlot-dwIndex-dwNumElem, dwIndex, FALSE);
	m_dwTopFreeSlot-=dwNumElem;
}



/*
 * If not building with explicit template instantiation then also
 * include all other methods for COrderedArray
 */

#ifndef DPNBUILD_EXPLICIT_TEMPLATES
#include "OrderedArray.inl"
#endif


#endif	//#ifndef __ORDEREDARRAY_H__