include/EDoc/StringIdentifiedObject.h

Go to the documentation of this file.

/*******************************************************************************

   Copyright (C) 2007 by Brendon Costa

   This library is free software; you can redistribute it and/or modify 
   it under the terms of the "LGPL Like" License defined in the file COPYING 
   that should have been distributed along with this source.

   This library is distributed in the hope that it will be useful, 
   but WITHOUT ANY WARRANTY; without even the implied warranty of 
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  

   You should have received a copy of the "LGPL Like" License 
   along with this library; see the file COPYING. if not, it can be 
   obtained from the EDoc++ website: 
   http://edoc.sourceforge.net/license.html

*******************************************************************************/
#ifndef EDOC_STRINGIDENTIFIEDOBJECT_H
#define EDOC_STRINGIDENTIFIEDOBJECT_H

#include "EDoc/DictionarySpecific.h"
#include "EDoc/stdint.h"
#include <string>
#include <ostream>
#include <sstream>

#include <map>

namespace EDoc
{
   class PersistenceIFace;
   class IndexedDictionary;
   class IndexedObject;
   class Dictionary;
   class PStack;
   
   //===========================================================================
   /** \brief Represents a fundamental DictionarySpecific data type that has a
    * unique string identifier.
    *
    * All fundamental dictionary types derive from this abstract class. This
    * includes the classes:
    *    - File
    *    - Type
    *    - FunctionType
    *    - Function
    *    .
    *
    * This class exposes common functionality that makes managing these objects
    * a little simpler. In particular all such types are identified by a unique
    * string, however when saved in .edc files they are identified by unique
    * integer indexes. This class provides mechanisms to help in the process of
    * loading objects that are indexed with integers and fitting them into
    * objects indexed by strings.
    *
    * 
    * These objects all have common properties such as:
    *    - They all have eithre a string identifier OR an integer identifier.
    *       Only the string OR the integer can be used for indexing the object
    *       at any one point in time.
    *    - They can exist in a non-populated state waiting to be populated
    *    - They can all be written/read to/from a file
    *    - It can be easy to introduce a bug in pointer assignment between
    *       dictionaries, so they all support special internal validation and
    *       pointer replacement methods.
    *    .
    *
    * \see See Also Dictionary and DictionarySpecific
    */
   class StringIdentifiedObject : public DictionarySpecific
   {
      friend class IndexedDictionary;
      friend class IndexedObject;
      friend class Dictionary;
   public:

      //------------------------------------------------------------------------
      /** \brief Constructor called from a derived class initialising the object
       * with an initial string identifier.
       */
      StringIdentifiedObject(Dictionary& dict_in, std::string key_name_in, 
         bool populated_in=false);

      //------------------------------------------------------------------------
      /** \brief Constructor called from a derived class initialising the object
       * with an initial integer identifier.
       */
      StringIdentifiedObject(Dictionary& dict_in, int32_t index_in, 
         bool populated_in=false);
      
      //------------------------------------------------------------------------
      /** \brief Destructor.
       */
      virtual ~StringIdentifiedObject() {}
      
      //------------------------------------------------------------------------
      /** \brief See CodeBlock::Read()
       *
       * After reading objects
       * derived from StringIdentifiedObject will have their key name set and
       * will be considered "populated"
       */
      virtual void Read(PersistenceIFace& file, IndexedDictionary& idict) = 0;

      //------------------------------------------------------------------------
      /** \brief See CodeBlock::Write()
       */
      virtual void Write(PersistenceIFace& file) const = 0;

      //------------------------------------------------------------------------
      /** \brief Merges two StringIdentifiedObjects.
       *
       * \warning NOTE: The two objects MUST be of the same type. You can NOT 
       * merge a File with a Function.
       */
      virtual void Merge(const StringIdentifiedObject& right) = 0;

      //------------------------------------------------------------------------
      /** \brief Returns an integer identifying the type of the derived class.
       *
       * Currently the following integers are defined i npersistence_data.h:
       *    - 1 VALUE_RECORD_TYPE_TYPE for Type objects.
       *    - 2 VALUE_RECORD_TYPE_FUNCTION for Function objects.
       *    - 3 VALUE_RECORD_TYPE_FILE for File objects.
       *    - 4 VALUE_RECORD_TYPE_FUNCTION_TYPE for FunctionType objects.
       *    .
       */
      virtual uint8_t GetRecordType() const = 0;

      //------------------------------------------------------------------------
      /** \brief Returns the string key that identifies this object.
       *
       * Will assert if the object has not yet been populated OR it currently
       * uses an integer identifier not a string identifier.
       */
      const std::string& GetKeyName() const;
      
      //------------------------------------------------------------------------
      /** \brief Returns the integer key that identifies this object.
       */
      inline ssize_t GetIndex() const
      {
         return index;
      }

      //------------------------------------------------------------------------
      /** \brief Returns true if this object has been completely populated from
       * a file source or manually or false if the object is incomplete.
       */
      inline bool IsPopulated() const
      {
         return populated;
      }


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

   protected:
      
      //------------------------------------------------------------------------
      /** \brief Used by derived class to set the string key once it is able to
       * determine it.
       *
       * Usually an instance is created with an integer index and then data is
       * loaded into the object and once it has loaded it is able to determine
       * what its string index should be. Then it will call this function which
       * sets the integer index to -1 and sets the string key to the given
       * value.
       */
      void SetKeyName(std::string key_name_in);

      //------------------------------------------------------------------------
      /** \brief True if this object has been completely populated.
       */
      bool populated;

      //------------------------------------------------------------------------
      /** \brief Set to the integer index used to identify this object or -1 if
       * the key_name is used to identify this object.
       */
      mutable int32_t index;

      //------------------------------------------------------------------------
      /** \brief Set to the string key used to identify this object.
       */
      std::string key_name;




      //------------------------------------------------------------------------
      // Public Temporary Data values.
      //------------------------------------------------------------------------

      //------------------------------------------------------------------------
      /** \brief USED ONLY FROM Dictionary::Write()
       *
       * While writing an object to file it is possible to use both the objects
       * integer and string keys. This is the only time that is allowable and
       * this flag is used to determine that.
       */
      // @@@Brendon This is a horrible hack.
      mutable bool writing;

      //------------------------------------------------------------------------
   };
   //===========================================================================

   // For SWIG
   typedef StringIdentifiedObject* StringIdentifiedObjectPtr;
   typedef std::map<std::string, StringIdentifiedObject* > StrIDObjPMap;
}

#endif // EDOC_STRINGIDENTIFIEDOBJECT_H

---