mirror/fmt
1
0
Fork 0
mirror of https://github.com/fmtlib/fmt.git synced 2024-12-25 06:21:00 +00:00
Code Issues Packages Projects Releases Wiki Activity

Make format_to return iterator and update docs

Browse Source
This commit is contained in:
Victor Zverovich 2018-03-04 08:13:08 -08:00
parent 5281ea6ad2
commit b7632e9641
4 changed files with 42 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
doc/api.rst
View File

@ -4,9 +4,8 @@
API Reference API Reference
************* *************
All functions and classes provided by the fmt library reside in namespace All functions and classes provided by the {fmt} library reside in namespace
``fmt`` and macros have prefix ``FMT_``. For brevity the namespace is usually ``fmt`` and macros have prefix ``FMT_``.
omitted in examples.
Format API Format API
========== ==========
@ -60,28 +59,28 @@ Formatting user-defined types
To make a user-defined type formattable, specialize the ``formatter<T>`` struct To make a user-defined type formattable, specialize the ``formatter<T>`` struct
template and implement ``parse`` and ``format`` methods:: template and implement ``parse`` and ``format`` methods::
struct MyStruct { double x, y; }; struct point { double x, y; };
namespace fmt { namespace fmt {
template <> template <>
struct formatter<MyStruct> { struct formatter<point> {
template <typename ParseContext> template <typename ParseContext>
auto parse(ParseContext &ctx) { return ctx.begin(); } auto parse(ParseContext &ctx) { return ctx.begin(); }
template <typename FormatContext> template <typename FormatContext>
auto format(const MyStruct &s, FormatContext &ctx) { auto format(const point &p, FormatContext &ctx) {
return format_to(ctx.begin(), "[MyStruct: x={:.1f}, y={:.2f}]", s.x, s.y); return format_to(ctx.begin(), "({:.1f}, {:.1f})", p.x, p.y);
} }
}; };
} }
Then you can pass objects of type ``MyStruct`` to any formatting function:: Then you can pass objects of type ``point`` to any formatting function::
MyStruct m = {1, 2}; point p = {1, 2};
std::string s = fmt::format("m={}", m); std::string s = fmt::format("{}", p);
// s == "m=[MyStruct: x=1.0, y=2.00]" // s == "(1.0, 2.0)"
In the example above the ``formatter<MyStruct>::parse`` function ignores the In the example above the ``formatter<point>::parse`` function ignores the
contents of the format string referred to by ``ctx.begin()`` so the object will contents of the format string referred to by ``ctx.begin()`` so the object will
always be formatted in the same way. See ``formatter<tm>::parse`` in always be formatted in the same way. See ``formatter<tm>::parse`` in
:file:`fmt/time.h` for an advanced example of how to parse the format string and :file:`fmt/time.h` for an advanced example of how to parse the format string and

21
include/fmt/core.h
View File

