libs/EDoc/Dictionary.cpp

Go to the documentation of this file.

#warning "@@@Brendon Document the AddException function and friends that we just added."
#warning "@@@Brendon Document the Function::on_processed members"
/*******************************************************************************

   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

*******************************************************************************/
#include "config.h"

#include "EDoc/Dictionary.h"
#include "EDoc/Type.h"
#include "EDoc/Function.h"
#include "EDoc/FunctionType.h"
#include "EDoc/File.h"
#include "EDoc/PersistenceIFace.h"
#include "EDoc/exceptions.h"
#include "EDoc/Logger.h"
#include "EDoc/utils.h"
#include "EDoc/PStack.h"
#include "EDoc/StackRef.h"
#include "EDoc/NotificationIFace.h"
#include "EDoc/TranslationUnit.h"

#include "EDoc/persistence_data.h"
#include "IndexedDictionary.h"

#include <iomanip>
#include <set>
#include <algorithm>

//===========================================================================
/** \brief define a small macro that is called upon a merge error.
 */
#define EDOC_MERGE_ERROR(Message) \
   EDOC_Error(Message); \
   EDOC_THROW_EXCEPTION(MergeException, "Failed merging dictionary.", Message);


namespace EDoc
{
   //==========================================================================
   /** \brief Returns true if the callgraph complexity of left is less than 
    * that of right.
    *
    * Complexity is defined by the following in order of precedence:
    *
    *    - Total number of unique calls to other functions 
    *       (Function::total_calls)
    *    - Functions part of circular callgraphs are more complex than 
    *       those that are not.
    *    - Functions part of circular callgraphs with more members in it
    *       are more complex than those that are not.
    *    - Finally we use the memory address of the circular set to order
    *       so that members in the same circular callgraph are next to 
    *       each other.
    *    .
    */
   static bool LessThanCallComplexity(const Function* left, 
      const Function* right)
   {
      // If total calls differs, then use that to determine order.
      if (left->total_calls != right->total_calls)
      {
         return left->total_calls < right->total_calls;
      }
      
      // If same number of unique calls, then order based on
      // circular callgraphs being "more complex" than others.
      
      // If the circular instances are both NULL OR both the same
      // then we are the same complexity.
      if (left->circular == right->circular)
      {
         return false;
      }
      
      // If one is circular and the other is not, then the one
      // that is not is less complex.
      if (!left->circular && right->circular)
      {
         return true;
      }
      else if (left->circular && !right->circular)
      {
         return false;
      }

      // Otherwise we have two functions both with the same total_calls
      // both in circular callgraphs, but both in different circles.
      
      // Will say circle with more members is more complex.
      if (left->circular->size() != right->circular->size())
      {
         return left->circular->size() < right->circular->size();
      }
      
      // If they are in different circles but both circles have the
      // same number of items in the circles, then we will just
      // sort based on the pointer address so that members in the
      // same circle are next to each other.
      return (uintptr_t)left->circular < (uintptr_t)right->circular;
   }

   //===========================================================================
   /** \brief 
    */
   static void AddRethrow(
      std::list<PropogatingException>& exceptions, 
      PropogatingException& exception,
      FunctionLoc& fcall,
      std::list<PropogatingException>& poss_curr_catch_types)
   {
      // We can "rethrow" one of any of the current possible catch type 
      // exceptions.
      EDOC_FOREACH(PropExcepList, it, poss_curr_catch_types)
      {
         // If fcall defines a "possible" rethrow OR
         // the pcct exception is a "possible" exception, then the resulting
         // exception is also not definite. 
         // I.e. 
         // It "may or may not be rethrown" (fcall.possible)
         // OR
         // It "may or may-not have propogated to this function through some
         // function pointer or virtual function call in the first place"
         // (it->possible).
         bool possible = fcall.possible | it->possible;
         
         // If exception we are re-throwing is not visible, then the result is
         // not visible. 
         // Likewise if the "rethrow" is not visible, then neithre is the
         // result.
         bool visible = exception.visible & it->visible;
         
         // For the exception being rethrown see if we already have 
         // an item in our list for it.
         PropogatingException* pe = NULL;
         EDOC_FOREACH(PropExcepList, jt, exceptions)
         {
            if (*jt == *it)
            {
               pe = &*jt;
               break;
            }
         }

         // If no item in our list for it then add one.
         if (!pe)
         {
            exceptions.push_back(*it);
            pe = &exceptions.back();
            pe->possible = possible;
            pe->visible = it->visible;
         }
         else
         {
            // If we have this exception in the list already,
            // then it is only going to result in a "possible" exception if both
            // the existing one in the list and the new one are both "possible".
            if (it->possible)
            {
               pe->possible = possible;
            }
            
            // result is only "invisible" if both item in list is invisible, and
            // new item is invisible.
            if (!it->visible)
            {
               pe->visible = visible;
            }
         }
         

         // Mark that the exception may be rethrown here.
         EDOC_Fine("Adding rethrow to exception: " 
            << pe->exception->type.value->GetDeclaredName());
         pe->rethrows.push_back(exception.exception);
      }
   }

