std.check.src.formatter.hpp: src/formatter.hpp

/*!
  \file formatter.hpp
  \brief Header file which provides text formatting ability.
*/
#ifndef CHECK_FORMATTER_HPP
#define CHECK_FORMATTER_HPP

#include 
#include 
#include 
#include 


namespace Check
{


/*!
  \ingroup text

  \brief The %Formatter class provides basic functions for writing information
  to a string with full control to its formatting.

  The %Formatter class was introduced to handle standard printf formatting for
  dynamic strings in a safe way. Additionally, in future versions this class
  will have a functional interface similar to that of the standard C++
  \e ostringstream class.
*/
class Formatter
{
private:
  enum { DefaultBufferSize = 128, MaxBufferSize = 1024 };

  std::string str;
  char *buffer;
  size_t bufferSize;

  void allocateBuffer(const size_t newSize);
  void deallocateBuffer() { free(buffer); buffer = NULL; bufferSize = 0; }

public:
  /*!
    Constructs a text stream that operates on string initialized with \a text.

    \see text() and clear()
  */
  Formatter(const char *text = NULL)
    : str(text != NULL ? text : ""), buffer(NULL), bufferSize(0)
  { allocateBuffer(DefaultBufferSize); }

  /*!
    This is an overloaded member function, provided for convenience.

    Constructs a text stream that operates on string initialized with \a text.

    \see text() and clear()
  */
  Formatter(const std::string text)
    : str(text), buffer(NULL), bufferSize(0)
  { allocateBuffer(DefaultBufferSize); }

  //! Destroys the text stream.
  ~Formatter() { deallocateBuffer(); }

  /*!
    Returns current state of the text stream stored in a \c std::string object.

    \see clear()
  */
  const std::string &text() const { return str; }

  //! Ensures that at least \a length characters are allocated to the text.
  void reserve(const size_t length) { str.reserve(length); }

  //! Removes all information from the text stream. \see text()
  void clear() { str.clear(); }

  /*!
    Similar to print() except for the way arguments passed.

    Unlike print() arguments passed as a list of pointers \c va_list.

    \see print()
  */
  Formatter &printArgs(const char *format, const va_list argList);

  /*!
    Safely builds a formatted string from the printf format string \a format
    and an arbitrary list of arguments.

    \see printArgs()
  */
  Formatter &print(const char *format, ...);
};


/*!
  \ingroup text
  \relates Formatter

  This function behaves essentially like Formatter::printArgs() and
  provided for convenience.

  \see Formatter::printArgs() and format()
*/
inline std::string formatArgs(const char *format, const va_list argList)
{ return Formatter().printArgs(format, argList).text(); }

/*!
  \ingroup text
  \relates Formatter

  This function behaves essentially like Formatter::print() and
  provided for convenience.

  \see Formatter::print() and formatArgs()
*/
std::string format(const char *format, ...);


namespace Auxiliary
{


extern const size_t DefaultQuoteLookSize;


std::string quote(
  const char *text, const size_t length,
  const size_t index, const size_t lookSize);


}


/*!
  \ingroup text

  Quotes at most \a lookSize first characters of string \a text and returns it
  as \c std::string object.
*/
inline std::string quote(
  const char *text, const size_t lookSize = Auxiliary::DefaultQuoteLookSize)
{ return Auxiliary::quote(text, std::strlen(text), 0, lookSize); }


/*!
  \ingroup text

  This is an overloaded function, provided for convenience.

  Quotes at most \a lookSize characters of string \a text around
  position \a index and returns it as \c std::string object.
*/
inline std::string quote(
  const std::string &text, const size_t index = 0,
  const size_t lookSize = Auxiliary::DefaultQuoteLookSize)
{ return Auxiliary::quote(text.c_str(), text.length(), index, lookSize); }


}

#endif /* CHECK_FORMATTER_HPP */