include/EDoc/utils.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_UTILS_H
#define EDOC_UTILS_H

#include <string>
#include <vector>
#include <list>

/** \file utils.h This file provides some useful utilities that make using 
 * the STL containers a little simpler throughout the EDoc library.
 */
 
//==============================================================================
/** \brief A macro that can be used to loop for each element of a stl container.
 *
 * May be used like:
 * \code
 * typedef std::map<int, Blah> BlahMap;
 * BlahMap mymap;
 * ...
 * EDOC_FOREACH(BlahMap, it, mymap)
 * {
 *    ... do stuff with it->second ...
 * }
 * \endcode
 *
 * Important to note is that the typedef above is necessary in the EDOC_FOREACH
 * otherwise the macro will assume the comma in the map type is a sperator for
 * the macro. It is not necessary however for use with std::list and std::vector
 */
#define EDOC_FOREACH(ContainerType, IteratorName, ContainerObject) \
   for(ContainerType::iterator IteratorName = (ContainerObject).begin(); \
      IteratorName != (ContainerObject).end(); ++IteratorName)

//==============================================================================
/** \brief A macro that can be used to loop for each element of a const stl
 * container.
 */
#define EDOC_FOREACH_CONST(ContainerType, IteratorName, ContainerObject) \
   for(ContainerType::const_iterator IteratorName = (ContainerObject).begin(); \
      IteratorName != (ContainerObject).end(); ++IteratorName)

//==============================================================================
/** \brief A macro for marking function parameters as unused.
 *
 * This is used to eliminate the GCC warning for unused parameters when
 * compiled with that option.
 */
#define EDOC_UNUSED(Param)

//==============================================================================

namespace EDoc
{
   class Type;

   //---------------------------------------------------------------------------
   /** \brief used in a number of places within the Print() functions to provide
    * indentation.
    */
   static char const* const INDENT_STR = "\t";

   //---------------------------------------------------------------------------
   /** \brief Returns the extension of the given file name.
    *
    * I.e.: Thing.txt would return "txt"
    */
   std::string GetFileExtension(std::string name);

   //---------------------------------------------------------------------------
   /** \brief Returns both the extension and the base name of the given 
    * file name.
    *
    * I.e.: Thing.txt would return "Thing" and "txt"
    */
   std::pair<std::string, std::string> SplitFileExtension(std::string name);

   //---------------------------------------------------------------------------
   /** \brief Creates a new temporary file.
    *
    * Depending upon implementation this function may use the given base string
    * to construct the temporary file name. 
    */
   std::string CreateTempFilename(std::string base="EDoctmp");

   //---------------------------------------------------------------------------
   /** \brief Returns true if the given STL container contains an item.
    */
   template <typename T>
   inline bool ListContains(const T& cont, typename T::const_reference item)
   {
      EDOC_FOREACH_CONST(typename T, it, cont)
      {
         if (*it == item)
         {
            return true;
         }
      }
      
      return false;
   }

   //---------------------------------------------------------------------------
   /** \brief Returns an iterator for the item that matches.
    *
    * Most containers in STL have a .find() function. But apparently not
    * std::vector.
    */
   template <typename T>
   inline typename T::iterator VecFind(T& cont, typename T::const_reference item)
   {
      EDOC_FOREACH(typename T, it, cont)
      {
         if ((*it) == item)
         {
            return it;
         }
      }
      return cont.end();
   }

   //---------------------------------------------------------------------------
   /** \brief Pushes item to the back of the STL container if it does not 
    * already exist in the container.
    */
   template <typename T>
   inline void PushBackUnique(T& cont, typename T::const_reference item)
   {
      if (ListContains(cont, item))
      {
         return;
      }
      cont.push_back(item);
   }

   //---------------------------------------------------------------------------
   /** \brief Appends items from one STL container to the back of a seccond 
    * STL container if the items are not already in the second container.
    */
   template<typename T>
   inline void AppendUnique(T& cont1, const T& cont2)
   {
      EDOC_FOREACH_CONST(typename T, it, cont2)
      {
         PushBackUnique(cont1, *it);
      }
   }

   //---------------------------------------------------------------------------
   /** \brief Appends contents of STL container cont2 to the end of cont1.
    */
   template<typename T>
   inline T& Append(T& cont1, const T& cont2)
   {
      cont1.insert(cont1.end(), cont2.begin(), cont2.end());
      return cont1;
   }

   //---------------------------------------------------------------------------
   /** \brief Erases all items from the given container.
    */
   template<typename T>
   inline void Erase(T& cont)
   {
      cont.erase(cont.begin(), cont.end());
   }

   //---------------------------------------------------------------------------
   /** \brief Splits the given string into a vector of strings using sep as a
    * seperator.
    */
   std::vector<std::string> Split(std::string str, char sep = ' ');

   //---------------------------------------------------------------------------
   /** \brief Executes the given command and returns its exit status.
    */
   int RunProgram(std::string command_in);

   //---------------------------------------------------------------------------
   /** \brief Executes the given command and returns its exit status.
    */
   int RunProgramRedirect(std::string& out, std::string& err, std::string command);

   //---------------------------------------------------------------------------
   /** \brief Creates a directory structure if it does not exist.
    *
    * This is like mkdir -p
    */
   void MkDirs(std::string dir);

   //---------------------------------------------------------------------------
   /** \brief Copies source file to destination file.
    */
   void CopyFile(std::string source, std::string destination);

   //---------------------------------------------------------------------------
   /** \brief Returns true if the specified filename exists as a file.
    */
   bool FileExists(std::string filename);

   //---------------------------------------------------------------------------
   /** \brief Trims all whitespace from the beginning and end of the string.
    */
   std::string TrimWhitespace(const std::string& str);

   //---------------------------------------------------------------------------
   /** \brief Creates a temporary file on the system using the given template.
    */
   std::string MakeTemporaryFile(std::string prefix="", std::string suffix="", std::string directory="/tmp");

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

}

#endif // EDOC_UTILS_H

---