Make format_to return iterator and update docs

doc/api.rst

@@ -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

include/fmt/core.h

@@ -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>

include/fmt/format.h

@@ -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) {

include/fmt/ostream.h

@@ -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>