include/EDoc/FunctionType.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_FUNCTIONTYPE_H
#define EDOC_FUNCTIONTYPE_H

#include "EDoc/StringIdentifiedObject.h"
#include <vector>
#include <sstream>

namespace EDoc
{
   class Type;
   class Function;
   
   //===========================================================================
   /** \brief Represents a C/C++ function pointer type.
    *
    * This stores information about the individual elements of a function
    * pointer or a member function pointer in C++. This information is stored
    * seperatly in order to be able to match function pointers that can be
    * called across C/C++ with types that may have different names due to
    * typedefs etc.
    *
    * It is primarily used for storing the type of a Function object and for
    * being stored in a CodeBlock::function_pointers list as a list of calls to
    * function pointers. The most important call is the IsEquivilant() function.
    */
   class FunctionType : public StringIdentifiedObject
   {
   public:

      //------------------------------------------------------------------------
      /** \brief See StringIdentifiedObject::(Dictionary& dict_in, 
       * std::string key_name_in, bool populated_in=false)
       */
      FunctionType(Dictionary& dict_in, std::string key_name_in);

      //------------------------------------------------------------------------
      /** \brief See StringIdentifiedObject(Dictionary& dict_in, 
       * int32_t index_in, bool populated_in=false)
       */
      FunctionType(Dictionary& dict_in, int32_t index_in);

      //------------------------------------------------------------------------
      /** \brief Copies data from another object into this one.
       *
       * This can be used across different dictionaries and will only copy
       * object data but not identification information used in the
       * StringIdentifiedObject such as the key name.
       */
      FunctionType& operator=(const FunctionType& right);

      //------------------------------------------------------------------------
      /** \brief See StringIdentifiedObject::Read()
       */
      void Read(PersistenceIFace& file, IndexedDictionary& idict);

      //------------------------------------------------------------------------
      /** \brief See StringIdentifiedObject::Write()
       */
      void Write(PersistenceIFace& file) const;

      //------------------------------------------------------------------------
      /** \brief See StringIdentifiedObject::Merge()
       */
      virtual void Merge(const StringIdentifiedObject& right);

      //------------------------------------------------------------------------
      /** \brief DictionarySpecific::ReplaceReferences()
       */
      virtual size_t ReplaceReferences(PStack& stack, 
         void* remove, void* replace);

      //------------------------------------------------------------------------
      /** \brief See DictionarySpecific::Print()
       */
      virtual std::ostream& Print(std::ostream& out, 
         std::string prefix="") const;

      //------------------------------------------------------------------------
      /** \brief See DictionarySpecific::Validate()
       */
      virtual void Validate(PStack& stack, const Dictionary& dict_in) const;

      //------------------------------------------------------------------------
      /** \brief Returns true if the two types are the same.
       *
       * Works across dictionaries.
       */
      bool operator==(const FunctionType& right) const;

      //------------------------------------------------------------------------
      /** \brief See StringIdentifiedObject::GetRecordType()
       */
      virtual uint8_t GetRecordType() const;














      //------------------------------------------------------------------------
      /** \brief Returns a string representation of this function pointer type
       * using the names for the types as the user may have defined them.
       */
      inline std::string GetDeclaredName() const
      {
         return GetNameInternal(false);
      }

      //------------------------------------------------------------------------
      /** \brief Returns a string representation of this function pointer type
       * using the names for the types in a normalized format.
       */
      inline std::string GetNormalisedName() const
      {
         return GetNameInternal(true);
      }
      


      //------------------------------------------------------------------------
      /** \brief See Function::GetSpecString()
       */
      std::string GetSpecString() const;


      //------------------------------------------------------------------------
      /** \brief Returns true if the function type on the right is equivilant
       * to the function type on the left.
       *
       * Note: This is not exact. It will return true in some cases where they
       * are NOT equivilant. This is due to C type equivilance tests that
       * differ from C++ ones. This needs to be worked on in the future, however
       * it will match as best it can from the data it has available.
       *
       * Types that trace to a root type with external linkage can be accuratly
       * tested for equivilance, however types whose root_type does NOT have
       * external linkage can not be tested for equality currently. So we 
       * just assume they are equal.
       */
      bool IsEquivilant(const FunctionType& right) const;

      //------------------------------------------------------------------------
      /** \brief A representative name for the function type.
       */
      std::string full_name;

      //------------------------------------------------------------------------
      /** \brief The type instance that represents the functions return type.
       */
      Type* return_type;
      
      //------------------------------------------------------------------------
      /** \brief The type instance that represents the class this function
       * belongs to if it is a pointer to a C++ class member.
       */
      Type* method_context;

      //------------------------------------------------------------------------
      /** \brief The type instances for all the parameters that make up the
       * functions aregument list.
       */
      std::vector<Type*> parameters;
      
      //------------------------------------------------------------------------
      /** \brief True if method_context is not null and this member is defined
       * const.
       */
      bool is_const;
      
      //------------------------------------------------------------------------
      /** \brief See Function::has_exception_spec
       */
      bool has_exception_spec;

      //------------------------------------------------------------------------
      /** \brief See Function::exception_spec
       */
      std::vector<Type*> exception_spec;


      //------------------------------------------------------------------------
      /** \brief Returns the name of this function type in one of two formats.
       *
       * \param canonical If true returns the canonical form of the function
       * name otherwise returns the declared form of the function pointer types
       * name.
       */
      std::string GetNameInternal(bool canonical) const;



      //------------------------------------------------------------------------
      // Public Temporary Data values.
      //------------------------------------------------------------------------
      // @@@Brendon These really should not be here!
      /** \brief Stores a list of other function types that are considered
       * equivilant to this one.
       *
       * This value is set by Dictionary::UpdateFunctionAddressLists() and is
       * used in expanding the callgraph for function pointer calls. Its value
       * is considered temporary and should not be used elsewhere.
       */
      std::vector<FunctionType*> equivilant;
      
      //------------------------------------------------------------------------
      /** \brief USED ONLY FROM Dictionary::CalculatePropogatingExceptions()
       *
       * This is only used as a "cache" and contains a list of all functions
       * that match this type whose addresses have been taken.
       */
      std::vector<Function*> addressed_functions;


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


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

#endif // EDOC_FUNCTIONTYPE_H

---