MeVisLab/Standard/Sources/ML/MLBase/mlListBase.h

Go to the documentation of this file.

// **InsertLicense** code
//----------------------------------------------------------------------------------

//
// Defines the following classes:
// - ListBase: An abstract class derived from Base providing methods available
//     for all list classes.
// - ListTemplate: A class template derived from ListBase and std::vector.
//     It implements the persistence functionality of a list.
// - BaseListTemplate: A class template derived from ListTemplate. It should be
//     used for item classes that are subclasses of BaseItem.
// - For class BaseItem see mlBaseItem.h.
//----------------------------------------------------------------------------------

#ifndef __mlListBase_H
#define __mlListBase_H


// ML-includes
#ifndef __mlBaseInit_H
#include "mlBaseInit.h"
#endif
#ifndef __mlModuleIncludes_H
#include "mlModuleIncludes.h"
#endif
#ifndef __mlTreeNode_H
#include "mlTreeNode.h"
#endif
#ifndef __mlStringConversion_H
#include "mlStringConversion.h"
#endif


// Local includes
#ifndef __mlListParser_H
#include "mlListParser.h"
#endif

// Also include BaseItem although it is not needed here; however many derived classes still expect it.
#ifndef __mlBaseItem_H
#include "mlBaseItem.h"
#endif

// Safe casts.
#ifndef __mlRangeCasts_H
#include "mlRangeCasts.h"
#endif

ML_START_NAMESPACE

class BaseItem;

// ------------------------------------------------------------------
// ------------------------------------------------------------------

class MLBASEEXPORT ListBase : public Base
{
public:

  ListBase (bool persistance)
    : _hasPersistance(persistance),
      _actionClass(ActNew),
      _actionId(-1),
      _actionIndex(-1),
      _currentIndex(-1)
  {}




  virtual size_t getSize () const = 0;

  virtual BaseItem* getItemAt(MLssize_t /*index*/) { return NULL; };

  virtual const BaseItem* getConstItemAt(MLssize_t /*index*/) const { return NULL; };

  virtual void insertItemAt(MLssize_t /*index*/, const BaseItem* /*item*/) {};

  virtual void modifyItemAt(MLssize_t /*index*/, const BaseItem* /*item*/) {};

  virtual void deleteItemAt(MLssize_t /*index*/) {};

  virtual void selectItemAt(MLssize_t /*index*/) {};

  virtual const RuntimeType* getItemTypeId() const { return NULL; };

  virtual void clearList ()
  { setAction(ActNew); }

  virtual ListBase* clone() const { return NULL; };

  virtual ListBase* deepCopy() const { return clone(); };





  virtual bool hasPersistance () const { return _hasPersistance; }

  virtual void setPersistance (bool persistance) { _hasPersistance = persistance; }

  MLBASEEXPORT friend std::ostream& operator << (std::ostream &s, const ListBase &list);

  virtual void addStateToTree(TreeNode* parent) const;

  ML_SET_ADDSTATE_VERSION(0);

  virtual void readStateFromTree(TreeNode* parent);





  enum ActionClass
       {
         ActNone = 0,        
         ActUnknown,         
         ActNew,             
         ActSelect,          

         ActModify,          
         ActDelete,          

         ActInsert,          
         ActInsertOvw,       



         ActNumActions       
       };

  static const char *const ActionClassNames[ActNumActions];

  virtual void setAction (ActionClass actionClass, MLssize_t id, MLssize_t index);

  virtual void setAction (ActionClass actionClass)
  { setAction(actionClass, -1, -1); }

  virtual void getAction (ActionClass &actionClass, MLssize_t &id, MLssize_t &index) const;

  virtual ActionClass getActionClass () const
  { return _actionClass; }

  virtual MLssize_t getActionId () const
  { return _actionId; }

  virtual MLssize_t getActionIndex () const
  { return _actionIndex; }

  virtual MLssize_t getCurrentIndex () const
  { return _currentIndex; }