   //===========================================================================
   /** \brief 
    */
   // exceptions : the current list of exceptions propogating from a function
   // fcall : The call to a function which resulted in the exception
   // exception : The exception belonging to function pointer to by fcall that
   //             we want to add to our list
   // poss_curr_catch_types : A list of exceptions that have been caught and are
   static inline bool AddPException(
      Dictionary& dict,
      std::list<PropogatingException>& exceptions, 
      PropogatingException& exception,
      FunctionLoc& fcall,
      std::list<PropogatingException>& poss_curr_catch_types)
   {
      // Specially handle the rethrow "..." case when we have a list of 
      // poss_curr_catch_types that can BE 'rethrown".
      if ((exception.exception->type.value->GetDeclaredName() == "...") &&
         poss_curr_catch_types.size())
      {
         AddRethrow(exceptions, exception, fcall, poss_curr_catch_types);
         return true;
      }
      
      // Otherwise if is a rethrow and nothing in catch list OR is any
      // exception other than a rethrow, then we will add the exception
      // to the list if it is not already in it.
      
      // First construct the propogating exception object for our list
      // from the one belonging to function pointer to by fcall.
      PropogatingException pe(dict, exception.exception, fcall);
      
      // If fcall is possible OR exception is possible, then this new 
      // exception should also be possible.
      pe.possible = fcall.possible | exception.possible;
      
      // Visibility porpogates only from the exception we are propogating.
      pe.visible = exception.visible;
      

      // See if the exception already exists in the list (Note: Exceptions
      // thrown from different locations or as a result of different function
      // calls are considered as different exceptions.)
      EDOC_FOREACH(PropExcepList, it, exceptions)
      {
         if (*it == pe)
         {
            EDOC_Finer("Exception already exists: " 
               << pe.exception->type.value->GetDeclaredName());
            
            // If we have this exception in the list already,
            // then it is only going to result in a "possible" exception if both
            // the existing one in the list and the new one are both "possible".
            if (it->possible)
            {
               it->possible = pe.possible;
            }
            
            if (!it->visible)
            {
               it->visible = pe.visible;
            }
            return false;
         }
      }
      
      EDOC_Fine("Adding new exception: " 
         << pe.exception->type.value->GetDeclaredName());
      exceptions.push_back(pe);
      return true;
   }
   
   
   //===========================================================================
   /** \brief 
    */
   static inline bool AddOException(
      Dictionary& dict,
      std::list<PropogatingException>& exceptions, 
      Exception& exception,
      std::list<PropogatingException>& poss_curr_catch_types)
   {
      // An originating exception is handled basically the same as a propogating
      // exception, except:
      //
      //    - The function call location is undefined
      //    - The function called to produce the exception is NULL
      //    - The cause is never a "possible" call giving rise to a "possible"
      //          exception
      //    - The cause is always visible, so never giving rise to an
      //       "invisible" propogating exception.
      
      // So we just create a "dummy" propogating exception to use for this
      // and call the propogating exception implementation.
      FunctionLoc dummy_fcall(dict, NULL, *dict.UNKNOWN_LOCATION);
      PropogatingException dummy_pe(dict, &exception, dummy_fcall);
      
      return AddPException(dict, exceptions, dummy_pe, dummy_fcall, 
         poss_curr_catch_types);
   }


   //===========================================================================
   /** \brief
    */
   static bool AddExceptions(
      std::list<PropogatingException>& exceptions, 
      std::list<PropogatingException>& add)
   {
      size_t added = 0;
      
      // For each exception in add:
      //    1) add it to exceptions if it is not already in there.
      //    2) if it is in there then append to its rethrows list the contents 
      //       of our rethrows list.
      EDOC_FOREACH(PropExcepList, it, add)
      {
         PropExcepList::iterator s = std::find(exceptions.begin(),
            exceptions.end(), *it);
         if (s != exceptions.end())
         {
            AppendUnique(s->rethrows, it->rethrows);
         }
         else
         {
            added++;
            exceptions.push_back(*it);
         }
      }
      return added;
   }
   //===========================================================================





