🛠 Add basic array safety functions and backwards-compatible result type (#3805)

include/fmt/base.h

@@ -276,6 +276,8 @@
 #  define FMT_UNICODE !FMT_MSC_VERSION
 #endif
 
+#define FMT_FWD(...) static_cast<decltype(__VA_ARGS__)&&>(__VA_ARGS__)
+
 // Enable minimal optimizations for more compact code in debug mode.
 FMT_GCC_PRAGMA("GCC push_options")
 #if !defined(__OPTIMIZE__) && !defined(__CUDACC__)
@@ -2861,8 +2863,10 @@ inline auto runtime(string_view s) -> runtime_format_string<> { return {{s}}; }
 
 /** Formats a string and writes the output to ``out``. */
 template <typename OutputIt,
-          FMT_ENABLE_IF(detail::is_output_iterator<OutputIt, char>::value)>
+          FMT_ENABLE_IF(detail::is_output_iterator<remove_cvref_t<OutputIt>,
-auto vformat_to(OutputIt out, string_view fmt, format_args args) -> OutputIt {
+                                                   char>::value)>
+auto vformat_to(OutputIt&& out, string_view fmt, format_args args)
+    -> remove_cvref_t<OutputIt> {
   auto&& buf = detail::get_buffer<char>(out);
   detail::vformat_to(buf, fmt, args, {});
   return detail::get_iterator(buf, out);
@@ -2881,10 +2885,11 @@ auto vformat_to(OutputIt out, string_view fmt, format_args args) -> OutputIt {
  \endrst
  */
 template <typename OutputIt, typename... T,
-          FMT_ENABLE_IF(detail::is_output_iterator<OutputIt, char>::value)>
+          FMT_ENABLE_IF(detail::is_output_iterator<remove_cvref_t<OutputIt>,
-FMT_INLINE auto format_to(OutputIt out, format_string<T...> fmt, T&&... args)
+                                                   char>::value)>
-    -> OutputIt {
+FMT_INLINE auto format_to(OutputIt&& out, format_string<T...> fmt, T&&... args)
-  return vformat_to(out, fmt, fmt::make_format_args(args...));
+    -> remove_cvref_t<OutputIt> {
+  return vformat_to(FMT_FWD(out), fmt, fmt::make_format_args(args...));
 }
 
 template <typename OutputIt> struct format_to_n_result {
@@ -2919,6 +2924,33 @@ FMT_INLINE auto format_to_n(OutputIt out, size_t n, format_string<T...> fmt,
   return vformat_to_n(out, n, fmt, fmt::make_format_args(args...));
 }
 
+template <typename OutputIt, typename OutputSen = OutputIt>
+struct format_to_result {
+  /** Iterator pointing to just after the last succesful write in the range. */
+  OutputIt out;
+  /** Sentinel indicating the end of the output range. */
+  OutputSen out_last;
+
+  FMT_CONSTEXPR operator OutputIt&() & noexcept { return out; }
+  FMT_CONSTEXPR operator const OutputIt&() const& noexcept { return out; }
+  FMT_CONSTEXPR operator OutputIt&&() && noexcept {
+    return static_cast<OutputIt&&>(out);
+  }
+};
+
+template <size_t Size>
+auto vformat_to(char (&out)[Size], string_view fmt, format_args args)
+    -> format_to_result<char*> {
+  format_to_n_result<char*> result = vformat_to_n(out, Size, fmt, args);
+  return {result.out, out + Size};
+}
+
+template <size_t Size, typename... T>
+FMT_INLINE auto format_to(char (&out)[Size], format_string<T...> fmt,
+                          T&&... args) -> format_to_result<char*> {
+  return vformat_to(out, fmt, fmt::make_format_args(args...));
+}
+
 /** Returns the number of chars in the output of ``format(fmt, args...)``. */
 template <typename... T>
 FMT_NODISCARD FMT_INLINE auto formatted_size(format_string<T...> fmt,

test/base-test.cc

@@ -9,15 +9,16 @@
 #include "test-assert.h"
 // clang-format on
 
+#include "fmt/base.h"
+
 #include <climits>      // INT_MAX
 #include <cstring>      // std::strlen
 #include <functional>   // std::equal_to
-#include <iterator>     // std::back_insert_iterator
+#include <iterator>     // std::back_insert_iterator, std::distance
 #include <limits>       // std::numeric_limits
 #include <string>       // std::string
 #include <type_traits>  // std::is_same
 
-#include "fmt/base.h"
 #include "gmock/gmock.h"
 
 using fmt::string_view;
@@ -692,6 +693,47 @@ TEST(core_test, format_to) {
   EXPECT_EQ(s, "42");
 }
 
+TEST(core_test, format_to_c_array) {
+  char buffer[4];
+  auto result = fmt::format_to(buffer, "{}", 12345);
+  EXPECT_EQ(4, std::distance(&buffer[0], result.out));
+  EXPECT_EQ(0, std::distance(result.out, result.out_last));
+  EXPECT_EQ(buffer + 4, result.out);
+  EXPECT_EQ("1234", fmt::string_view(buffer, 4));
+
+  result = fmt::format_to(buffer, "{:s}", "foobar");
+  EXPECT_EQ(4, std::distance(&buffer[0], result.out));
+  EXPECT_EQ(0, std::distance(result.out, result.out_last));
+  EXPECT_EQ(buffer + 4, result.out);
+  EXPECT_EQ("foob", fmt::string_view(buffer, 4));
+
+  buffer[0] = 'x';
+  buffer[1] = 'x';
+  buffer[2] = 'x';
+  buffer[3] = 'x';
+  result = fmt::format_to(buffer, "{}", 'A');
+  EXPECT_EQ(1, std::distance(&buffer[0], result.out));
+  EXPECT_EQ(3, std::distance(result.out, result.out_last));
+  EXPECT_EQ(buffer + 1, result.out);
+  EXPECT_EQ("Axxx", fmt::string_view(buffer, 4));
+
+  result = fmt::format_to(buffer, "{}{} ", 'B', 'C');
+  EXPECT_EQ(3, std::distance(&buffer[0], result.out));
+  EXPECT_EQ(1, std::distance(result.out, result.out_last));
+  EXPECT_EQ(buffer + 3, result.out);
+  EXPECT_EQ("BC x", fmt::string_view(buffer, 4));
+
+  result = fmt::format_to(buffer, "{}", "ABCDE");
+  EXPECT_EQ(4, std::distance(&buffer[0], result.out));
+  EXPECT_EQ(0, std::distance(result.out, result.out_last));
+  EXPECT_EQ("ABCD", fmt::string_view(buffer, 4));
+
+  result = fmt::format_to(buffer, "{}", std::string(1000, '*'));
+  EXPECT_EQ(4, std::distance(&buffer[0], result.out));
+  EXPECT_EQ(0, std::distance(result.out, result.out_last));
+  EXPECT_EQ("****", fmt::string_view(buffer, 4));
+}
+
 #ifdef __cpp_lib_byte
 TEST(core_test, format_byte) {
   auto s = std::string();