diff --git a/doc/conf.py b/doc/conf.py index cbd5512a..6c04afae 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -54,9 +54,9 @@ copyright = u'1990-2012, Python Software Foundation' # built documents. # # The short X.Y version. -version = '0.3' +version = '0.4' # The full version, including alpha/beta/rc tags. -release = '0.3' +release = '0.4' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/doc/format.rst b/doc/format.rst index 0b3b16f7..442441a9 100644 --- a/doc/format.rst +++ b/doc/format.rst @@ -10,6 +10,11 @@ String Formatting .. doxygenclass:: format::Formatter :members: +.. doxygenclass:: format::TempFormatter + :members: + +.. doxygenstruct:: format::NoAction + .. doxygenclass:: format::StringRef :members: diff --git a/format.h b/format.h index ccb1285a..c1553707 100644 --- a/format.h +++ b/format.h @@ -761,8 +761,11 @@ inline internal::ArgInserter Formatter::operator()(StringRef format) { return formatter; } -// A formatting action that does nothing. +/** + A formatting action that does nothing. + */ struct NoAction { + /** Does nothing. */ void operator()(const Formatter &) const {} }; @@ -793,25 +796,39 @@ class TempFormatter : public internal::ArgInserter { }; public: - // Creates an active formatter with a format string and an action. - // Action should be an unary function object that takes a const - // reference to Formatter as an argument. See Ignore and Write - // for examples of action classes. + /** + \rst + Constructs a temporary formatter with a format string and an action. + The action should be an unary function object that takes a const + reference to :cpp:class:`format::Formatter` as an argument. + See :cpp:class:`format::NoAction` and :cpp:class:`format::Write` for + examples of action classes. + \endrst + */ explicit TempFormatter(StringRef format, Action a = Action()) : action_(a) { Init(formatter_, format.c_str()); } + /** + Constructs a temporary formatter from a proxy object. + */ TempFormatter(const Proxy &p) : ArgInserter(0), action_(p.action) { Init(formatter_, p.format); } + /** + Performs the actual formatting, invokes the action and destroys the object. + */ ~TempFormatter() { if (formatter()) action_(*Format()); } + /** + Converts a temporary formatter into a proxy object. + */ operator Proxy() { const char *fmt = format(); ResetFormatter(); @@ -831,7 +848,7 @@ class TempFormatter : public internal::ArgInserter { **Example**:: - std::string message = str(Format("Elapsed time: {0:.2f} seconds") << 1.23); + std::string message = str(Format("The answer is {}") << 42); See also `Format String Syntax`_. \endrst