diff --git a/doc/index.rst b/doc/index.rst index 77ef4a3e..ffe615b7 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -6,8 +6,8 @@ Usage ----- To use the C++ Format library, add ``format.h`` and ``format.cc`` from -a `release archive `__ -or the `Git repository `__ to your project. +a `release archive `_ +or the `Git repository `_ to your project. If you are using Visual C++ with precompiled headers, you might need to add the line @@ -25,6 +25,20 @@ 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. +Formatting functions +^^^^^^^^^^^^^^^^^^^^ + +The following functions use `format string syntax`_ similar to the one +used by Python's `str.format +`_ function. +They take *format_str* and *args* as arguments. + +*format_str* is a format string that contains literal text and replacement +fields surrounded by braces ``{}``. The fields are replaced with formatted +arguments in the resulting string. + +*args* is an argument list representing arbitrary arguments. + .. doxygenfunction:: fmt::format(StringRef, const ArgList &) .. doxygenfunction:: fmt::print(StringRef, const ArgList &) @@ -33,20 +47,25 @@ namespace is usually omitted in examples. .. doxygenfunction:: fmt::print(std::ostream &, StringRef, const ArgList &) -.. doxygendefine:: FMT_VARIADIC +Printf formatting functions +^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. doxygenclass:: fmt::BasicWriter - :members: +The following functions use `printf format string syntax +`_ with +a POSIX extension for positional arguments. -.. doxygenclass:: fmt::ArgList - :members: +.. doxygenfunction:: fmt::printf(StringRef, const ArgList &) -.. doxygenclass:: fmt::BasicStringRef - :members: +.. doxygenfunction:: fmt::fprintf(std::FILE *, StringRef, const ArgList &) + +.. doxygenfunction:: fmt::sprintf(StringRef, const ArgList &) Write API --------- +.. doxygenclass:: fmt::BasicWriter + :members: + .. doxygenfunction:: fmt::bin .. doxygenfunction:: fmt::oct @@ -59,6 +78,17 @@ Write API .. _formatstrings: +Utilities +--------- + +.. doxygendefine:: FMT_VARIADIC + +.. doxygenclass:: fmt::ArgList + :members: + +.. doxygenclass:: fmt::BasicStringRef + :members: + System Errors ------------- diff --git a/format.cc b/format.cc index c7405f99..ce9b90da 100644 --- a/format.cc +++ b/format.cc @@ -1248,21 +1248,15 @@ void fmt::report_windows_error( } #endif -void fmt::print(StringRef format, const ArgList &args) { +void fmt::print(std::FILE *f, StringRef format_str, const ArgList &args) { Writer w; - w.write(format, args); - std::fwrite(w.data(), 1, w.size(), stdout); -} - -void fmt::print(std::FILE *f, StringRef format, const ArgList &args) { - Writer w; - w.write(format, args); + w.write(format_str, args); std::fwrite(w.data(), 1, w.size(), f); } -void fmt::print(std::ostream &os, StringRef format, const ArgList &args) { +void fmt::print(std::ostream &os, StringRef format_str, const ArgList &args) { Writer w; - w.write(format, args); + w.write(format_str, args); os.write(w.data(), w.size()); } @@ -1274,10 +1268,10 @@ void fmt::print_colored(Color c, StringRef format, const ArgList &args) { std::fputs(RESET_COLOR, stdout); } -void fmt::printf(StringRef format, const ArgList &args) { +int fmt::fprintf(std::FILE *f, StringRef format, const ArgList &args) { Writer w; printf(w, format, args); - std::fwrite(w.data(), 1, w.size(), stdout); + return std::fwrite(w.data(), 1, w.size(), f); } // Explicit instantiations for char. diff --git a/format.h b/format.h index 64859490..94a17475 100644 --- a/format.h +++ b/format.h @@ -1745,21 +1745,11 @@ void print_colored(Color c, StringRef format, const ArgList &args); /** \rst - Formats a string similarly to Python's `str.format - `__ function - and returns the result as a string. - - *format_str* is a format string that contains literal text and replacement - fields surrounded by braces ``{}``. The fields are replaced with formatted - arguments in the resulting string. - - *args* is an argument list representing arbitrary arguments. + Formats arguments and returns the result as a string. **Example**:: std::string message = format("The answer is {}", 42); - - See also `Format String Syntax`_. \endrst */ inline std::string format(StringRef format_str, const ArgList &args) { @@ -1774,6 +1764,17 @@ inline std::wstring format(WStringRef format_str, const ArgList &args) { return w.str(); } +/** + \rst + Prints formatted data to the file *f*. + + **Example**:: + + print(stderr, "Don't {}!", "panic"); + \endrst + */ +void print(std::FILE *f, StringRef format_str, const ArgList &args); + /** \rst Prints formatted data to ``stdout``. @@ -1783,29 +1784,20 @@ inline std::wstring format(WStringRef format_str, const ArgList &args) { print("Elapsed time: {0:.2f} seconds", 1.23); \endrst */ -void print(StringRef format, const ArgList &args); +inline void print(StringRef format_str, const ArgList &args) { + print(stdout, format_str, args); +} /** \rst - Prints formatted data to a file. - - **Example**:: - - print(stderr, "Don't {}!", "panic"); - \endrst - */ -void print(std::FILE *f, StringRef format, const ArgList &args); - -/** - \rst - Prints formatted data to a stream. + Prints formatted data to the stream *os*. **Example**:: print(cerr, "Don't {}!", "panic"); \endrst */ -void print(std::ostream &os, StringRef format, const ArgList &args); +void print(std::ostream &os, StringRef format_str, const ArgList &args); template void printf(BasicWriter &w, @@ -1813,13 +1805,44 @@ void printf(BasicWriter &w, internal::PrintfFormatter().format(w, format, args); } +/** + \rst + Formats arguments and returns the result as a string. + + **Example**:: + + std::string message = fmt::sprintf("The answer is %d", 42); + \endrst +*/ inline std::string sprintf(StringRef format, const ArgList &args) { Writer w; printf(w, format, args); return w.str(); } -void printf(StringRef format, const ArgList &args); +/** + \rst + Prints formatted data to the file *f*. + + **Example**:: + + fmt::fprintf(stderr, "Don't %s!", "panic"); + \endrst + */ +int fprintf(std::FILE *f, StringRef format, const ArgList &args); + +/** + \rst + Prints formatted data to ``stdout``. + + **Example**:: + + fmt::printf("Elapsed time: %.2f seconds", 1.23); + \endrst + */ +inline int printf(StringRef format, const ArgList &args) { + return fprintf(stdout, format, args); +} /** Fast integer formatter. @@ -2032,7 +2055,8 @@ FMT_VARIADIC(void, print, std::FILE *, StringRef) FMT_VARIADIC(void, print, std::ostream &, StringRef) FMT_VARIADIC(void, print_colored, Color, StringRef) FMT_VARIADIC(std::string, sprintf, StringRef) -FMT_VARIADIC(void, printf, StringRef) +FMT_VARIADIC(int, printf, StringRef) +FMT_VARIADIC(int, fprintf, std::FILE *, StringRef) } // Restore warnings.