From 97117cbb51ce83905736ef4287645c99adba646c Mon Sep 17 00:00:00 2001 From: Victor Zverovich Date: Sun, 2 Jun 2024 12:21:11 -0700 Subject: [PATCH] Migrate to mkdocs --- doc/api.md | 58 +++++++++++++-------------- include/fmt/args.h | 4 +- include/fmt/color.h | 10 ++--- include/fmt/compile.h | 2 +- include/fmt/format.h | 93 ++++++++++++++++++------------------------- include/fmt/os.h | 4 +- include/fmt/ostream.h | 4 +- include/fmt/printf.h | 6 +-- include/fmt/ranges.h | 36 ++++++++--------- 9 files changed, 98 insertions(+), 119 deletions(-) diff --git a/doc/api.md b/doc/api.md index d1d6fd4a..7b26df47 100644 --- a/doc/api.md +++ b/doc/api.md @@ -41,10 +41,10 @@ in Python. They take *fmt* and *args* as arguments. *fmt* 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. [\~fmt::format_string]{.title-ref} is a format string -which can be implicitly constructed from a string literal or a `constexpr` -string and is checked at compile time in C++20. To pass a runtime format -string wrap it in [fmt::runtime]{.title-ref}. +in the resulting string. [`fmt::format_string`](#format_string) is a format +string which can be implicitly constructed from a string literal or a +`constexpr` string and is checked at compile time in C++20. To pass a runtime +format string wrap it in [fmt::runtime](#runtime). *args* is an argument list representing objects to be formatted. @@ -52,7 +52,6 @@ I/O errors are reported as [`std::system_error`]( https://en.cppreference.com/w/cpp/error/system_error) exceptions unless specified otherwise. - ::: print(format_string, T&&...) ::: print(FILE*, format_string, T&&...) @@ -100,7 +99,7 @@ Example ([run](https://godbolt.org/z/nvME4arz8)): } int main() { - fmt::print("{}\n", kevin_namespacy::film::se7en); // prints "7" + fmt::print("{}\n", kevin_namespacy::film::se7en); // Output: 7 } Using specialization is more complex but gives you full control over @@ -154,7 +153,7 @@ fmt::format("{:>10}", color::blue) will return `" blue"`. -The experimental `nested_formatter` provides an easy way of applying a + In general the formatter has the following form: @@ -232,10 +231,10 @@ struct B : A { }; template -struct fmt::formatter::value, char>> : +struct fmt::formatter, char>> : fmt::formatter { auto format(const A& a, format_context& ctx) const { - return fmt::formatter::format(a.name(), ctx); + return formatter::format(a.name(), ctx); } }; ``` @@ -248,12 +247,18 @@ struct fmt::formatter::value, char>> : int main() { B b; A& a = b; - fmt::print("{}", a); // prints "B" + fmt::print("{}", a); // Output: B } ``` -Providing both a `formatter` specialization and a `format_as` overload -is disallowed. +Providing both a `formatter` specialization and a `format_as` overload is +disallowed. + +::: basic_format_parse_context + +::: context + +::: format_context ### Compile-Time Format String Checks @@ -311,12 +316,6 @@ parameterized version. ::: basic_format_arg -::: basic_format_parse_context - -::: context - -::: format_context - ### Compatibility ::: basic_string_view @@ -368,7 +367,7 @@ The following user-defined literals are defined in `fmt/format.h`. The {fmt} library supports custom dynamic memory allocators. A custom allocator class can be specified as a template argument to -`fmt::basic_memory_buffer`{.interpreted-text role="class"}: +[`fmt::basic_memory_buffer`](#basic_memory_buffer): using custom_memory_buffer = fmt::basic_memory_buffer; @@ -439,18 +438,16 @@ The library also supports convenient formatting of ranges and tuples: #include - std::tuple t{'a', 1, 2.0f}; - // Prints "('a', 1, 2.0)" - fmt::print("{}", t); + fmt::print("{}", std::tuple{'a', 42}); + // Output: ('a', 42) -Using `fmt::join`, you can separate tuple elements with a custom -separator: +Using `fmt::join`, you can separate tuple elements with a custom separator: #include - std::tuple t = {1, 'a'}; - // Prints "1, a" + auto t = std::tuple{1, 'a'}; fmt::print("{}", fmt::join(t, ", ")); + // Output: 1, a ::: join(Range&&, string_view) @@ -475,16 +472,17 @@ chrono-format-specifications). int main() { std::time_t t = std::time(nullptr); - // Prints "The date is 2020-11-07." (with the current date): fmt::print("The date is {:%Y-%m-%d}.", fmt::localtime(t)); + // Output: The date is 2020-11-07. + // (with 2020-11-07 replaced by the current date) using namespace std::literals::chrono_literals; - // Prints "Default format: 42s 100ms": fmt::print("Default format: {} {}\n", 42s, 100ms); + // Output: Default format: 42s 100ms - // Prints "strftime-like format: 03:15:30": fmt::print("strftime-like format: {:%H:%M:%S}\n", 3h + 15min + 30s); + // Output: strftime-like format: 03:15:30 } ::: localtime(std::time_t) diff --git a/include/fmt/args.h b/include/fmt/args.h index f6713859..390393c8 100644 --- a/include/fmt/args.h +++ b/include/fmt/args.h @@ -159,7 +159,7 @@ class dynamic_format_arg_store Note that custom types and string types (but not string views) are copied into the store dynamically allocating memory if necessary. - **Example**:: + **Example**: fmt::dynamic_format_arg_store store; store.push_back(42); @@ -180,7 +180,7 @@ class dynamic_format_arg_store Adds a reference to the argument into the dynamic store for later passing to a formatting function. - **Example**:: + **Example**: fmt::dynamic_format_arg_store store; char band[] = "Rolling Stones"; diff --git a/include/fmt/color.h b/include/fmt/color.h index 25ee275f..5addb18e 100644 --- a/include/fmt/color.h +++ b/include/fmt/color.h @@ -478,7 +478,7 @@ inline void vprint(FILE* f, const text_style& ts, string_view fmt, 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); @@ -495,7 +495,7 @@ void print(FILE* f, const text_style& ts, format_string fmt, Formats a string and prints it to stdout 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); @@ -518,7 +518,7 @@ inline auto vformat(const text_style& ts, string_view fmt, format_args args) Formats arguments and returns the result as a string using ANSI escape sequences to specify text formatting. - **Example**:: + **Example**: #include std::string message = fmt::format(fmt::emphasis::bold | fg(fmt::color::red), @@ -548,7 +548,7 @@ auto vformat_to(OutputIt out, const text_style& ts, string_view fmt, Formats arguments with the given text_style, writes the result to the output iterator ``out`` and returns the iterator past the end of the output range. - **Example**:: + **Example**: std::vector out; fmt::format_to(std::back_inserter(out), @@ -603,7 +603,7 @@ struct formatter, Char> : formatter { Returns an argument that will be formatted using ANSI escape sequences, to be used in a formatting function. - **Example**:: + **Example**: fmt::print("Elapsed time: {0:.2f} seconds", fmt::styled(1.23, fmt::fg(fmt::color::green) | diff --git a/include/fmt/compile.h b/include/fmt/compile.h index ae4b8be5..95691b63 100644 --- a/include/fmt/compile.h +++ b/include/fmt/compile.h @@ -34,7 +34,7 @@ struct is_compiled_string : std::is_base_of {}; * compile time and converted into efficient formatting code. Requires C++17 * `constexpr if` compiler support. * - * **Example**:: + * **Example**: * * // Converts 42 into std::string using the most efficient method and no * // runtime format string processing. diff --git a/include/fmt/format.h b/include/fmt/format.h index 5386aa4b..b43fc34a 100644 --- a/include/fmt/format.h +++ b/include/fmt/format.h @@ -817,7 +817,7 @@ enum { inline_buffer_size = 500 }; * types with the first `SIZE` elements stored in the object itself. Most * commonly used via the `memory_buffer` alias for `char`. * - * **Example**:: + * **Example**: * * auto out = fmt::memory_buffer(); * fmt::format_to(std::back_inserter(out), "The answer is {}.", 42); @@ -1812,7 +1812,7 @@ inline auto find_escape(const char* begin, const char* end) /** * Constructs a compile-time format string from a string literal `s`. * - * **Example**:: + * **Example**: * * // A compile-time error because 'd' is an invalid specifier for strings. * std::string s = fmt::format(FMT_STRING("{:d}"), "foo"); @@ -3873,7 +3873,7 @@ FMT_API auto vsystem_error(int error_code, string_view format_str, * `fmt::format(fmt, args...)`. * `error_code` is a system error code as given by `errno`. * - * **Example**:: + * **Example**: * * // This throws std::system_error with the description * // cannot open file 'madeup': No such file or directory @@ -3890,20 +3890,17 @@ auto system_error(int error_code, format_string fmt, T&&... args) } /** - \rst - Formats an error message for an error returned by an operating system or a - language runtime, for example a file opening error, and writes it to `out`. - The format is the same as the one used by ``std::system_error(ec, message)`` - where ``ec`` is ``std::error_code(error_code, std::generic_category()})``. - It is implementation-defined but normally looks like: - - .. parsed-literal:: - **: ** - - where ** is the passed message and ** is the system - message corresponding to the error code. - `error_code` is a system error code as given by ``errno``. - \endrst + * Formats an error message for an error returned by an operating system or a + * language runtime, for example a file opening error, and writes it to `out`. + * The format is the same as the one used by `std::system_error(ec, message)` + * where `ec` is `std::error_code(error_code, std::generic_category())`. + * It is implementation-defined but normally looks like: + * + * : + * + * where `` is the passed message and `` is the system + * message corresponding to the error code. + * `error_code` is a system error code as given by `errno`. */ FMT_API void format_system_error(detail::buffer& out, int error_code, const char* message) noexcept; @@ -3912,7 +3909,7 @@ FMT_API void format_system_error(detail::buffer& out, int error_code, // Can be used to report errors from destructors. FMT_API void report_system_error(int error_code, const char* message) noexcept; -/** Fast integer formatter. */ +/// A fast integer formatter. class format_int { private: // Buffer should be large enough to hold all digits (digits10 + 1), @@ -3944,31 +3941,23 @@ class format_int { explicit format_int(unsigned long long value) : str_(format_unsigned(value)) {} - /** Returns the number of characters written to the output buffer. */ + /// Returns the number of characters written to the output buffer. auto size() const -> size_t { return detail::to_unsigned(buffer_ - str_ + buffer_size - 1); } - /** - Returns a pointer to the output buffer content. No terminating null - character is appended. - */ + /// Returns a pointer to the output buffer content. No terminating null + /// character is appended. auto data() const -> const char* { return str_; } - /** - Returns a pointer to the output buffer content with terminating null - character appended. - */ + /// Returns a pointer to the output buffer content with terminating null + /// character appended. auto c_str() const -> const char* { buffer_[buffer_size - 1] = '\0'; return str_; } - /** - \rst - Returns the content of the output buffer as an ``std::string``. - \endrst - */ + /// Returns the content of the output buffer as an `std::string`. auto str() const -> std::string { return std::string(str_, size()); } }; @@ -4008,7 +3997,7 @@ struct formatter : formatter, Char> {}; /** * Converts `p` to `const void*` for pointer formatting. * - * **Example**:: + * **Example**: * * auto s = fmt::format("{}", fmt::ptr(p)); */ @@ -4020,7 +4009,7 @@ template auto ptr(T p) -> const void* { /** * Converts `e` to the underlying type. * - * **Example**:: + * **Example**: * * enum class color { red, green, blue }; * auto s = fmt::format("{}", fmt::underlying(color::red)); @@ -4074,15 +4063,13 @@ template struct group_digits_view { }; /** - \rst - Returns a view that formats an integer value using ',' as a locale-independent - thousands separator. - - **Example**:: - - fmt::print("{}", fmt::group_digits(12345)); - // Output: "12,345" - \endrst + * Returns a view that formats an integer value using ',' as a + * locale-independent thousands separator. + * + * **Example**: + * + * fmt::print("{}", fmt::group_digits(12345)); + * // Output: "12,345" */ template auto group_digits(T value) -> group_digits_view { return {value}; @@ -4175,7 +4162,7 @@ template struct nested_formatter { /** * Converts `value` to `std::string` using the default format for type `T`. * - * **Example**:: + * **Example**: * * std::string answer = fmt::to_string(42); */ @@ -4326,14 +4313,12 @@ struct formatter #if FMT_USE_USER_DEFINED_LITERALS inline namespace literals { /** - \rst - User-defined literal equivalent of :func:`fmt::arg`. - - **Example**:: - - using namespace fmt::literals; - fmt::print("Elapsed time: {s:.2f} seconds", "s"_a=1.23); - \endrst + * User-defined literal equivalent of `fmt::arg`. + * + * **Example**: + * + * using namespace fmt::literals; + * fmt::print("Elapsed time: {s:.2f} seconds", "s"_a=1.23); */ # if FMT_USE_NONTYPE_TEMPLATE_ARGS template constexpr auto operator""_a() { @@ -4354,9 +4339,9 @@ FMT_API auto vformat(string_view fmt, format_args args) -> std::string; * Formats `args` according to specifications in `fmt` and returns the result * as a string. * - * **Example**:: + * **Example**: * - * #include + * #include * std::string message = fmt::format("The answer is {}.", 42); */ template diff --git a/include/fmt/os.h b/include/fmt/os.h index 7e1ea345..9c03b5ed 100644 --- a/include/fmt/os.h +++ b/include/fmt/os.h @@ -150,7 +150,7 @@ FMT_API std::system_error vwindows_error(int error_code, string_view format_str, If `error_code` is not a valid error code such as -1, the system message will look like "error -1". - **Example**:: + **Example**: // This throws a system_error with the description // cannot open file 'madeup': The system cannot find the file specified. @@ -444,7 +444,7 @@ class FMT_API ostream { (``file::WRONLY | file::CREATE | file::TRUNC`` by default) * ``buffer_size=``: Output buffer size - **Example**:: + **Example**: auto out = fmt::output_file("guide.txt"); out.print("Don't {}", "Panic"); diff --git a/include/fmt/ostream.h b/include/fmt/ostream.h index 56f2a95c..a5f5a5fe 100644 --- a/include/fmt/ostream.h +++ b/include/fmt/ostream.h @@ -139,7 +139,7 @@ struct formatter, Char> \rst Returns a view that formats `value` via an ostream ``operator<<``. - **Example**:: + **Example**: fmt::print("Current thread id: {}\n", fmt::streamed(std::this_thread::get_id())); @@ -175,7 +175,7 @@ void vprint(std::basic_ostream& os, \rst Prints formatted data to the stream `os`. - **Example**:: + **Example**: fmt::print(cerr, "Don't {}!", "panic"); \endrst diff --git a/include/fmt/printf.h b/include/fmt/printf.h index c62ea30d..5cdb6546 100644 --- a/include/fmt/printf.h +++ b/include/fmt/printf.h @@ -602,7 +602,7 @@ inline auto vsprintf(basic_string_view fmt, \rst Formats arguments and returns the result as a string. - **Example**:: + **Example**: std::string message = fmt::sprintf("The answer is %d", 42); \endrst @@ -628,7 +628,7 @@ inline auto vfprintf(std::FILE* f, basic_string_view fmt, \rst Prints formatted data to the file `f`. - **Example**:: + **Example**: fmt::fprintf(stderr, "Don't %s!", "panic"); \endrst @@ -650,7 +650,7 @@ FMT_DEPRECATED inline auto vprintf(basic_string_view fmt, \rst Prints formatted data to ``stdout``. - **Example**:: + **Example**: fmt::printf("Elapsed time: %.2f seconds", 1.23); \endrst diff --git a/include/fmt/ranges.h b/include/fmt/ranges.h index efb37f28..a3fb6b62 100644 --- a/include/fmt/ranges.h +++ b/include/fmt/ranges.h @@ -658,30 +658,26 @@ struct formatter, Char> { } }; -/** - Returns a view that formats the iterator range `[begin, end)` with elements - separated by `sep`. - */ +/// Returns a view that formats the iterator range `[begin, end)` with elements +/// separated by `sep`. template auto join(It begin, Sentinel end, string_view sep) -> join_view { return {std::move(begin), end, sep}; } /** - \rst - Returns a view that formats `range` with elements separated by `sep`. - - **Example**:: - - std::vector v = {1, 2, 3}; - fmt::print("{}", fmt::join(v, ", ")); - // Output: "1, 2, 3" - - ``fmt::join`` applies passed format specifiers to the range elements:: - - fmt::print("{:02}", fmt::join(v, ", ")); - // Output: "01, 02, 03" - \endrst + * Returns a view that formats `range` with elements separated by `sep`. + * + * **Example**: + * + * std::vector v = {1, 2, 3}; + * fmt::print("{}", fmt::join(v, ", ")); + * // Output: 1, 2, 3 + * + * `fmt::join` applies passed format specifiers to the range elements: + * + * fmt::print("{:02}", fmt::join(v, ", ")); + * // Output: 01, 02, 03 */ template auto join(Range&& r, string_view sep) @@ -809,7 +805,7 @@ FMT_BEGIN_EXPORT \rst Returns an object that formats `tuple` with elements separated by `sep`. - **Example**:: + **Example**: std::tuple t = {1, 'a'}; fmt::print("{}", fmt::join(t, ", ")); @@ -827,7 +823,7 @@ FMT_CONSTEXPR auto join(const std::tuple& tuple, string_view sep) Returns an object that formats `initializer_list` with elements separated by `sep`. - **Example**:: + **Example**: fmt::print("{}", fmt::join({1, 2, 3}, ", ")); // Output: "1, 2, 3"