From 9d5905707a902543fcc6504b82990873ab14ed52 Mon Sep 17 00:00:00 2001 From: Victor Zverovich Date: Sun, 29 Jun 2014 11:51:27 -0700 Subject: [PATCH] Update docs. --- README.rst | 39 ++++++++++++++++--------------- doc/Doxyfile | 1 + doc/index.rst | 63 +++++++++++++++++++++------------------------------ 3 files changed, 46 insertions(+), 57 deletions(-) diff --git a/README.rst b/README.rst index 85dff37a..08e7b45c 100644 --- a/README.rst +++ b/README.rst @@ -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 -`__ -to create your own functions similar to `Format -`__ and -`Print `__ -with an arbitrary action performed when formatting is complete: +You can use the `FMT_VARIADIC +`__ +macro to create your own functions similar to `format +`__ and +`print `__ +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 ReportError(const char *format) { - fmt::Formatter 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 `__: 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 `__ or by submitting an `issue `__. diff --git a/doc/Doxyfile b/doc/Doxyfile index fd1b5d24..d4b4a757 100644 --- a/doc/Doxyfile +++ b/doc/Doxyfile @@ -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 \ diff --git a/doc/index.rst b/doc/index.rst index a94f77a8..51d331e0 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -9,7 +9,7 @@ To use the C++ Format library, add ``format.h`` and ``format.cc`` from a `release archive `__ or the `Git repository `__ 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::