mirror/fmt
1
0
Fork 0
mirror of https://github.com/fmtlib/fmt.git synced 2025-04-16 14:42:25 +00:00
Code Issues Packages Projects Releases Wiki Activity

Migrate to mkdocs

Browse Source
This commit is contained in:
Victor Zverovich 2024-06-02 12:21:11 -07:00
parent 886237ae7b
commit 97117cbb51
9 changed files with 98 additions and 119 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

58
doc/api.md
View File

@ -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.
<a id="print"></a>
::: print(format_string<T...>, T&&...)
::: print(FILE*, format_string<T...>, 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
<!-- The experimental `nested_formatter` provides an easy way of applying a
formatter to one or more subobjects.
For example:
@ -185,7 +184,7 @@ prints:
Notice that fill, align and width are applied to the whole object which
is the recommended behavior while the remaining specifiers apply to
elements.
elements. -->
In general the formatter has the following form:
@ -232,10 +231,10 @@ struct B : A {
};
template <typename T>
struct fmt::formatter<T, std::enable_if_t<std::is_base_of<A, T>::value, char>> :
struct fmt::formatter<T, std::enable_if_t<std::is_base_of_v<A, T>, char>> :
fmt::formatter<std::string> {
auto format(const A& a, format_context& ctx) const {
return fmt::formatter<std::string>::format(a.name(), ctx);
return formatter<std::string>::format(a.name(), ctx);
}
};
```
@ -248,12 +247,18 @@ struct fmt::formatter<T, std::enable_if_t<std::is_base_of<A, T>::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<char, fmt::inline_buffer_size, custom_allocator>;
@ -439,18 +438,16 @@ The library also supports convenient formatting of ranges and tuples:
#include <fmt/ranges.h>
std::tuple<char, int, float> t{'a', 1, 2.0f};
// Prints "('a', 1, 2.0)"
fmt::print("{}", t);
fmt::print("{}", std::tuple<char, int>{'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 <fmt/ranges.h>
std::tuple<int, char> t = {1, 'a'};
// Prints "1, a"
auto t = std::tuple<int, char>{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)

4
include/fmt/args.h
View File

@ -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<fmt::format_context> 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<fmt::format_context> store;
char band[] = "Rolling Stones";

10
include/fmt/color.h
View File

@ -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<T...> 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 <fmt/color.h>
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<char> out;
fmt::format_to(std::back_inserter(out),
@ -603,7 +603,7 @@ struct formatter<detail::styled_arg<T>, Char> : formatter<T, Char> {
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) |

2
include/fmt/compile.h
View File

@ -34,7 +34,7 @@ struct is_compiled_string : std::is_base_of<compiled_string, S> {};
* 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.

93
include/fmt/format.h
View File

@ -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<T...> 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::
*<message>*: *<system-message>*
where *<message>* is the passed message and *<system-message>* 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:
*
* <message>: <system-message>
*
* where `<message>` is the passed message and `<system-message>` 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<char>& out, int error_code,
const char* message) noexcept;
@ -3912,7 +3909,7 @@ FMT_API void format_system_error(detail::buffer<char>& 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<Char[N], Char> : formatter<basic_string_view<Char>, Char> {};
/**
* Converts `p` to `const void*` for pointer formatting.
*
* **Example**::
* **Example**:
*
* auto s = fmt::format("{}", fmt::ptr(p));
*/
@ -4020,7 +4009,7 @@ template <typename T> 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 <typename T> 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 <typename T> auto group_digits(T value) -> group_digits_view<T> {
return {value};
@ -4175,7 +4162,7 @@ template <typename T, typename Char = char> 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<detail::float128, Char>
#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 <detail_exported::fixed_string Str> 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 <fmt/core.h>
* #include <fmt/format.h>
* std::string message = fmt::format("The answer is {}.", 42);
*/
template <typename... T>

4
include/fmt/os.h
View File

@ -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=<integer>``: Output buffer size
**Example**::
**Example**:
auto out = fmt::output_file("guide.txt");
out.print("Don't {}", "Panic");

4
include/fmt/ostream.h
View File

@ -139,7 +139,7 @@ struct formatter<detail::streamed_view<T>, 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<Char>& os,
\rst
Prints formatted data to the stream `os`.
**Example**::
**Example**:
fmt::print(cerr, "Don't {}!", "panic");
\endrst

6
include/fmt/printf.h
View File

@ -602,7 +602,7 @@ inline auto vsprintf(basic_string_view<Char> 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<Char> 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<Char> fmt,
\rst
Prints formatted data to ``stdout``.
**Example**::
**Example**:
fmt::printf("Elapsed time: %.2f seconds", 1.23);
\endrst

36
include/fmt/ranges.h
View File

@ -658,30 +658,26 @@ struct formatter<join_view<It, Sentinel, Char>, 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 <typename It, typename Sentinel>
auto join(It begin, Sentinel end, string_view sep) -> join_view<It, Sentinel> {
return {std::move(begin), end, sep};
}
/**
\rst
Returns a view that formats `range` with elements separated by `sep`.
**Example**::
std::vector<int> 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<int> 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 <typename Range>
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<int, char> t = {1, 'a'};
fmt::print("{}", fmt::join(t, ", "));
@ -827,7 +823,7 @@ FMT_CONSTEXPR auto join(const std::tuple<T...>& 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"