ElementArray.h

Go to the documentation of this file.

//! @file ElementArray.h
//! @brief An advanced array class containing data that needs to be construct / destruct
//! 
//////////////////////////////////////////////////////////////////////
 
#if !defined(AFX_ELEMENTARRAY_H__04DC4B96_93F6_11D2_A1B6_000000000000__INCLUDED_)
#define AFX_ELEMENTARRAY_H__04DC4B96_93F6_11D2_A1B6_000000000000__INCLUDED_
 
#ifdef _MSC_VER
#pragma once
#endif // _MSC_VER
 
#include "InstanciatedObject.h"
 
BEGIN_MOOTOOLS_NAMESPACE
 
typedef unsigned int ElementType;
 
//! @class CElementMethods
//! @brief CElementMethods is provided to CElementArray and give some information on the data as well as the methods to construct or destruct data in-place.
class DLL_TOOLSFUNCTION CElementMethods : public CXObject, public CInstanciatedObject
{
protected:
    virtual ~CElementMethods(); // Call ->Delete()
 
public:
    //! Return false is element array are object that need to be destructed, copied or serialized\n
    //!in this case, element are memory struct and array used memcpy\n
    //! when true is returned, DestructElement/CopyElement/SerializeElement is called anytime it is needed\n
    //
    //! @Note for class should return true if the class has virtual method and if we make copy between inherited object\n
    //! otherwise memcpy overwrite the virtual table, and the inheritance is lost
    virtual bool IsObject() const;
 
    //! This is the default object comparison method use when we store raw memory structure
    //! If we compare this and B:
    //! * We have this->GetBaseType == B->GetType, we make a memcpy with the size of the structure
    //! * We have this->GetBaseType = B->GetType, we memcpy with the sizeof(A)
    //! * We have this->GetType = B->GetBaseType, we memcpy with the sizeof(B)
    //! @Note If we have this->GetBaseType == this->GetBaseType we cannot do anything even if the structure are in relation, because\n
    //! we don't know the sizeof the BaseType. In such case IsObject should return true and CopyElement can handle this\n
    //! kind copy\n
    //
    //! For class we if this->GetBaseType() == B->GetType() that means that this knows how to copy from B
    virtual bool IsKindOf(const CElementMethods *methods) const;
 
    virtual SIZET GetSizeof() const = 0;
    virtual ElementType GetType() const = 0;
    virtual ElementType GetBaseType() const = 0;
    virtual void ConstructElement(void* pNewData) = 0; // Always initialize array elements
    virtual void DestructElement(void* pNewData);
    virtual void CopyElement(void* pDest, const void* pSrc);
    virtual void CopyElement(void* pDest, const CElementMethods *pSrcMethods, const void* pSrc, const CElementMethods *pDstMethods);
    virtual void SerializeElement(CXArchive& ar, void* pSrc);
 
    virtual CXRuntimeClassPtr GetRuntimeClassDescriptor() const { XASSERT(0); return NULL; }; //!< **Important** DECLARE_SERIAL_XOBJECT // IMPLEMENT_SERIAL_XOBJECT must be declared if the array need to be serialized
 
#ifdef _DEBUG
    using CXObject::Dump;
    virtual void Dump(const void *data) const;
#endif
};
 
//! @class CElementArray
//! @brief An advanced array class containing data that needs to be construct / destruct
//! @details CElementMethods provides some information about the data contained in the array.
//!
class DLL_TOOLSFUNCTION CElementArray : public CXObject
{
public:
    //! @enum GrowMode
    //! GrowMode control the way the array inflate while adding data.
    typedef enum GrowMode
    {
        GROW_DEFAULT = 0, //!< A default grow mode which increase the array size by 1024 bytes each times its needed
        GROW_KEEP_MODE = -1, //!< Keep the default grow size (SetAtGrow, SetSize)
        GROW_DOUBLE_SIZE = -2, //!< Double size the array for fast element growing (required when the final element number is not known, and is probably big)
    } GrowMode;
 
