mirror/fmt
1
0
Fork 0
mirror of https://github.com/fmtlib/fmt.git synced 2024-12-24 03:17:53 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update docs.

Browse Source
This commit is contained in:
Victor Zverovich 2014-06-29 11:51:27 -07:00
parent a1264926a0
commit 9d5905707a
3 changed files with 46 additions and 57 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

39
README.rst
View File

@ -60,7 +60,7 @@ Arguments can be accessed by position and arguments' indices can be repeated:
.. code-block:: c++
std::string s = str(fmt::Format("{0}{1}{0}") << "abra" << "cad");
std::string s = str(fmt::format("{0}{1}{0}", "abra", "cad"));
// s == "abracadabra"
C++ Format can be used as a safe portable replacement for ``itoa``:
@ -87,31 +87,30 @@ An object of any user-defined type for which there is an overloaded
}
};
std::string s = str(fmt::Format("The date is {}") << Date(2012, 12, 9));
std::string s = str(fmt::format("The date is {}", Date(2012, 12, 9)));
// s == "The date is 2012-12-9"
You can use `Formatter
<http://cppformat.github.io/doc/latest/#project0classfmt_1_1_formatter>`__
to create your own functions similar to `Format
<http://cppformat.github.io/doc/latest#fmt::Format__StringRef>`__ and
`Print <http://cppformat.github.io/doc/latest#fmt::Print__StringRef>`__
with an arbitrary action performed when formatting is complete:
You can use the `FMT_VARIADIC
<http://cppformat.github.io/doc/latest/#project0format_8h_1a65215c7dfcc0e942cd0798860877e86b>`__
macro to create your own functions similar to `format
<http://cppformat.github.io/doc/latest#fmt::format__StringRef.ArgListCR>`__ and
`print <http://cppformat.github.io/doc/latest#fmt::print__StringRef.ArgListCR>`__
which take arbitrary arguments:
.. code-block:: c++
struct PrintError {
void operator()(const fmt::Writer &w) const {
std::cerr << "Error: " << w.str() << std::endl;
}
};
// Formats an error message and prints it to std::cerr.
fmt::Formatter<PrintError> ReportError(const char *format) {
fmt::Formatter<PrintError> f(format);
return f;
// Prints formatted error message to std::cerr.
void ReportError(const char *format_str, const fmt::ArgList &args) {
std::cerr << "Error: " << fmt::format(format_str, args) << std::endl;
}
FMT_VARIADIC(void, ReportError)
ReportError("File not found: {}") << path;
ReportError("File not found: {}", path);
Note that you only need to define one function that takes `const fmt::ArgList &`
argument and `FMT_VARIADIC` automatically defines necessary wrappers that
accept variable number of arguments. These wrappers are simple inline functions
that are very fast and don't result in code bloat.
Projects using this library
---------------------------
@ -126,7 +125,7 @@ Projects using this library
* `HarpyWar/pvpgn <https://github.com/HarpyWar/pvpgn>`__:
Player vs Player Gaming Network with tweaks
If you are aware of other projects using ``format``, please let me know
If you are aware of other projects using this library, please let me know
by `email <mailto:victor.zverovich@gmail.com>`__ or by submitting an
`issue <https://github.com/cppformat/cppformat/issues>`__.

1
doc/Doxyfile
View File

@ -13,6 +13,7 @@ XML_OUTPUT = doxyxml
ALIASES = "rst=\verbatim embed:rst"
ALIASES += "endrst=\endverbatim"
PREDEFINED = _WIN32=1 \
FMT_NO_DEPRECATED=1 \
FMT_USE_VARIADIC_TEMPLATES=1 \
FMT_USE_RVALUE_REFERENCES=1
EXCLUDE_SYMBOLS = fmt::internal::* VFormat ArgInfo BasicArg CustomValue FormatParser \

63
doc/index.rst
View File

@ -9,7 +9,7 @@ To use the C++ Format library, add ``format.h`` and ``format.cc`` from
a `release archive <https://github.com/cppformat/cppformat/releases/latest>`__
or the `Git repository <https://github.com/cppformat/cppformat>`__ to your project.
If you are using Visual Studio with precompiled headers, you might need to add
If you are using Visual C++ with precompiled headers, you might need to add
the line
::
@ -25,36 +25,23 @@ All functions and classes provided by the C++ Format library reside
in namespace ``fmt`` and macros have prefix ``FMT_``. For brevity the
namespace is usually omitted in examples.
.. doxygenfunction:: fmt::Format(StringRef)
.. doxygenfunction:: fmt::format(StringRef, const ArgList &)
.. doxygenfunction:: fmt::Format(StringRef, const Args &...)
.. doxygenfunction:: fmt::print(StringRef, const ArgList &)
.. doxygenfunction:: fmt::Print(StringRef)
.. doxygenfunction:: fmt::print(std::FILE *, StringRef, const ArgList &)
.. doxygenfunction:: fmt::Print(std::FILE *, StringRef)
.. doxygendefine:: FMT_VARIADIC
.. doxygenclass:: fmt::BasicWriter
:members:
.. doxygenclass:: fmt::BasicFormatter
:members:
.. doxygenclass:: fmt::Formatter
:members:
.. doxygenclass:: fmt::NullSink
:members:
.. doxygenclass:: fmt::FileSink
.. doxygenclass:: fmt::ArgList
:members:
.. doxygenclass:: fmt::BasicStringRef
:members:
.. doxygenfunction:: fmt::str(StringRef)
.. doxygenfunction:: fmt::c_str(StringRef)
Write API
---------
@ -83,8 +70,8 @@ System Errors
Format String Syntax
--------------------
The :cpp:func:`fmt::Format()` function and the :cpp:class:`fmt::Formatter`
class share the same syntax for format strings.
Formatting functions such as :cpp:func:`fmt::format()` and :cpp:func:`fmt::print()`
use the same format string syntax described in this section.
Format strings contain "replacement fields" surrounded by curly braces ``{}``.
Anything that is not contained in braces is considered literal text, which is
@ -140,10 +127,12 @@ Format Specification Mini-Language
"Format specifications" are used within replacement fields contained within a
format string to define how individual values are presented (see
:ref:`formatstrings`). They can also be passed directly to the
:func:`Format` function. Each formattable type may define how the format
:ref:`formatstrings`). Each formattable type may define how the format
specification is to be interpreted.
..
They can also be passed directly to the :func:`format` function.
Most built-in types implement the following options for format specifications,
although some of the formatting options are only supported by the numeric types.
@ -384,48 +373,48 @@ following examples.
Accessing arguments by position::
Format("{0}, {1}, {2}") << 'a' << 'b' << 'c';
format("{0}, {1}, {2}", 'a', 'b', 'c');
// Result: "a, b, c"
Format("{}, {}, {}") << 'a' << 'b' << 'c';
format("{}, {}, {}", 'a', 'b', 'c)';
// Result: "a, b, c"
Format("{2}, {1}, {0}") << 'a' << 'b' << 'c';
format("{2}, {1}, {0}", 'a', 'b', 'c');
// Result: "c, b, a"
Format("{0}{1}{0}") << "abra" << "cad"; // arguments' indices can be repeated
format("{0}{1}{0}", "abra", "cad"); // arguments' indices can be repeated
// Result: "abracadabra"
Aligning the text and specifying a width::
Format("{:<30}") << "left aligned";
format("{:<30}", "left aligned");
// Result: "left aligned "
Format("{:>30}") << "right aligned"
format("{:>30}", "right aligned");
// Result: " right aligned"
Format("{:^30}") << "centered"
format("{:^30}", "centered");
// Result: " centered "
Format("{:*^30}") << "centered" // use '*' as a fill char
format("{:*^30}", "centered"); // use '*' as a fill char
// Result: "***********centered***********"
Replacing ``%+f``, ``%-f``, and ``% f`` and specifying a sign::
Format("{:+f}; {:+f}") << 3.14 << -3.14; // show it always
format("{:+f}; {:+f}", 3.14, -3.14); // show it always
// Result: "+3.140000; -3.140000"
Format("{: f}; {: f}") << 3.14 << -3.14; // show a space for positive numbers
format("{: f}; {: f}", 3.14, -3.14); // show a space for positive numbers
// Result: " 3.140000; -3.140000"
Format("{:-f}; {:-f}") << 3.14 << -3.14; // show only the minus -- same as '{:f}; {:f}'
format("{:-f}; {:-f}", 3.14, -3.14); // show only the minus -- same as '{:f}; {:f}'
// Result: "3.140000; -3.140000"
Replacing ``%x`` and ``%o`` and converting the value to different bases::
Format("int: {0:d}; hex: {0:x}; oct: {0:o}; bin: {0:b}") << 42;
format("int: {0:d}; hex: {0:x}; oct: {0:o}; bin: {0:b}", 42);
// Result: "int: 42; hex: 2a; oct: 52; bin: 101010"
// with 0x or 0 or 0b as prefix:
Format("int: {0:d}; hex: {0:#x}; oct: {0:#o}; bin: {0:#b}") << 42;
format("int: {0:d}; hex: {0:#x}; oct: {0:#o}; bin: {0:#b}", 42);
// Result: "int: 42; hex: 0x2a; oct: 052; bin: 0b101010"
.. ifconfig:: False
Using the comma as a thousands separator::
Format("{:,}") << 1234567890)
format("{:,}", 1234567890);
'1,234,567,890'
Expressing a percentage::