  virtual bool isModified () const
  { return (ActSelect != _actionClass && ActNone != _actionClass); }




protected:

  char *newString (const std::string &str) const
  { return ParserBase::newString(str); }

  void deleteString (char *str) const
  { ParserBase::deleteString(str); }

  ListBase &operator = (const ListBase &list);

private:

  bool _hasPersistance;

  ActionClass _actionClass;

  MLssize_t _actionId;

  MLssize_t _actionIndex;

  MLssize_t _currentIndex;


  ML_ABSTRACT_CLASS_HEADER(ListBase)

};



// ------------------------------------------------------------------
// ------------------------------------------------------------------

template <class T>
class ListTemplate : public ListBase, public std::vector<T>
{
public:

  typedef T itemType;




  ListTemplate () : ListBase(false) {}

  ListTemplate (bool persistance) : ListBase(persistance) {}





  virtual size_t getSize () const
  { using namespace std; return vector<T>::size(); }

  virtual void clearList ()
  { ListBase::clearList(); using namespace std; vector<T>::clear(); }


  ListTemplate<T> &operator = (const ListTemplate<T> &list)
  {
    using namespace std;

    ListBase::operator =(list);
    vector<T>::operator =(list);

    return *this;
  }

  virtual ListTemplate<T>* clone() const;

  virtual ListTemplate<T>* deepCopy() const { return clone(); };





  virtual char *getPersistentState () const;

  virtual void setPersistentState (const char *state);

  virtual void clearPersistentState (char *state) const
  { deleteString(state); }

  virtual void addStateToTree(TreeNode* parent) const;

  ML_SET_ADDSTATE_VERSION(2);

  virtual void readStateFromTree(TreeNode* parent);



protected:



    //  virtual char *getItemState (iterator /*it*/) { return 0; }
  virtual char *getItemState (typename ListTemplate<T>::const_iterator /*it*/) const { return 0; }

    //virtual void setItemState (iterator /*it*/, const char* /*state*/) {}
  virtual void setItemState (typename ListTemplate<T>::iterator /*it*/, const char* /*state*/) {}

    //virtual void clearItemState (iterator /*it*/, char *state)
  virtual void clearItemState (typename ListTemplate<T>::iterator /*it*/, char *state) const
  { deleteString(state); }


};



// ------------------------------------------------------------------
// Implementation of ListTemplate
// ------------------------------------------------------------------

template <class T>
char *ListTemplate<T>::getPersistentState () const
{
  using namespace std;

  typename ListTemplate<T>::const_iterator it;
  char *itemStr=NULL, *pListStr=NULL, *pItemStr=NULL;
  std::string listStr;

  if (hasPersistance())
  {
    // Start list with an opening bracket
    listStr = "[";

    // Iterate through list
    for (it = vector<T>::begin(); it != vector<T>::end(); it++)
    {
      // Separate items by a comma
        if (it != vector<T>::begin()){
            listStr += ", ";
        }

      // Get string representation for item object
      itemStr = getItemState(it);
      if (itemStr)
      {
        // Item string needs to be quoted?
        if (ListParser::needsQuote(itemStr))
        {
          // Obtain quoted version of item string and append it to list string
          pItemStr = ListParser::quoteString(itemStr);
          listStr += pItemStr;
          ListParser::deleteString(pItemStr);
        }
        else
          // Append unquoted item string to list string
          listStr += itemStr;
      }
      else
        // Empty item string, add "" to list string
        listStr += "\"\"";
    }

    // End list with a closing bracket
    listStr += ']';

    // Create copy of list string on heap
    pListStr = newString(listStr);
  }

  return pListStr;
}