   //===========================================================================
   static Dictionary* current = NULL;
   //===========================================================================
   Dictionary* GetCurrentDictionary()
   {
      return current;
   }
   //===========================================================================
   Dictionary* GetCurrentDictionaryAssert()
   {
      EDOC_ASSERT(current, "");
      return current;
   }
   //===========================================================================
   void SetCurrentDictionary(Dictionary* current_in)
   {
      current = current_in;
   }
   //===========================================================================
   Dictionary::Dictionary() :
      //CURRENT_EXCEPTION_TYPE(NULL),
      UNKNOWN_FILE(NULL),
      UNKNOWN_LOCATION(NULL),
      SUBSTITUTION_EXCEPTION_TYPE(NULL),
      files(*this),
      types(*this),
      function_types(*this),
      functions(*this)
   {
      GeneratePredefined();
   }
   //===========================================================================
   Dictionary::~Dictionary()
   {
      // We own the memory for the types and functions. So delete it now.
      EraseAll();
   }
   //===========================================================================
   void Dictionary::EraseAll()
   {
      MngObjPList objs = GetManagedObjects();
      EDOC_FOREACH(MngObjPList, it, objs)
      {
         (*it)->EraseAll();
      }
      
      //delete SUBSTITUTION_EXCEPTION_TYPE;
      SUBSTITUTION_EXCEPTION_TYPE = NULL;

      delete UNKNOWN_LOCATION;
      UNKNOWN_LOCATION = NULL;

      //delete UNKNOWN_FILE;
      UNKNOWN_FILE = NULL;
   }
   //===========================================================================
   void Dictionary::GeneratePredefined()
   {
      if (!UNKNOWN_FILE)
      {
         // First check to see if the "" file already exists and use that if so.
         File* file = files.AlwaysGet("");
         if (!file->IsPopulated())
         {
            file->key_name = "";
            file->index = -1;

            file->populated = true;
         }
         UNKNOWN_FILE = file;
      }
      
      if (!UNKNOWN_LOCATION)
      {
         UNKNOWN_LOCATION = new Location(this);
      }

      if (!SUBSTITUTION_EXCEPTION_TYPE)
      {
         Type* type = types.AlwaysGet("....");
         if (!type->IsPopulated())
         {
            type->name = "....";
            type->index = -1;
            type->external_linkage = false;
            type->translation_unit = TranslationUnit::GetUnknown();
            type->throw_type = type;
            type->root_type = type;
            
            // No other types are identical.
            // No other types (except ...) can be used to catch this type.
            type->loc = *UNKNOWN_LOCATION;
            type->referenced_in_files.push_back(
               const_cast<File*>(UNKNOWN_FILE));
            
            // This should never be in documentation anyway.
            type->visible = true;

            type->populated = true;
         }
         SUBSTITUTION_EXCEPTION_TYPE = type;
      }
   }
   //===========================================================================
   void Dictionary::Read(PersistenceIFace& file)
   {
      EraseAll();
      
      IndexedDictionary idict(*this);

      uint8_t record_type = file.ReadRecordType();
      if (record_type != VALUE_RECORD_TYPE_HEADER)
      {
         EDOC_THROW_EXCEPTION(FileIOException, "Invalid record type. "
            "Expected: " << (unsigned int)VALUE_RECORD_TYPE_HEADER 
            << ", Received: " << (unsigned int)record_type,
            "");
      }

      uint8_t version = file.ReadUInt8(KEY_EDOC_VERSION);
      EDOC_Fine("Version: " << (uint32_t)version);
      if (version != EDOC_FILE_VERSION)
      {
         EDOC_THROW_EXCEPTION(FileIOException, "Mismatching file version.",
            "EDoc version: " << PACKAGE_VERSION 
            << " can only load .edc files of version: " 
            << (unsigned int)EDOC_FILE_VERSION 
            << ", failed loading .edc file of version: " 
            << (unsigned int)version);
      }
      
      uint32_t size = 0;
      size = file.ReadUInt32(KEY_TRANSLATION_UNITS_LS);
      translation_units.erase(translation_units.begin(), 
         translation_units.end());
      for (size_t i = 0; i < size; i++)
      {
         translation_units.push_back(
            TranslationUnit::Create(file.ReadString(KEY_TRANSLATION_UNIT)));
      }

      std::vector<ManagedObject*> dict_stages = GetManagedObjectsVector();
      std::vector<IndexedObject*> idict_stages = idict.GetManagedObjects();
      EDOC_ASSERT(dict_stages.size() == idict_stages.size(), "");
      
      // Read each record and add it to the dict.
      int stage = 0;
      bool more_records = true;
      while (more_records)
      {
         try
         {
            record_type = file.ReadRecordType();
         }
         catch(EOFException& eofe)
         {
            // No more records to read.
            EDOC_Fine("Finished reading file.");
            more_records = false;
            break;
         }

         // Read the index for this item.
         uint32_t index = file.ReadUInt32(KEY_INDEX);

         int rt_stage = 0;
         if       (record_type == VALUE_RECORD_TYPE_FILE) rt_stage = 0;
         else if  (record_type == VALUE_RECORD_TYPE_TYPE) rt_stage = 1;
         else if  (record_type == VALUE_RECORD_TYPE_FUNCTION_TYPE) rt_stage = 2;
         else if  (record_type == VALUE_RECORD_TYPE_FUNCTION) rt_stage = 3;
         else
         {
            EDOC_THROW_EXCEPTION(FileIOException, "Invalid record type.", 
               "Record Type: " << (unsigned int)record_type);
         }

         // Ensure that the records are in the correct order.
         if (stage > rt_stage)
         {
            EDOC_THROW_EXCEPTION(FileIOException, 
               "File record found out of order.", "");
         }
         stage = rt_stage;


         // Obtain an object and populate it.
         EDOC_Finer("Reading record in stage: " << stage);
         StringIdentifiedObject* item = idict_stages[stage]->CAlwaysGet(index);
         EDOC_ASSERT(!item->IsPopulated(), "")
         item->Read(file, idict);

         // See if we already have an instance for it.
         EDOC_Finer("Ensuring uniqueness of record and inserting it into "
            "the dictionary: " << item->GetKeyName());
         if(dict_stages[stage]->CGet(item->GetKeyName()))
         {
            StringIdentifiedObject* item2 = 
               dict_stages[stage]->CGet(item->GetKeyName());

            EDOC_Debug("Item exists. "
               "Replacing stub: " << (void*)item2 
               << ", with populated: " << (void*)item 
               << ", for key: " << item->GetKeyName());

            // Then a file has previously been inserted as a place holder
            // based on its name. We will need to erase all references to
            // this "stub" and replace them with references to this populated
            // file instance.
            EDOC_ASSERT(!item2->IsPopulated(), "stage: " << stage 
               << ", item: " << item->GetKeyName() 
               << " has already been populated. This means there is a "
               "duplicate in the .edc file. "
               << "Item details: " << item->ToString());

            PStack stack;
            size_t replaced = ReplaceReferences(stack, item2, item);
            EDOC_ASSERT(replaced, "");
            dict_stages[stage]->CRemove(item);
            delete item2;
         }
         EDOC_Debug("Read stage: " << (unsigned int)stage 
            << ", item: " << item->GetKeyName());
         dict_stages[stage]->CAdd(item);
      }

      // Lets look at all the integer keyed instances and ensure that we have
      // them in our string keys maps.
      // We dont care so much if we have additional instances in our string
      // indexed dictionary as long as they have somehow been populated as
      // checked in the validate call.
      for (size_t i = 0; i < idict_stages.size(); i++)
      {
         EDOC_FOREACH(StrIDObjPMap, it, dict_stages[i]->items)
         {
            for (size_t j = 0; j < idict_stages[i]->items.size(); j++)
            {
               if (it->second == idict_stages[i]->items[j])
               {
                  idict_stages[i]->items[j] = NULL;
                  it->second->index = -1;
               }
            }
         }
         
         // After setting to NULL the ones we are using in the string indexed
         // dictionary. Assert if there are any left over.
         for (size_t j = 0; j < idict_stages[i]->items.size(); j++)
         {
            EDOC_ASSERT(!idict_stages[i]->items[j], 
               "Left-over item in indexed dictionary." 
               << "\nIndex: " 
               << idict_stages[i]->items[j]->index
               << "\nKey: " 
               << idict_stages[i]->items[j]->key_name);
         }
      }
      
      GeneratePredefined();
      #ifdef EDOC_ENABLE_VALIDATION
      Validate();
      #endif // EDOC_ENABLE_VALIDATION
   }
   //===========================================================================
   void Dictionary::Merge(const Dictionary& right)
   {
      if (&right == this)
      {
         return;
      }

      // Add any translation units from right to our list
      EDOC_FOREACH_CONST(TUnitPVec, it, right.translation_units)
      {
         PushBackUnique(translation_units, *it);
      }

      std::vector<ManagedObject*> objs = GetManagedObjectsVector();
      std::vector<const ManagedObject*> robjs = right.GetManagedObjectsVector();
      EDOC_ASSERT(objs.size() == robjs.size(), "");
      
      for (size_t i = 0; i < robjs.size(); i++)
      {
         EDOC_FOREACH_CONST(StrIDObjPMap, it, robjs[i]->items)
         {
            EDOC_Finer("Merging item: " << it->first);
            objs[i]->CAlwaysGet(it->first)->Merge(*it->second);
         }
      }

      #ifdef EDOC_ENABLE_VALIDATION
      Validate();
      #endif // EDOC_ENABLE_VALIDATION
   }
   //===========================================================================
   void Dictionary::Validate() const
   {
      // Ensure the predefined values are generated and correct.
      EDOC_ASSERT(UNKNOWN_FILE, "");
      EDOC_ASSERT(UNKNOWN_FILE->GetKeyName() == "", "");
      EDOC_ASSERT(files.Get(UNKNOWN_FILE->GetKeyName()) == UNKNOWN_FILE, "");

      EDOC_ASSERT(UNKNOWN_LOCATION, "");
      EDOC_ASSERT(!(*UNKNOWN_LOCATION), "");

      PStack stack;
      // @@@Brendon Update to use the managed object Validate instead of
      // accessing its private members directly.
      std::vector<const ManagedObject*> objs = GetManagedObjectsVector();
      for (size_t i = 0; i < objs.size(); i++)
      {
         objs[i]->Validate(stack, *this);
      }
      
      // @@@Brendon Any validation required for translation units?
   }
   //===========================================================================
   std::ostream& Dictionary::Print(std::ostream& out, std::string prefix) const
   {
      std::vector<const ManagedObject*> objs = GetManagedObjectsVector();
      for (size_t i = 0; i < objs.size(); i++)
      {
         objs[i]->Print(out, prefix);
      }

      return out;
   }
   //===========================================================================
   std::string Dictionary::ToString(std::string prefix) const
   {
      std::ostringstream stream;
      Print(stream, prefix);
      return stream.str();
   }
   //===========================================================================
   void Dictionary::Write(PersistenceIFace& file) const
   {
      // First we must give all functions and types a unique integer
      // identification number.
      uint32_t index = 0;
      std::vector<const ManagedObject*> objs = GetManagedObjectsVector();
      for (size_t i = 0; i < objs.size(); i++)
      {
         EDOC_FOREACH_CONST(StrIDObjPMap, it, objs[i]->items)
         {
            // Dont write the subst exception type to file.
            // The subst exception should only be used internally.
            // So should not be exported to file if an exception
            // references it and is exported to file then there is a bug
            // in the exception instance.
            if (it->second ==
               (StringIdentifiedObject*)SUBSTITUTION_EXCEPTION_TYPE)
            {
               continue;
            }
            EDOC_Finer("Giving index: " << index << " to item: " << it->first);
            it->second->index = index++;
            it->second->writing = true;
         }
      }

      file.WriteRecordType(VALUE_RECORD_TYPE_HEADER);
      file.WriteUInt8(KEY_EDOC_VERSION, EDOC_FILE_VERSION);

      file.WriteUInt32(KEY_TRANSLATION_UNITS_LS, translation_units.size());
      EDOC_FOREACH_CONST(TUnitPVec, it, translation_units)
      {
         file.WriteString(KEY_TRANSLATION_UNIT, (*it)->GetName());
      }

      for (size_t i = 0; i < objs.size(); i++)
      {
         // @@@Brendon Move this code into managed object?
         EDOC_FOREACH_CONST(StrIDObjPMap, it, objs[i]->items)
         {
            if (it->second == 
               (StringIdentifiedObject*)SUBSTITUTION_EXCEPTION_TYPE)
            {
               continue;
            }
            file.WriteRecordType(it->second->GetRecordType());
            file.WriteUInt32(KEY_INDEX, it->second->index);
            it->second->Write(file);
         }
      }

      // @@@Brendon This "writing" flag is not really a good idea. 
      // Reset the "writing" flag and indexes.
      objs = GetManagedObjectsVector();
      for (size_t i = 0; i < objs.size(); i++)
      {
         EDOC_FOREACH_CONST(StrIDObjPMap, it, objs[i]->items)
         {
            it->second->index = -1;
            it->second->writing = false;
         }
      }
   }
   //===========================================================================
   void Dictionary::ExpandCallGraph()
   {
      // Ensure that the functions which have had their addresses taken are
      // added to their corresponding types.
      UpdateFunctionAddressLists();

      // Expand the call graph for each function now that the derived virtuals
      // have been calculated.
      EDOC_FOREACH(StrIDObjPMap, it, functions.items)
      {
         dynamic_cast<Function*>(it->second)->ExpandCallGraph();
      }
      
      #ifdef EDOC_ENABLE_VALIDATION
      Validate();
      #endif // EDOC_ENABLE_VALIDATION
   }
   //===========================================================================
   void Dictionary::UpdateFunctionAddressLists()
   {
      EDOC_Fine("Cacheing all functions that have had their addresses taken.");

      // For each function type lets first erase its list of functions that have
      // had addresses taken.
      EDOC_FOREACH(StrIDObjPMap, it, function_types.items)
      {
         Erase(dynamic_cast<FunctionType*>(it->second)->addressed_functions);
         Erase(dynamic_cast<FunctionType*>(it->second)->equivilant);
      }

      
      // Update the equivilant lists for all function types.
      EDOC_FOREACH(StrIDObjPMap, it, function_types.items)
      {
         EDOC_FOREACH(StrIDObjPMap, it2, function_types.items)
         {
            if (dynamic_cast<FunctionType*>(it->second)->IsEquivilant(
               *dynamic_cast<FunctionType*>(it2->second)))
            {
               PushBackUnique(dynamic_cast<FunctionType*>(it->second)
                  ->equivilant, dynamic_cast<FunctionType*>(it2->second));
            }
         }
      }



      // For each function we will see if its address has been taken and if so
      // add it to the list for its type.
      EDOC_FOREACH(StrIDObjPMap, it, functions.items)
      {
         Function* func = dynamic_cast<Function*>(it->second);
         if (func->address_taken.size())
         {
            EDOC_Fine("Function: " << func->GetKeyName() 
               << " has its address taken and has been cached for type: " 
               << func->function_pointer_type->GetKeyName());
            
            for (size_t i = 0; i < 
               func->function_pointer_type->equivilant.size(); i++)
            {
               PushBackUnique(
                  func->function_pointer_type->equivilant[i]
                     ->addressed_functions, func);
            }
         }
      }
   }
   //===========================================================================
   // @@@Brendon Instead of doing special iteration over these i should just
   // make use of the GetCodeBlocks and use that as i am interested in a flat
   // view of it not the structured view.
   //===========================================================================
   static int CalculateTotalFunctionCalls(std::set<Function*>& processed, 
      std::vector<Function*>& curr_stack, 
      Function* f);
   //===========================================================================
   inline static int CalculateTotalFunctionCalls(
      std::set<Function*>& processed,
      std::vector<Function*>& curr_stack, 
      CodeBlock& cb)
   {
      int total_calls = 0;

      EDOC_FOREACH(FuncLocList, it, cb.function_calls)
      {
         total_calls += CalculateTotalFunctionCalls(processed, curr_stack, it->value);
      }
      
      EDOC_FOREACH(FuncLocList, it, cb.possible_function_calls)
      {
         total_calls += CalculateTotalFunctionCalls(processed, curr_stack, it->value);
      }
      
      EDOC_FOREACH(TryBlockList, it, cb.try_blocks)
      {
         total_calls += CalculateTotalFunctionCalls(processed, 
            curr_stack, *(*it).try_block);
         
         size_t len2 = it->catch_blocks.size();
         for (size_t j = 0; j < len2; j++)
         {
            total_calls += CalculateTotalFunctionCalls(processed, 
               curr_stack, *(*it).catch_blocks[j].catch_code);
         }
      }
      
      return total_calls;
   }
   //===========================================================================
   static int CalculateTotalFunctionCalls(
      std::set<Function*>& processed, 
      std::vector<Function*>& curr_stack, 
      Function* f)
   {
      // Note: The +1 is used to simplify the code a little. There is 
      // probably a better way to achieve it though. 
      //
      // It is to include the call to the
      // function currently being processed. In the case of the top level
      // function this means that there needs to be 1 subtracted from it as is
      // done in CalculatePropogatingExceptions()

      // Check to see if we have already included a count for this function
      if (processed.count(f))
      {
         // If we have, then we will not include it again,
         // however we will check to see if it is part of a
         // circular callgraph (for the top function) by checking to 
         // see if it is at the start of the current call stack.
         if (curr_stack.size() && *curr_stack.begin() == f)
         {
            // Then all functions from it to the end of the vector are part
            // of a circular callgraph.

            // First see if any of the functions have a circular set yet.
            // If so we will use that otherwise we will create one.
            std::set<Function*>* circular = NULL;
            std::set<std::set<Function*>* > to_merge;
            EDOC_FOREACH(std::vector<Function*>, jt, curr_stack)
            {
               if ((*jt)->circular)
               {
                  // If this is the first set instance, then 
                  // we will assume this is the instance we 
                  // will use
                  if (!circular)
                  {
                     circular = (*jt)->circular;
                  }
                  // If there are two set instances for the same circular
                  // function, then we should merge the two sets
                  // as they are part of one larger circular callgraph
                  else if ((*jt)->circular && circular != (*jt)->circular)
                  {
                     // Add to list to be merged and deleted
                     to_merge.insert((*jt)->circular);
                     
                     // No longer reference the old set but all 
                     // reference the same set now.
                     (*jt)->circular = NULL;
                  }
               }
            }

            // Merge contents of multiple "extra" sets into the 
            // single one referenced by "circular" and delete the
            // old sets that are no longer referenced.
            EDOC_FOREACH(std::set<std::set<Function*>* >, jt, to_merge)
            {
               EDOC_ASSERT(circular != *jt, "");
               EDOC_FOREACH(std::set<Function*>, kt, *(*jt))
               {
                  circular->insert(*kt);
                  EDOC_ASSERT((*kt)->circular == NULL || (*kt)->circular == *jt, "");
                  (*kt)->circular = NULL;
               }
               
               // delete the "extra" superfluous set.
               delete *jt;
            }
            Erase(to_merge);

            // Create a new circular set if none exists already.
            if (!circular)
            {
               circular = new std::set<Function*>();
            }

            // Now we add the items in the curr_stack to the set.
            EDOC_FOREACH(std::vector<Function*>, it, curr_stack)
            {
               circular->insert(*it);
            }
            
            // Finally we will set the circular member for each function
            // in the set to reference the single set.
            EDOC_FOREACH(std::set<Function*>, jt, *circular)
            {
               EDOC_ASSERT((*jt)->circular == NULL || (*jt)->circular == circular, "");
               (*jt)->circular = circular;
            }

            // We have now finished marking this function as part of a circular callgraph.
            EDOC_ASSERT(f->circular, "We never explicitly assigned to f->circuit but should have in the loop.");
         }

         return 0;
      }
      
      // Add this new function to the call stack and the processed set.
      processed.insert(f);
      curr_stack.push_back(f);
      
      // Count the functions that we call.
      int ret = CalculateTotalFunctionCalls(processed, curr_stack, f->implementation) + 1;

      // We are "exiting" this function so pop it off the call stack.
      EDOC_ASSERT(curr_stack.back() == f, "");
      curr_stack.pop_back();
      return ret;
   }
   //===========================================================================