@ -1118,7 +1118,7 @@ struct named_arg : named_arg_base<Char> {
**Example**:: **Example**::
print("Elapsed time: {s:.2f} seconds", arg("s", 1.23)); fmt::print("Elapsed time: {s:.2f} seconds", arg("s", 1.23));
\endrst \endrst
*/ */
template <typename T> template <typename T>
@ -1144,7 +1144,7 @@ FMT_API void vprint_colored(Color c, string_view format, format_args args);
Formats a string and prints it to stdout using ANSI escape sequences to Formats a string and prints it to stdout using ANSI escape sequences to
specify color (experimental). specify color (experimental).
Example: Example:
print_colored(fmt::RED, "Elapsed time: {0:.2f} seconds", 1.23); fmt::print_colored(fmt::RED, "Elapsed time: {0:.2f} seconds", 1.23);
*/ */
template <typename... Args> template <typename... Args>
inline void print_colored(Color c, string_view format_str, inline void print_colored(Color c, string_view format_str,
@ -1152,9 +1152,9 @@ inline void print_colored(Color c, string_view format_str,
vprint_colored(c, format_str, make_args(args...)); vprint_colored(c, format_str, make_args(args...));
} }
void vformat_to(internal::buffer &buf, string_view format_str, context::iterator vformat_to(internal::buffer &buf, string_view format_str,
format_args args); format_args args);
void vformat_to(internal::wbuffer &buf, wstring_view format_str, wcontext::iterator vformat_to(internal::wbuffer &buf, wstring_view format_str,
wformat_args args); wformat_args args);
template <typename Container> template <typename Container>
@ -1168,11 +1168,14 @@ struct is_contiguous<fmt::internal::basic_buffer<Char>> : std::true_type {};
/** Formats a string and writes the output to ``out``. */ /** Formats a string and writes the output to ``out``. */
template <typename Container> template <typename Container>
typename std::enable_if<is_contiguous<Container>::value>::type typename std::enable_if<
is_contiguous<Container>::value, std::back_insert_iterator<Container>>::type
vformat_to(std::back_insert_iterator<Container> out, vformat_to(std::back_insert_iterator<Container> out,
string_view format_str, format_args args) { string_view format_str, format_args args) {
internal::container_buffer<Container> buf(internal::get_container(out)); auto& container = internal::get_container(out);
internal::container_buffer<Container> buf(container);
vformat_to(buf, format_str, args); vformat_to(buf, format_str, args);
return std::back_inserter(container);
} }
std::string vformat(string_view format_str, format_args args); std::string vformat(string_view format_str, format_args args);
@ -1184,7 +1187,7 @@ std::wstring vformat(wstring_view format_str, wformat_args args);
**Example**:: **Example**::
std::string message = format("The answer is {}", 42); std::string message = fmt::format("The answer is {}", 42);
\endrst \endrst
*/ */
template <typename... Args> template <typename... Args>
@ -1204,7 +1207,7 @@ FMT_API void vprint(std::FILE *f, string_view format_str, format_args args);
**Example**:: **Example**::
print(stderr, "Don't {}!", "panic"); fmt::print(stderr, "Don't {}!", "panic");
\endrst \endrst
*/ */
template <typename... Args> template <typename... Args>
@ -1220,7 +1223,7 @@ FMT_API void vprint(string_view format_str, format_args args);
**Example**:: **Example**::
print("Elapsed time: {0:.2f} seconds", 1.23); fmt::print("Elapsed time: {0:.2f} seconds", 1.23);
\endrst \endrst
*/ */
template <typename... Args> template <typename... Args>

31
include/fmt/format.h
View File

@ -2146,7 +2146,7 @@ class arg_formatter:
using base::operator(); using base::operator();
/** Formats an argument of a custom (user-defined) type. */ /** Formats an argument of a user-defined type. */
void operator()(typename basic_arg<context_type>::handle handle) const { void operator()(typename basic_arg<context_type>::handle handle) const {
handle.format(ctx_); handle.format(ctx_);
} }
@ -3324,28 +3324,28 @@ std::basic_string<Char> to_string(const basic_memory_buffer<Char> &buffer) {
return std::basic_string<Char>(buffer.data(), buffer.size()); return std::basic_string<Char>(buffer.data(), buffer.size());
} }
inline void vformat_to(internal::buffer &buf, string_view format_str, inline context::iterator vformat_to(
format_args args) { internal::buffer &buf, string_view format_str, format_args args) {
typedef back_insert_range<internal::buffer> range; typedef back_insert_range<internal::buffer> range;
vformat_to<arg_formatter<range>>(buf, format_str, args); return vformat_to<arg_formatter<range>>(buf, format_str, args);
} }
inline void vformat_to(internal::wbuffer &buf, wstring_view format_str, inline wcontext::iterator vformat_to(
wformat_args args) { internal::wbuffer &buf, wstring_view format_str, wformat_args args) {
typedef back_insert_range<internal::wbuffer> range; typedef back_insert_range<internal::wbuffer> range;
vformat_to<arg_formatter<range>>(buf, format_str, args); return vformat_to<arg_formatter<range>>(buf, format_str, args);
} }
template <typename... Args> template <typename... Args>
inline void format_to(memory_buffer &buf, string_view format_str, inline context::iterator format_to(
const Args & ... args) { memory_buffer &buf, string_view format_str, const Args & ... args) {
vformat_to(buf, format_str, make_args(args...)); return vformat_to(buf, format_str, make_args(args...));
} }
template <typename... Args> template <typename... Args>
inline void format_to(wmemory_buffer &buf, wstring_view format_str, inline wcontext::iterator format_to(
const Args & ... args) { wmemory_buffer &buf, wstring_view format_str, const Args & ... args) {
vformat_to(buf, format_str, make_args<wcontext>(args...)); return vformat_to(buf, format_str, make_args<wcontext>(args...));
} }
template <typename OutputIt, typename Char = char> template <typename OutputIt, typename Char = char>
@ -3373,10 +3373,11 @@ inline OutputIt format_to(OutputIt out, string_view format_str,
} }
template <typename Container, typename... Args> template <typename Container, typename... Args>
inline typename std::enable_if<is_contiguous<Container>::value>::type inline typename std::enable_if<
is_contiguous<Container>::value, std::back_insert_iterator<Container>>::type
format_to(std::back_insert_iterator<Container> out, format_to(std::back_insert_iterator<Container> out,
string_view format_str, const Args & ... args) { string_view format_str, const Args & ... args) {
vformat_to(out, format_str, make_args(args...)); return vformat_to(out, format_str, make_args(args...));
} }
inline std::string vformat(string_view format_str, format_args args) { inline std::string vformat(string_view format_str, format_args args) {

2
include/fmt/ostream.h
View File

@ -133,7 +133,7 @@ inline void vprint(std::ostream &os, string_view format_str, format_args args) {
**Example**:: **Example**::
print(cerr, "Don't {}!", "panic"); fmt::print(cerr, "Don't {}!", "panic");
\endrst \endrst
*/ */
template <typename... Args> template <typename... Args>