template <class T>
void ListTemplate<T>::setPersistentState (const char *state)
{
  ListParser parser;
  int parserResult=0;
  char *pItemString=NULL;

  if (hasPersistance())
  {
    // Start with empty list
    clearList();

    // Initialize parser
    parserResult = parser.init(state);

    while (!parserResult)
    {
      // Parse next item string
      parserResult = parser.nextItemString(pItemString);
      if (pItemString && parserResult != ListParser::kEndOfSource)
      {
        using namespace std;

        // Append new item object at end of list
        vector<T>::insert(vector<T>::end(),  T());

        // Restore item object from item string
        setItemState(vector<T>::end()-1, pItemString);

        // Dispose item string
        ListParser::deleteString(pItemString);
      }
    }

    // Set list action
    setAction(ListBase::ActNew);

    // Print error message to console
    if (parserResult > 0 && parserResult != ParserBase::kEmptyString) {
      ML_PRINT_ERROR("ListTemplate::setPersistentState()", ML_EMPTY_MESSAGE,
                     parser.getErrorMessage(parserResult));
    }
  }
}


template <class T>
void ListTemplate<T>::addStateToTree(TreeNode* parent) const
{
  using namespace std;

  //if (!hasPersistance()) return;

  ML_ADDSTATE_VERSION(ListTemplate<T>);

  // add listbase members
  ML_ADDSTATE_SUPER(ListBase);

  typename ListTemplate<T>::const_iterator it;

  // write list size always as unsigned 64 bit integer.
  parent->addChild(static_cast<MLuint64>(vector<T>::size()), "ListSize");

  // write list items:
  TreeNode* items = parent->addChild("ListItems");

  // Iterate through list
  for (it = vector<T>::begin(); it != vector<T>::end(); it++)
  {
    char* state = getItemState(it);
    items->addChild(state, "Item");
    ML_DELETE_ARRAY(state);
  }

}

template <class T>
void ListTemplate<T>::readStateFromTree(TreeNode* parent)
{
  using namespace std;

  if (!hasPersistance()) { return; }

  int version = parent->getVersion("ListTemplate");

  // Currently supporting version <= 2 only, version 2 is saved by 64 bit systems.
  if (version > 2){
    // Error, too high version number.
    throw TreeNodeException(TNE_UnsupportedClassVersion);
  }

  if (version >= 1) {
    // ListBase saves its members since version 1:
    ML_READSTATE_SUPER(ListBase);
  }

  bool endLoop = false;

  clearList();

  // read size if possible
  MLuint64 loadedSize = 0;
  ML_READCHILD_OPTIONAL(loadedSize, "ListSize", 0);

  #if !defined(ML_IS_64_BIT_SYSTEM)
    // Check whether list size is too large for 32 bit systems.
    if (loadedSize >= static_cast<MLuint64>(ML_UINT32_MAX)){
      ML_PRINT_ERROR("ListTemplate<T>::readStateFromTree",
                     ML_OUT_OF_RANGE,
                     "The stored ListSize parameter of a ListTemplate is too "
                     "large to be handled on 32 bit systems. It is set to 0 to "
                     "avoid memory overflows; thus the structure is not loaded "
                     "correctly.");
      loadedSize = 0;
    }
  #endif

  // reserve some memory for the list. However, we do really want to rely on the ListSize
  // setting and still read until a child is not found.
  vector<T>::reserve( static_cast<size_t>(loadedSize) );

  TreeNode* items = parent->readContainerChild("ListItems");

  char* currStr = NULL;
  do {
    // try to read next child:
    if (items->hasChild()) {
      items->readChild(currStr);
    } else {
      // break free from loop
      endLoop = true;
    }
    if (!endLoop) {

      vector<T>::insert(vector<T>::end(), T());

      // Restore item object from item string
      setItemState(vector<T>::end()-1, currStr);
      items->deleteString(currStr);
      currStr = NULL;
    }
  } while (!endLoop);

  items->deleteString(currStr);

  // Set list action
  setAction(ListBase::ActNew);
}



template <class T>
ListTemplate<T>* ListTemplate<T>::clone() const
{
  // get runtime type of this instance
  const RuntimeType* thisType = this->getTypeId();

  // valid type?
  if (!thisType || !thisType->canCreateInstance()) {
    // invalid type
    return NULL;
  }

  ListTemplate<T>* newList = static_cast<ListTemplate<T>*>(thisType->createInstance());
  if (!newList) {
    // object creation failed
    return NULL;
  }

  (*newList) = (*this);

  return newList;
}