   //===========================================================================
   void Dictionary::ErasePropogatingExceptions()
   {
      // Erase all propogating exception information.
      EDOC_FOREACH(StrIDObjPMap, it, functions.items)
      {
         Erase(dynamic_cast<Function*>(it->second)->propogating_exceptions);
         Erase(dynamic_cast<Function*>(it->second)->filtered_exceptions);


         dynamic_cast<Function*>(it->second)->
            calculated_propogating_exceptions = false;
         dynamic_cast<Function*>(it->second)->total_calls = -1;
         
         // Populate the originating exceptions function attribute.
         std::list<CodeBlock*> blocks = dynamic_cast<Function*>(
            it->second)->implementation.GetAllCodeBlocks();

         EDOC_FOREACH(CodeBlockPList, jt, blocks)
         {
            EDOC_FOREACH(ExcepList, kt, (*jt)->originating_exceptions)
            {
               kt->function = dynamic_cast<Function*>(it->second);
            }
         }
      }
   }
   //===========================================================================
   void Dictionary::CalculateCallComplexity(std::vector <Function*>& funcs)
   {
      // Before we try and calculate the prop exceptions lets try and sort the
      // list so that the funcs with the least dependencies are done first. This
      // will speed up execution a lot.
      
      // Classification is made based on hown many functions this function calls
      // both directly and indirectly.
      
      // The higher the count then the later this function is processed as it
      // most likely depends on functions that are processed before it. This
      // means we have as little "recalculation" as possible.
      funcs.resize(functions.items.size());

      EDOC_Debug("Calculating the callgraph complexity for each function.");
      size_t count = 0;
      EDOC_FOREACH(StrIDObjPMap, it, functions.items)
      {
         std::set<Function*> processed;
         std::vector<Function*> curr_stack;
         funcs[count] = dynamic_cast<Function*>(it->second);
         funcs[count]->total_calls = CalculateTotalFunctionCalls(
            processed, curr_stack, funcs[count]) - 1;
         count++;
      }
      
      EDOC_Debug("Sorting list of functions based on their "
         "callgraph complexity.");
      std::sort(funcs.begin(), funcs.end(), LessThanCallComplexity);
      for (size_t i = 0; i < funcs.size(); i++)
      {
         EDOC_Fine(i << ") calls: " << funcs[i]->total_calls << ": " 
            << funcs[i]->GetDeclaredName());
      }
   }
   //===========================================================================
   void Dictionary::CalculatePropogatingExceptions(
      std::vector <Function*>& sorted, FunctionProgressIFace* progress)
   {
      if (progress)
      {
         progress->Start(sorted.size());
      }
      
      // Calculate all propogating exception information from scratch using 
      // the now sorted list.
      for (size_t i = 0; i < sorted.size(); i++)
      {
         Function* func = sorted[i];
         EDOC_Fine("--------------------------------------------");
         EDOC_Fine("Calculating exceptions for function: " 
            << func->GetKeyName());
         //func->Print(std::cerr);

         // Process the functions callgraph to generate a list of
         // propogating exceptions.
         bool circular = GenerateExceptions(progress, *func);

         // If this function is in a circular callgraph that has
         // not yet been processed, then handle the circular callgraph
         // case.
         if (circular)
         {
            HandleCircularCallgraph(progress, *func);
         }
         
         // Now we have a complete list of exceptions, post process them
         // filtering out ones that dont match the functions exception 
         // spec and emitting warnings as necessary.
         PostProcessExceptions(*func);
         
         if (func->on_processed)
         {
            func->on_processed(*func, func->on_processed_data);
         }
      }

      
      #ifdef EDOC_ENABLE_VALIDATION
      std::cerr << "Checking data..." << std::endl;
      Validate();
      #endif // EDOC_ENABLE_VALIDATION
      return;
   }
   
