include/EDoc/PStack.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_PROCESSINGSTACK_H
#define EDOC_PROCESSINGSTACK_H

#include "EDoc/exceptions.h"

#include <ostream>
#include <sstream>
#include <list>

namespace EDoc
{
   //===========================================================================
   /** \brief Stores a stack of pointers that provides "set" like capabilities.
    *
    * This is primarily used to store a stack of pointers to ensure that while
    * processing data (Especially in
    * Dictionary::CalculatePropogatingExceptions()) that the code does not
    * enter a state of infinite recursion. 
    */
   class PStack
   {
   public:

      //------------------------------------------------------------------------
      /** \brief Returns the number of items in the stack.
       */
      size_t Size() const
      {
         return stack.size();
      }

      //------------------------------------------------------------------------
      /** \brief Returns true if the stack already contains the given pointer.
       */
      bool Contains(const void* item) const;

      //------------------------------------------------------------------------
      /** \brief Returns the index/location within the stack that the given 
       * pointer is located if it is in the stack or -1 if it is not in the 
       * stack.
       */
      ssize_t Location(const void* item) const;

      //------------------------------------------------------------------------
      /** \brief Push a pointer onto the stack returning false if it already
       * exists on the stack.
       */
      bool Push(const void* item);
      
      //------------------------------------------------------------------------
      /** \brief Pop a pointer from the top of the stack.
       *
       * \param item This is used for validation to ensure that we are popping
       * of the item we expect.
       *
       * \return Returns false if the top item in the stack does not have the
       * same value as the parameter item. If it returns false then it will NOT
       * pop anything off the stack.
       */
      bool Pop(const void* item);

      //------------------------------------------------------------------------
      /** \brief Print a list of items currently on the stack.
       *
       * Used for debugging purposes.
       */
      std::ostream& Print(std::ostream& out, std::string prefix="") const;
      
      //------------------------------------------------------------------------
      /** \brief Returns a string with the contents that would be displayed by
       * Print().
       */
      std::string ToString(std::string prefix="") const;

      //------------------------------------------------------------------------
      /** \brief Returns a reference to the internal list that is used to 
       * implement the stack.
       */
      inline const std::list<const void*>& GetInternal() const
      {
         return stack;
      }

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

   private:
   
      //------------------------------------------------------------------------
      /** \brief The list of pointers that comprises the stack.
       */
      std::list<const void*> stack;
      
      //------------------------------------------------------------------------
   };
   //===========================================================================
}

namespace std
{
   //===========================================================================
   /** \brief Overloaded instertion operator calls PStack::Print()
    */
   static inline std::ostream& operator<<(std::ostream& out, 
      const EDoc::PStack& value)
   {
      return value.Print(out);
   }
   //===========================================================================
}

#endif // EDOC_PROCESSINGSTACK_H

---