// ------------------------------------------------------------------
// ------------------------------------------------------------------

template <class T>
class BaseListTemplate : public ListTemplate<T>
{
public:



  BaseListTemplate () : ListTemplate<T>(), _nextId(1) {}

  BaseListTemplate (bool persistance) : ListTemplate<T>(persistance), _nextId(1) {}


  virtual BaseItem* getItemAt(MLssize_t index){
    return &(*this)[mlrange_cast<size_t>(index)];
  };

  virtual const BaseItem* getConstItemAt(MLssize_t index) const {
    return &(*this)[mlrange_cast<size_t>(index)];
  };

  virtual void insertItemAt(MLssize_t index, const BaseItem* item) {
    if (item && (getItemTypeId() == item->getTypeId())) {
      doInsertItem(index, *static_cast<const T*>(item) );
    }
  };


  virtual void modifyItemAt(MLssize_t index, const BaseItem* item) {
    if (item && (getItemTypeId() == item->getTypeId())) {
      doModifyItem(index, *static_cast<const T*>(item) );
    }
  };

  virtual void deleteItemAt(MLssize_t index) {
    doDeleteItem(index);
  };

  virtual void selectItemAt(MLssize_t index) {
    doSelectItem(index);
  };

  virtual const RuntimeType* getItemTypeId() const {
    return T::getClassTypeId();
  }




  virtual MLssize_t newId () { return _nextId++; }

  virtual void usedId (MLssize_t id)
  {
      if (id >= _nextId) {
        _nextId = id+1;
      }
  }

  virtual void resetId ()
  {
    _nextId = 1;
    for (typename ListTemplate<T>::iterator it = ListTemplate<T>::begin(); it != ListTemplate<T>::end(); it++){
      usedId(it->getId());
    }
  }


  virtual void clearList ()
  {
    ListTemplate<T>::clear();
    resetId();
  }




  virtual void doDeleteItem (MLssize_t index);

  virtual void doInsertItem (MLssize_t index, const T &item);

  virtual void doModifyItem (MLssize_t index, const T &item);

  virtual void doSelectItem (MLssize_t index);

  virtual void appendItem(const T &item);

  virtual void addStateToTree(TreeNode* parent) const;


  ML_SET_ADDSTATE_VERSION(1);

  virtual void readStateFromTree(TreeNode* parent);





protected:



  virtual char *getItemState (typename ListTemplate<T>::const_iterator it) const
  { return it->getPersistentState(); }

  virtual void setItemState (typename ListTemplate<T>::iterator it, const char *state)
  {
    it->setPersistentState(state);
    usedId(it->getId());
  }

  virtual void clearItemState (typename ListTemplate<T>::iterator it, char *state) const
  { it->clearPersistentState(state); }



private:

  MLssize_t _nextId;

};




// ------------------------------------------------------------------
// --- Implementation of BaseListTemplate
// ------------------------------------------------------------------

template <class T>
void BaseListTemplate<T>::doDeleteItem (MLssize_t index)
{
  if ((index >= 0) && (index < static_cast<MLssize_t>(ListTemplate<T>::size())) )
  {
    this->setAction(ListTemplate<T>::ActDelete, (*this)[mlrange_cast<size_t>(index)].getId(), index);
    ListTemplate<T>::erase(ListTemplate<T>::begin()+index);
  }
}


template <class T>
void BaseListTemplate<T>::doInsertItem (MLssize_t index, const T &item)
{
  MLssize_t id=0;

  if ((index >= 0) && (index <= mlrange_cast<MLssize_t>(ListTemplate<T>::size())) )
  {
    ListTemplate<T>::insert(ListTemplate<T>::begin()+index, item);
    id = newId();
    (*this)[static_cast<size_t>(index)].setId(id);
    this->setAction(ListTemplate<T>::ActInsert, id, index);
  }
}