   //===========================================================================
   bool Dictionary::GenerateExceptions(
      FunctionProgressIFace* progress, Function& function)
   {
      // Dont calculate propagating exceptions for a function that has already 
      // had it done.
      if (function.calculated_propogating_exceptions)
      {
         return false;
      }
      
      // Notify the user of progress.
      if (progress)
      {
         progress->Progress(&function);
      }
      
      EDOC_Finer("Entering: CalculatePropogatingExceptions");
      std::list<PropogatingException> poss_curr_catch_types;

      // @@@Brendon Maybe should not use UNKNOWN location but create a new 
      // location called NONE. I.e. this function is not being called but 
      // is being used to initiate the trace. So there is NO call location.
      FunctionLoc fl(*this, &function, *UNKNOWN_LOCATION);

      // This should be the only place a function loc has a true value for 
      // is_top_level
      fl.is_top_level = true;
      
      ProcessFunction(function, 
         fl,
         poss_curr_catch_types);
      fl.is_top_level = false;

      // mark this function as having had its exception list calculated.
      function.calculated_propogating_exceptions = true;
      
      return function.circular;
   }
   //===========================================================================
   void Dictionary::HandleCircularCallgraph(
      FunctionProgressIFace* progress, Function& function)
   {
      #warning "@@@Brendon emit a warning for circular callgraph possibly causing extra exceptions."
      EDOC_ASSERT(function.circular, "");
      
      // First we make sure that the other functions in the circular
      // callraph have been partially calculated.
      EDOC_FOREACH(std::set<Function*>, ft, *function.circular)
      {
         GenerateExceptions(progress, *(*ft));
      }

      // We then find the union of the propogating exceptions for all
      // the functions in the circle (not including the subst 
      // exceptions). 
      PropExcepPList all_exceps;
      EDOC_FOREACH(std::set<Function*>, ft, *function.circular)
      {
         EDOC_FOREACH(PropExcepList, jt, (*ft)->propogating_exceptions)
         {
            // If it isnt a subst exception, then add it to the list.
            if (jt->exception->type.value != SUBSTITUTION_EXCEPTION_TYPE)
            {
               PushBackUnique(all_exceps, &(*jt));
            }
         }
      }

      // Then for each subst exception we substitute the unioned list
      EDOC_FOREACH(std::set<Function*>, ft, *function.circular)
      {
         // Now perform the substitutions, creating propagating exception
         // instances from the list of Exception instances and the Propagating
         // exception instance used for the subst exception.
         std::list<PropogatingException> add;

         // Dont use foreach because we want to allow erasures.
         for(PropExcepList::iterator it = (*ft)->propogating_exceptions.begin();
            it != (*ft)->propogating_exceptions.end(); 
            /* no it++ */)
         {
            // For convenience.
            PropogatingException& p(*it);

            // Skip non-substitution exceptions. I.e. We dont do anything 
            // with them.
            if (p.exception->type.value != SUBSTITUTION_EXCEPTION_TYPE)
            {
               ++it;
               continue;
            }

            // Skip the ORIGINATING substitution exception.
            // We only substitute for propagating subst exceptions.
            // This is because the originating exception "...." that we add
            // to the function is not a real exception, we add it to
            // determine 
            // where exceptions MAY propagate through other functions in the 
            // recursive case. The orginal one is added for the sole purpose
            // of generating the propagating ones. The propagating ones tell
            // us where posible exceptions might come from. 
            if (p.orig_subst)
            {
               // Erase the subst exception.
               it = (*ft)->propogating_exceptions.erase(it);

               // Skip it++
               continue;
            }

            // Create from this subst prop excep a new prop excep for each
            // Exception* instance in its functions list.
            EDOC_FOREACH(PropExcepPList, jt, all_exceps)
            {
               PropogatingException p2(p);
               p2.exception = (*jt)->exception;
               
               // The possible and visible flags must be merged from both
               // the original prop excep and the propogating subst excep.
               
               // Since the subst prop excep is a "fake" then the merging rules
               // are a bit different here.
               // In particular, if eithre the original pexcep is "possible" or
               // the subst excep is "possible" then the result is possible.
               // Usually this would be an AND not an OR operation.

               // Likewise if the original is invisible OR the subst is
               // invisible then the result is invisible.
               p2.possible = (*jt)->possible | p.possible;
               p2.visible = (*jt)->visible & p.visible;
               
               add.push_back(p2);
            }

            // Erase the subst exception.
            it = (*ft)->propogating_exceptions.erase(it);

            // Skip it++
         }

         // Add unique exceptions defined in add
         AddExceptions((*ft)->propogating_exceptions, add);
      }
   }
   //===========================================================================
   void Dictionary::PostProcessExceptions(Function& function)
   {
      // Lets emit any necessary warnings and filter out exceptions
      // not permitted by the functions exception specifiers.
      // Debugging.
      EDOC_FOREACH(PropExcepList, it, function.propogating_exceptions)
      {
         EDOC_Debug("EMITS EXCEPTION: " 
            << it->exception->type.value->GetDeclaredName());
      }

      // Now we look at all propogating exceptions for this function and move
      // from propogating_list to filtered list any that do not match the 
      // functions throw spec. These will cause program aborts, but will not
      // propogate elsewhere.
      if (function.has_exception_spec)
      {
         // Dont use foreach because we want to allow erasures.
         for(PropExcepList::iterator it = 
               function.propogating_exceptions.begin();
            it != function.propogating_exceptions.end(); 
            /* no it++ */)
         {
            bool found = false;
            for (size_t j = 0; j < function.exception_spec.size(); j++)
            {
               if (it->exception->type.value->
                     IsCaughtBy(*function.exception_spec[j]))
               {
                  found = true;
                  break;
               }
            }

            // If it is not allowed by the specifier list, then remove it from
            // the propogating exceptions list and add it to the filtered list.
            if (!found)
            {
               function.filtered_exceptions.push_back(*it);
               it = function.propogating_exceptions.erase(it);

               // Skip it++
               continue;
            }

            it++;
         }
      }
   }
   //===========================================================================
   void Dictionary::ProcessFunction(
      Function& top,
      FunctionLoc& function,
      std::list<PropogatingException>& poss_curr_catch_types)
   {
      // Check to see if this function has already been processed.
      if (function.value->calculated_propogating_exceptions)
      {
         EDOC_Fine("Function has already been processed: " 
            << function.value->GetKeyName());
         return;
      }

      // If we are now starting to process a function that is part of 
      // a circular callgraph for the top function, then we will not
      // descend into it, rather we will just add a 
      // "recursive substitute exception" to the list and later we will
      // find all these functions and union their exception list and
      // re-calculate
      if (!function.is_top_level && top.circular &&
          top.circular->count(function.value))
      {
         // Handle the recursive function call case by adding a "...." 
         // substitute exception that represents the set of currently unknown
         // exception types that can be thrown by this function. 
         // Note: we only want to add it if it does not already exist.
         bool found = false;
         EDOC_FOREACH_CONST(std::list<PropogatingException>, it, 
            function.value->propogating_exceptions)
         {
            if (it->exception->type.value == SUBSTITUTION_EXCEPTION_TYPE)
            {
               found = true;
               break;
            }
         }
         
         if (!found)
         {
            // Then we will add the special substitution exception to the list
            // so that it looks like it originates from this function.
            FunctionLoc fl(*this, function.value, *UNKNOWN_LOCATION);
            
            // @@@Brendon Do i also make the propagating exception a possible
            // exception?
            PropogatingException p(*this, 
               &function.value->GetSubstException(), fl);
            
            // Mark the orig_subst flag to indicate
            // that it is the ORIGINAL substitution exception. The originating
            // one is never substituted, only propagating varients of it.
            // This is because if a propagating varient does not occur at the
            // top level then the subst exception has been completely filtered 
            // out.
            p.orig_subst = true;
            function.value->propogating_exceptions.push_back(p);
         }
         
         EDOC_Debug("The special recursion case has occured for a function: "
            << function.value->GetDeclaredName() << ":" 
            << (const void*)function.value);
         EDOC_Fine("Function is already in the processing stack not "
            "processing its exception list: " 
            << function.value->GetKeyName() << std::endl
            << "functions address: " << (void*)function.value);
         return;
      }

      EDOC_ASSERT(&top == function.value && function.is_top_level, "If the functions are calculated in the correct order and the circular callgraphs handled correctly, we should never encounter the case where a function is being called that has not been processed previously unless it is the top function.");

      EDOC_Finer("Entering: CalculatePropogatingExceptions for function: " 
         << function.value->GetDeclaredName());

      // Clear the current exceptions list as it may be a partial one.
      Erase(function.value->propogating_exceptions);
      Erase(function.value->filtered_exceptions);

      // If the function has no implementation and it is not a pure virtual with
      // children then dont process it as it will not have any exceptions.
      if (!function.value->processed_implementations &&
         !function.value->derived_virtuals.size())
      {
         EDOC_Fine("Function has no implementation returning without "
            "processing: " << function.value->GetKeyName());
         return;
      }

      // Calculate a list of all exceptions that emit from this functions main
      // code block.
      EDOC_Fine("Processing function: " << function.value->GetKeyName());
      ProcessCodeBlock(
         top,
         function.value->implementation, 
         function, 
         poss_curr_catch_types, 
         function.value->propogating_exceptions);

      return;
   }
   //===========================================================================
   void Dictionary::ProcessCodeBlock(
      Function& top,
      CodeBlock& block,
      FunctionLoc& function,
      std::list<PropogatingException>& poss_curr_catch_types,
      std::list<PropogatingException>& exceptions)
   {
      EDOC_Finer("Entering: ProcessCodeBlock");
      // Add originating exceptions to the list.
      // If the exception is ... then add all poss_curr_catch_types to the list
      // as well.
      EDOC_FOREACH(ExcepList, it, block.originating_exceptions)
      {
         EDOC_Fine("Function: " << function.value->GetKeyName() 
            << " has originating exception: " 
            << it->type.value->GetKeyName());
         AddOException(*this, exceptions, *it, poss_curr_catch_types);
      }

      std::list<FunctionLoc> fns = block.AllFunctionCalls();
      // For each function this block calls, obtain a list of its exceptions
      EDOC_FOREACH(FuncLocList, it, fns)
      {
         // If calling set_unexpected then emit a warning to the user indicating that we cant correctly handle this at the moment.
         if (it->value->GetKeyName() == "_ZSt14set_unexpectedPFvvE")
         {
            EDOC_NOTIFICATION(WSET_UNEXPECTED, "Function: " 
               << function.value->GetDeclaredName()
               << " is calling std::set_unexpected()",
               function.value, function.loc.file, function.loc.line, 
               NULL, 0, NULL, NULL, NULL, NULL);
         }
         
         // Make sure that we have the list of exceptions that can propogate 
         // from the function (Because of the processing order the only 
         // functions that should need processing from this point are ones 
         // in a circular callgraph).
         EDOC_Finer("Calcing exceptions for function : " 
            << it->value->GetDeclaredName() << " address: " << (void*)&(*it));
         ProcessFunction(top,
            (*it),
            poss_curr_catch_types);

         // @@@Brendon regarding virtual functions : It is all about the origin
         // of the exception. We dont want the parent funciton to be the origin
         // of all exceptions but have child as originator of its own
         // exceptions.
         // We will ignore the origin issue for now and assume all originate
         // from the parent function. This is MUCH simpler.


         // A functions derived virtuals have been added to the function as a
         // list of possible calls
         EDOC_Finer("Called function: " << (*it).value->GetDeclaredName() 
            << ", has exception count: " 
            << (*it).value->propogating_exceptions.size());
         
         // Add that functions exceptions to our list.
         EDOC_FOREACH(PropExcepList, kt, (*it).value->propogating_exceptions)
         {
            EDOC_Finer("Adding exception from function: " 
               << (*it).value->GetDeclaredName() << " to function: " 
               << function.value->GetDeclaredName());
            AddPException(*this, exceptions, *kt, *it, poss_curr_catch_types);
         }
      }

      // Process all try blocks.
      EDOC_FOREACH(TryBlockList, it, block.try_blocks)
      {
         EDOC_Fine("Number of exceptions before: " << exceptions.size());
         ProcessTryBlock(
            top,
            (*it),
            function,
            poss_curr_catch_types,
            exceptions);

         EDOC_Fine("Number of exceptions after: " << exceptions.size());
      }

      return;
   }

