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 */