template <class T>
void BaseListTemplate<T>::appendItem(const T &item)
{
    doInsertItem(static_cast<MLssize_t>(ListTemplate<T>::size()), item);
}


template <class T>
void BaseListTemplate<T>::doModifyItem (MLssize_t index, const T &item)
{
  if ((index >= 0) && (index < mlrange_cast<MLssize_t>(ListTemplate<T>::size())) )
  {
    const size_t idx_size_t = static_cast<size_t>(index);
    const MLssize_t id = (*this)[idx_size_t].getId();
    (*this)[idx_size_t] = item;
    (*this)[idx_size_t].setId(id);
    this->setAction(ListTemplate<T>::ActModify, id, index);
  }
}


template <class T>
void BaseListTemplate<T>::doSelectItem (MLssize_t index)
{
  if ((index >= 0) && (index < mlrange_cast<MLssize_t>(ListTemplate<T>::size())) )
  {
    this->setAction(ListTemplate<T>::ActSelect, (*this)[static_cast<size_t>(index)].getId(), index);
  }
}


template <class T>
void BaseListTemplate<T>::addStateToTree(TreeNode* parent) const
{
  ML_ADDSTATE_VERSION(BaseListTemplate<T>);

  // add ListBase members
  ML_ADDSTATE_SUPER(ListBase);

  typename BaseListTemplate<T>::const_iterator it;
  MLuint64 i = 0;

  // write list size
  parent->addChild(static_cast<MLuint64>(ListTemplate<T>::size()), "ListSize");

  TreeNode* items = parent->addChild("ListItems");

  // Iterate through list
  for (it = ListTemplate<T>::begin(); it != ListTemplate<T>::end(); it++, i++)
  {
    items->addChild(&(*it), "Item", false);
  }

}

template <class T>
void BaseListTemplate<T>::readStateFromTree(TreeNode* parent)
{
  int version = parent->getVersion("BaseListTemplate");

  // Currently supporting version <= 2 only, version 2 is 64 bit version.
  if (version > 2) {
    throw TreeNodeException(TNE_UnsupportedClassVersion);
  }

  if (version >= 1) {
    // ListBase saves its members since version 1:
    ML_READSTATE_SUPER(ListBase);
  }

  bool endLoop = false;

  clearList(); // includes _nextId = 1;

  // read size if possible
  MLuint64 loadedSize = 0;
  ML_READCHILD_OPTIONAL(loadedSize, "ListSize", 0);

  #if !defined(ML_IS_64_BIT_SYSTEM)
    // Check whether list size is too large for 32 bit systems.
    if (loadedSize >= static_cast<MLuint64>(ML_UINT32_MAX)){
      ML_PRINT_ERROR("BaseListTemplate<T>::readStateFromTree",
                     ML_OUT_OF_RANGE,
                     "The stored ListSize parameter of a BaseListTemplate is too "
                     "large to be handled on 32 bit systems. It is set to 0 to "
                     "avoid memory overflows; thus the structure is not loaded "
                     "correctly.");
      loadedSize = 0;
    }
  #endif

  // reserve some memory for the list. However, we do not really want to rely on the ListSize
  // setting and still read until a child is not found.
  ListTemplate<T>::reserve( static_cast<size_t>(loadedSize) );

  TreeNode* items = parent->readContainerChild("ListItems");

  if (items) do {
    // try to read next child:
    if (items->hasChild()) {
      ListTemplate<T>::insert(ListTemplate<T>::end(), T());
      items->readChild(*(ListTemplate<T>::end()-1));
    } else {
      // break free from loop
      endLoop = true;
    }
    if (ListTemplate<T>::size() > 0){
        // update _nextId:
        _nextId = ML_MAX(_nextId, (ListTemplate<T>::end()-1)->getId() + 1);
    } else {
        endLoop = true;
    }
  } while (!endLoop);

  // Set list action
  this->setAction(ListTemplate<T>::ActNew);
}


ML_END_NAMESPACE


#endif // __mlListBase_H