diff --git a/README.rst b/README.rst index 2fc617de..4b943e49 100644 --- a/README.rst +++ b/README.rst @@ -145,29 +145,6 @@ Write a file from a single thread: This is up to 6x faster than glibc's ``fprintf``. -Create your own functions similar to `format -`_ and -`print `_ -which take arbitrary arguments (`godbolt `_): - -.. code:: c++ - - // Prints formatted error message. - void vreport_error(const char* format, fmt::format_args args) { - fmt::print("Error: "); - fmt::vprint(format, args); - } - template - void report_error(const char* format, const Args & ... args) { - vreport_error(format, fmt::make_format_args(args...)); - } - - report_error("file not found: {}", path); - -Note that ``vreport_error`` is not parameterized on argument types which can -improve compile times and reduce code size compared to a fully parameterized -version. - Benchmarks ---------- diff --git a/doc/api.rst b/doc/api.rst index 28270144..157875dc 100644 --- a/doc/api.rst +++ b/doc/api.rst @@ -66,6 +66,33 @@ Named arguments are not supported in compile-time checks at the moment. Argument Lists -------------- +You can create your own formatting function with compile-time checks and small +binary footprint, for example (https://godbolt.org/z/oba4Mc): + +.. code:: c++ + + #include + + void vlog(const char* file, int line, fmt::string_view format, + fmt::format_args args) { + fmt::print("{}: {}: ", file, line); + fmt::vprint(format, args); + } + + template + void log(const char* file, int line, const S& format, Args&&... args) { + vlog(file, line, format, + fmt::make_args_checked(format, args...)); + } + + #define MY_LOG(format, ...) \ + log(__FILE__, __LINE__, FMT_STRING(format), __VA_ARGS__) + + MY_LOG("invalid squishiness: {}", 42); + +Note that ``vlog`` is not parameterized on argument types which improves compile +times and reduces binary code size compared to a fully parameterized version. + .. doxygenfunction:: fmt::make_format_args(const Args&...) .. doxygenfunction:: fmt::make_args_checked(const S&, const remove_reference_t&...) diff --git a/include/fmt/color.h b/include/fmt/color.h index b30dc031..f1b1f753 100644 --- a/include/fmt/color.h +++ b/include/fmt/color.h @@ -504,11 +504,15 @@ void vprint(std::FILE* f, const text_style& ts, const S& format, } /** + \rst Formats a string and prints it to the specified file stream using ANSI escape sequences to specify text formatting. - Example: + + **Example**:: + fmt::print(fmt::emphasis::bold | fg(fmt::color::red), "Elapsed time: {0:.2f} seconds", 1.23); + \endrst */ template ::value)> diff --git a/include/fmt/core.h b/include/fmt/core.h index 2792aef8..500184b6 100644 --- a/include/fmt/core.h +++ b/include/fmt/core.h @@ -1567,11 +1567,18 @@ inline format_arg_store make_format_args( return {args...}; } -/** Same as `make_format_args` but with compile-time format string checks. */ +/** + \rst + Constructs an `~fmt::format_arg_store` object that contains references + to arguments and can be implicitly converted to `~fmt::format_args`. + If ``format_str`` is a compile-time string then `make_args_checked` checks + its validity at compile time. + \endrst + */ template > -inline format_arg_store, remove_reference_t...> -make_args_checked(const S& format_str, - const remove_reference_t&... args) { +inline auto make_args_checked(const S& format_str, + const remove_reference_t&... args) + -> format_arg_store, remove_reference_t...> { static_assert( detail::count<( std::is_base_of>::value &&