mirror/fmt
1
0
Fork 0
mirror of https://github.com/fmtlib/fmt.git synced 2024-12-24 12:14:26 +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
*************
All functions and classes provided by the fmt library reside in namespace
``fmt`` and macros have prefix ``FMT_``. For brevity the namespace is usually
omitted in examples.
All functions and classes provided by the {fmt} library reside in namespace
``fmt`` and macros have prefix ``FMT_``.
Format API
==========
@ -60,28 +59,28 @@ Formatting user-defined types
To make a user-defined type formattable, specialize the ``formatter<T>`` struct
template and implement ``parse`` and ``format`` methods::
struct MyStruct { double x, y; };
struct point { double x, y; };
namespace fmt {
template <>
struct formatter<MyStruct> {
struct formatter<point> {
template <typename ParseContext>
auto parse(ParseContext &ctx) { return ctx.begin(); }
template <typename FormatContext>
auto format(const MyStruct &s, FormatContext &ctx) {
return format_to(ctx.begin(), "[MyStruct: x={:.1f}, y={:.2f}]", s.x, s.y);
auto format(const point &p, FormatContext &ctx) {
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};
std::string s = fmt::format("m={}", m);
// s == "m=[MyStruct: x=1.0, y=2.00]"
point p = {1, 2};
std::string s = fmt::format("{}", p);
// 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
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

21
include/fmt/core.h
View File

@ -1118,7 +1118,7 @@ struct named_arg : named_arg_base<Char> {
**Example**::
print("Elapsed time: {s:.2f} seconds", arg("s", 1.23));
fmt::print("Elapsed time: {s:.2f} seconds", arg("s", 1.23));
\endrst
*/
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
specify color (experimental).
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>
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...));
}
void vformat_to(internal::buffer &buf, string_view format_str,
context::iterator vformat_to(internal::buffer &buf, string_view format_str,
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);
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``. */
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,
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);
return std::back_inserter(container);
}
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**::
std::string message = format("The answer is {}", 42);
std::string message = fmt::format("The answer is {}", 42);
\endrst
*/
template <typename... Args>
@ -1204,7 +1207,7 @@ FMT_API void vprint(std::FILE *f, string_view format_str, format_args args);
**Example**::
print(stderr, "Don't {}!", "panic");
fmt::print(stderr, "Don't {}!", "panic");
\endrst
*/
template <typename... Args>
@ -1220,7 +1223,7 @@ FMT_API void vprint(string_view format_str, format_args args);
**Example**::
print("Elapsed time: {0:.2f} seconds", 1.23);
fmt::print("Elapsed time: {0:.2f} seconds", 1.23);
\endrst
*/
template <typename... Args>

31
include/fmt/format.h
View File

@ -2146,7 +2146,7 @@ class arg_formatter:
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 {
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());
}
inline void vformat_to(internal::buffer &buf, string_view format_str,
format_args args) {
inline context::iterator vformat_to(
internal::buffer &buf, string_view format_str, format_args args) {
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,
wformat_args args) {
inline wcontext::iterator vformat_to(
internal::wbuffer &buf, wstring_view format_str, wformat_args args) {
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>
inline void format_to(memory_buffer &buf, string_view format_str,
const Args & ... args) {
vformat_to(buf, format_str, make_args(args...));
inline context::iterator format_to(
memory_buffer &buf, string_view format_str, const Args & ... args) {
return vformat_to(buf, format_str, make_args(args...));
}
template <typename... Args>
inline void format_to(wmemory_buffer &buf, wstring_view format_str,
const Args & ... args) {
vformat_to(buf, format_str, make_args<wcontext>(args...));
inline wcontext::iterator format_to(
wmemory_buffer &buf, wstring_view format_str, const Args & ... args) {
return vformat_to(buf, format_str, make_args<wcontext>(args...));
}
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>
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,
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) {

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**::
print(cerr, "Don't {}!", "panic");
fmt::print(cerr, "Don't {}!", "panic");
\endrst
*/
template <typename... Args>