    //! Create an array. methods can be set to NULL when serializing (CElementMethods are created on the fly) or if SetMethods is called just after creation
    CElementArray(CElementMethods *methods);
    virtual ~CElementArray();
 
    void SetMethods(CElementMethods *methods);
 
    ElementType GetBaseTypeOfElement() const;
    ElementType GetTypeOfElement() const;
    SIZET GetSizeOfElement() const;
 
    void FreeExtra();
    int SetGrowFactor(int nGrowBy);
    void PreAllocate(int estimatedSize); //!< Preallocate array. GetSize() return 0. When filling the array, SetSize must be called with growOnly = true, otherwise array will be resized loosing the preallocation advantage
    //! Can be use after Preallocate(XX) or SetSize(XX).
    //! This allow to construct all XX objects only once. Calling SetSize(YY, true) allow to resized down or up (to XX) without construction / destruction of elements.
    //! As element are construct once, elements can be leaved in an unknown state so this is to be used carefully.
    //! The mode remains valid until FreeExtra or ConstructMode(false) to go back to a normal mode
    void ConstructMode(bool constructAllOnce);
 
    //! Set the new size of the array
    //! If the array is to small, the array size if increased by a factor depending on nGrowBy mode.
    //! If the array is too big, the array is resized unless growOnly = true
    //! if newSize = 0, the array is freed whatever growOnly value.
    virtual void SetSize(int nNewSize, bool growOnly = false, int nGrowBy = GROW_KEEP_MODE);
 
    virtual void Serialize(CXArchive& ar);
 
    int GetSize() const;
    int GetUpperBound() const;
    virtual void RemoveAll();
    void SetAt(int nIndex, const void *newElement);
    void *ElementAt(int nIndex);
    const void *ElementAt(int nIndex) const;
    const void *GetFirst() const;
    const void *GetNext(const void *ptrObject) const;
    void *GetFirst();
    void *GetNext(void *ptrObject);
    int Add(const void *newElement, int nGrowBy = GROW_KEEP_MODE);
    void SetAtGrow(int nIndex, const void *newElement, int nGrowBy = GROW_KEEP_MODE);
    void *operator[](int nIndex);
    const void *operator[](int nIndex) const;
 
    // Potentially growing the array
    int Append(const CElementArray& src, bool growOnly = false);
    bool Copy(const CElementArray& src, bool growOnly = false);
    bool Copy(int dstindex, int srcindex, const CElementArray& src);
    virtual CElementArray *Duplicate(bool copydata) const;
 
    // Operations that move elements around
    void InsertAt(int nIndex, void *newElement, int nCount = 1);
    void RemoveAt(int nIndex, int nCount = 1);
    void InsertAt(int nStartIndex, CElementArray* pNewArray);
 
    bool Reorder(const unsigned int *reforder, unsigned int size, bool moveToDestinationIndexes);
    unsigned int GetChecksum() const; //!< Return a checksum value made by bitwise operator that is a simple way to check if content changed between 2 calls
 
#ifdef _DEBUG
    void Dump(int index) const;
    void Dump() const;
#endif
 
protected:
    CElementMethods *pElementMethods;
 
    // Implementation
private:
    unsigned char *buffer;   // the actual array of data
    SIZET sizeofElement; // Size of one element (28/06/2013) : use size_t type, so elementCount*sizeofElement has type size_t which avoid 32 bits mult overflow)
    int elementCount;     // number of elements
    int maxElementCount;  // max allocated elements
    int growElementCount;   // number of element to grow the array
    bool allConstructed;
 
    void InitElement(SIZET);
    const CElementArray& operator=(const CElementArray& Rhs) {return *this;}; // Use Copy instead, to avoid unvoluntary copy
 
protected:
    #ifdef __WINDOWS__
    #pragma warning(push)
    #pragma warning(disable: 4995)
    #endif
    void ConstructElements(unsigned char *pNewData, int nCount);
    void DestructElements(unsigned char *pOldData, int nCount); 
    bool CopyElements(int dstindex, int srcindex, int nCount, const CElementArray& src);
    bool CanCopyElement(const CElementMethods *methods) const;
    #ifdef __WINDOWS__
    #pragma warning(pop)
    #endif
 
