From 1e724a9d3380fdbadc9767a6884a6fd7a8191aff Mon Sep 17 00:00:00 2001 From: Victor Zverovich Date: Sun, 8 Sep 2013 15:37:14 -0700 Subject: [PATCH] Write docs. --- doc/index.rst | 10 +++--- format.h | 98 ++++++++++++++++++++++++++++++++++----------------- 2 files changed, 71 insertions(+), 37 deletions(-) diff --git a/doc/index.rst b/doc/index.rst index 34f413ef..6f472bfc 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -19,7 +19,7 @@ String Formatting API .. doxygenclass:: fmt::Write :members: -.. doxygenclass:: fmt::StringRef +.. doxygenclass:: fmt::BasicStringRef :members: .. doxygenfunction:: fmt::str @@ -190,8 +190,8 @@ sign-aware zero-padding for numeric types. This is equivalent to a *fill* character of ``'0'`` with an *alignment* type of ``'='``. The *precision* is a decimal number indicating how many digits should be -displayed after the decimal point for a floating point value formatted with -``'f'`` and ``'F'``, or before and after the decimal point for a floating point +displayed after the decimal point for a floating-point value formatted with +``'f'`` and ``'F'``, or before and after the decimal point for a floating-point value formatted with ``'g'`` or ``'G'``. For non-number types the field indicates the maximum field size - in other words, how many characters will be used from the field content. The *precision* is not allowed for integer values. @@ -225,7 +225,7 @@ The available integer presentation types are: +---------+----------------------------------------------------------+ | Type | Meaning | +=========+==========================================================+ - | ``'d'`` | Decimal Integer. Outputs the number in base 10. | + | ``'d'`` | Decimal integer. Outputs the number in base 10. | +---------+----------------------------------------------------------+ | ``'o'`` | Octal format. Outputs the number in base 8. | +---------+----------------------------------------------------------+ @@ -238,7 +238,7 @@ The available integer presentation types are: | none | The same as ``'d'``. | +---------+----------------------------------------------------------+ -The available presentation types for floating point values are: +The available presentation types for floating-point values are: +---------+----------------------------------------------------------+ | Type | Meaning | diff --git a/format.h b/format.h index 99adaad6..2d18b992 100644 --- a/format.h +++ b/format.h @@ -214,7 +214,7 @@ class BasicStringRef { public: /** Constructs a string reference object from a C string and a size. - If `size` is zero, which is the default, the size is computed with + If *size* is zero, which is the default, the size is computed with `strlen`. */ BasicStringRef(const Char *s, std::size_t size = 0) : data_(s), size_(size) {} @@ -406,9 +406,37 @@ template class BasicFormatter; /** + \rst This template provides operations for formatting and writing data into a character stream. The output is stored in a memory buffer that grows dynamically. + + You can use one of the following typedefs for common character types: + + +---------+----------------------+ + | Type | Definition | + +=========+======================+ + | Writer | BasicWriter | + +---------+----------------------+ + | WWriter | BasicWriter | + +---------+----------------------+ + + **Example**:: + + Writer out; + out << "The answer is " << 42 << "\n"; + out.Format("({:+f}, {:+f})") << -3.14 << 3.14; + + This will write the following output to the ``out`` object: + + .. code-block:: none + + The answer is 42 + (-3.140000, +3.140000) + + The output can be converted to an ``std::string`` with ``out.str()`` or + accessed as a C string with ``out.c_str()``. + \endrst */ template class BasicWriter { @@ -454,7 +482,7 @@ class BasicWriter { *this << IntFormatter(value, spec); } - // Formats a floating point number (double or long double). + // Formats a floating-point number (double or long double). template void FormatDouble(T value, const FormatSpec &spec, int precision); @@ -492,6 +520,32 @@ class BasicWriter { return std::basic_string(&buffer_[0], buffer_.size()); } + /** + \rst + Formats a string sending the output to the writer. Arguments are + accepted through the returned ``BasicFormatter`` object using inserter + operator ``<<``. + + **Example**:: + + Writer out; + out.Format("Current point:\n"); + out.Format("({:+f}, {:+f})") << -3.14 << 3.14; + + This will write the following output to the ``out`` object: + + .. code-block:: none + + Current point: + (-3.140000, +3.140000) + + The output can be accessed using :meth:`data` or :meth:`c_str`. + + See also `Format String Syntax`_. + \endrst + */ + BasicFormatter Format(StringRef format); + BasicWriter &operator<<(int value) { return *this << IntFormatter >(value, TypeSpec<0>()); } @@ -502,11 +556,19 @@ class BasicWriter { BasicWriter &operator<<(long value) { return *this << IntFormatter >(value, TypeSpec<0>()); } + + /** + Formats *value* and writes it to the stream. + */ BasicWriter &operator<<(unsigned long value) { return *this << IntFormatter >(value, TypeSpec<0>()); } + /** + Formats *value* using the general format for floating-point numbers + (``'g'``) and writes it to the stream. + */ BasicWriter &operator<<(double value) { FormatDouble(value, FormatSpec(), -1); return *this; @@ -530,30 +592,6 @@ class BasicWriter { FormatString(s.data(), s.size(), spec); } - /** - \rst - Formats a string sending the output to the writer. Arguments are - accepted through the returned `BasicFormatter` object using inserter - operator `<<`. - - **Example**:: - - Writer out; - out.Format("Current point:\n"); - out.Format("({:+f}, {:+f})") << -3.14 << 3.14; - - This will write the following output to the ``out`` object: - - .. code-block:: none - - Current point: - (-3.140000, +3.140000) - - The output can be accessed using :meth:`data` or :meth:`c_str`. - \endrst - */ - BasicFormatter Format(StringRef format); - void Clear() { buffer_.clear(); } @@ -990,9 +1028,7 @@ class Formatter : private Action, public BasicFormatter { inactive_(false) { } - /** - Constructs a formatter from a proxy object. - */ + // Constructs a formatter from a proxy object. Formatter(const Proxy &p) : Action(p.action), BasicFormatter(writer_, p.format), inactive_(false) { @@ -1008,9 +1044,7 @@ class Formatter : private Action, public BasicFormatter { } } - /** - Converts the formatter into a proxy object. - */ + // Converts the formatter into a proxy object. operator Proxy() { inactive_ = true; return Proxy(this->TakeFormatString(), *this);