   //===========================================================================
   void Dictionary::ProcessTryBlock(
      Function& top,
      TryBlock& block,
      FunctionLoc& function,
      std::list<PropogatingException>& poss_curr_catch_types,
      std::list<PropogatingException>& exceptions)
   {
      EDOC_Finer("Entering: ProcessTryBlock");
      // Get the exceptions generated by the try block
      std::list<PropogatingException> try_exceptions;
      ProcessCodeBlock(top, *block.try_block, function, poss_curr_catch_types,
         try_exceptions);

      // Check for the MUST_NOT_THROW_EXPR case where a try block has NO catch
      // blocks we use this to mark that the try block MUST NOT THROW ANY
      // EXCEPTIONS if so it will cause a call to terminate()
      if (try_exceptions.size() && !block.catch_blocks.size())
      {
         EDOC_FOREACH(PropExcepList, it, try_exceptions)
         {
            EDOC_NOTIFICATION(ENOT_THROW, "Exception type: " 
               << it->exception->type.value->GetDeclaredName()
               << " propogates past a MUST_NOT_THROW_EXPR code block"
               " in function: " << function.value->GetDeclaredName(),
               function.value, function.loc.file, function.loc.line, 
               NULL, 0, NULL, &(*it), NULL, NULL);
         }
         return;
      }

      // For each catch block using the exceptions from the try block get a list
      // of matches to create a poss_curr_catch_types list.
      // Note: Order is important here.
      for (size_t i = 0; i < block.catch_blocks.size(); i++)
      {
         // Firstly lets get a list of all the e types that can be thrown by the
         // try block which can also be caught by the current catch block.
         TypeLoc catch_type = block.catch_blocks[i].catch_type;

         std::list<PropogatingException> types_caught;

         // Dont use foreach because we want to allow erasures.
         for(PropExcepList::iterator jt = try_exceptions.begin();
            jt != try_exceptions.end(); 
            /* no jt++ */)
         {
            // If exception is "...." and catch is "..." then treat
            // the exception as normal.
            if (jt->exception->
               type.value->IsCaughtBy(*catch_type.value))
            {
               EDOC_Fine("Caught exception: " 
                  << jt->exception->
                     type.value->GetDeclaredName());
               types_caught.push_back(*jt);

               // Erase it from the try_exceptions list.
               jt = try_exceptions.erase(jt);
               
               // Skip jt++
               continue;
            }
            else if (jt->exception->type.value == SUBSTITUTION_EXCEPTION_TYPE)
            {
               // If the exception is a subst exception "...." and it was not 
               // caught by the above handler (I.e. Handler was not of type ...)
               // Then we will "catch" it with this handler but not sink it.
               // I.e. we will process it as though it was caught but will 
               // assume that it will continue to propagate further on.
               
               // Push the exception on the back but do not erase it i.e. do not 
               // push its index onto the indexes list.
               types_caught.push_back(*jt);
            }
            
            jt++;
         }

         // If this catch block is usless in that it can not catch any
         // exceptions thrown in the try block, then warn the user. Also do not
         // process its code block.
         if (types_caught.size() == 0)
         {
            // Only warn if this is the top level funciton in the process stack.
            if (function.is_top_level)
            {
               EDOC_NOTIFICATION(WUNUSED_CATCH, 
                  "Catch block with type: " 
                  << catch_type.value->GetDeclaredName()
                  //<< " in function: " << function.value->GetDeclaredName()
                  << ", at location: " << catch_type.loc.GetNormalisedName()
                  << " is unable to catch any exceptions thrown from"
                  << " try block.",
                  function.value, catch_type.loc.file, catch_type.loc.line,
                  NULL, 0, catch_type.value, NULL, NULL, NULL);
            }
            
            // Dont make any use of the catch block so its exception
            // data/callgraphs are ignored since they will never occur.
         }
         else
         {
            // Now we process this catch block with the types_caught as
            // poss_curr_catch_types and append the exceptions that can leave it
            // to blocks_exceptions

            // Note: This replaces the poss_curr_catch_types not append to it as
            // there can only be 1 active exception at any time. So for example:
            //
            // try
            // {
            //    throw 3;
            // }
            // catch(int i)
            // {
            //    try
            //    {
            //       throw 2.0f;
            //    }
            //    catch(float f)
            //    {
            //       throw;
            //    }
            // }
            //
            // The rethrow is NOT able to rethrow the integer 3 but will rethrow
            // the float 2.0. This is why we do not append, but replace upon
            // entering the catch block.
            std::list<PropogatingException> catches_exceptions;
            ProcessCodeBlock(
               top,
               *block.catch_blocks[i].catch_code,
               function,
               types_caught,
               catches_exceptions);

            AddExceptions(exceptions, catches_exceptions);
         }

      }


      // Add whats left in the try_exceptions list to the blocks_exceptions
      AddExceptions(exceptions, try_exceptions);

      return;
   }
   //===========================================================================
   //@@@Brendon Possibly use special C++ type conversion functions.
   #define EDOC_REPLACE(DataType, Data, From, To, Count) \
      if ((void*)Data == From) {Data = (DataType*)To; Count++;}
   //===========================================================================
   size_t Dictionary::ReplaceReferences(PStack& stack, void* remove, 
      void* replace)
   {
      size_t count = 0;
      if (!stack.Push(this))
      {
         return count;
      }

      // @@@Brendon Update to use the managed object Validate instead of
      // accessing its private members directly.
      std::vector<ManagedObject*> objs = GetManagedObjectsVector();
      for (size_t i = 0; i < objs.size(); i++)
      {
         EDOC_FOREACH_CONST(StrIDObjPMap, it, objs[i]->items)
         {
            count += it->second->ReplaceReferences(stack, remove, replace);
         }
      }
      
      EDOC_REPLACE(File, UNKNOWN_FILE, remove, replace, count);
      
      return count;
   }
   //===========================================================================
   TranslationUnit* Dictionary::GetIndexedTranslationUnit(int32_t index)
   {
      if (index == -1)
      {
         return TranslationUnit::GetUnknown();
      }
      return translation_units[index];
   }
   //===========================================================================
   int32_t Dictionary::GetTranslationUnitIndex(TranslationUnit* tu)
   {
      for (size_t i = 0; i < translation_units.size(); i++)
      {
         //if(translation_units[i]->GetID() == tu->GetID())
         if(translation_units[i] == tu)
         {
            return i;
         }
      }
      
      if (tu == TranslationUnit::GetUnknown())
      {
         return -1;
      }

      EDOC_ASSERT(false, "Requested index of a translation unit that is not a part of this dictionary.");
      return 0;
   }
   //===========================================================================

}

---