    void CopyElements(unsigned char *pDest, const unsigned char *pSrc, int nCount);
};
 
inline int CElementArray::GetSize() const
{
    return elementCount;
}
 
inline int CElementArray::GetUpperBound() const
{
    return elementCount - 1;
}
 
inline void CElementArray::SetAt(int nIndex, const void *newElement)
{
    if (nIndex < elementCount)
        CopyElements((buffer + (nIndex*sizeofElement)), (unsigned char *)newElement, 1);
}
 
inline void *CElementArray::ElementAt(int nIndex)
{
    if (nIndex < elementCount)
        return (void *)(buffer + (nIndex*sizeofElement));
 
    XASSERT(0);
    return NULL;
}
 
inline const void *CElementArray::ElementAt(int nIndex) const
{
    if (nIndex < elementCount)
        return (const void *)(buffer + (nIndex*sizeofElement));
 
    XASSERT(0);
    return NULL;
}
 
inline const void *CElementArray::GetFirst() const
{
    return (const void *)buffer;
}
 
inline const void *CElementArray::GetNext(const void *ptrObject) const
{
    return (const void *)(((unsigned char *)ptrObject) + sizeofElement);
}
 
inline void *CElementArray::GetFirst()
{
    return (void *)buffer;
}
 
inline void *CElementArray::GetNext(void *ptrObject)
{
    return (void *)(((unsigned char *)ptrObject) + sizeofElement);
}
 
inline int CElementArray::Add(const void *newElement, int nGrowBy)
{
    int nIndex = elementCount;
    SetAtGrow(nIndex, newElement, nGrowBy);
    return nIndex;
}
 
inline void CElementArray::SetAtGrow(int nIndex, const void *newElement, int nGrowBy)
{
    XASSERT(nIndex >= 0);
    XASSERT(nIndex < elementCount || newElement < buffer || newElement >= buffer + (maxElementCount * sizeofElement)); // Set size might reallocate memory. newElement should not be inside the block
 
    if (nIndex >= elementCount)
        SetSize(nIndex + 1, true, nGrowBy);
 
    CopyElements((buffer + (nIndex*sizeofElement)), (const unsigned char *)newElement, 1);
}
 
inline void *CElementArray::operator[](int nIndex)
{
    if (nIndex < elementCount)
        return (void *)(buffer + (nIndex*sizeofElement));
 
    XASSERT(0);
    return NULL;
}
 
inline const void *CElementArray::operator[](int nIndex) const
{
    if (nIndex < elementCount)
        return (const void *)(buffer + (nIndex*sizeofElement));
 
    XASSERT(0);
    return NULL;
}
 
inline void CElementArray::CopyElements(unsigned char *pDest, const unsigned char *pSrc, int nCount)
{
    if (!pElementMethods->IsObject())
    {
        XASSERT(pDest >= buffer);
        XASSERT((SIZET)(((pDest - buffer) / sizeofElement)*sizeofElement) == (SIZET)(pDest - buffer)); // Check pDest match a a multiple of sizeofElement from buffer
        xmemcpy_s(pDest, nCount*sizeofElement, pSrc, nCount*sizeofElement);
        return;
    }
 
    XASSERT(nCount >= 0);
    XASSERT(sizeofElement > 0);
 
    while (nCount--)
    {
        pElementMethods->CopyElement(pDest, pSrc);
        pDest += sizeofElement;
        pSrc += sizeofElement;
    }
}
 
END_MOOTOOLS_NAMESPACE
 
#endif // !defined(AFX_ELEMENTARRAY_H__04DC4B96_93F6_11D2_A1B6_000000000000__INCLUDED_)