Move format_system_error to the public API (#323)

doc/api.rst

@@ -197,6 +197,8 @@ System errors
 .. doxygenclass:: fmt::SystemError
    :members:
 
+.. doxygenfunction:: fmt::format_system_error
+
 .. doxygenclass:: fmt::WindowsError
    :members:
 

fmt/format.cc

@@ -359,6 +359,13 @@ class CharConverter : public ArgVisitor<CharConverter, void> {
 
 namespace internal {
 
+// This method is used to preserve binary compatibility with fmt 3.0.
+// It can be removed in 4.0.
+FMT_FUNC void format_system_error(
+  Writer &out, int error_code, StringRef message) FMT_NOEXCEPT {
+  fmt::format_system_error(out, error_code, message);
+}
+
 template <typename Char>
 class PrintfArgFormatter :
     public ArgFormatterBase<PrintfArgFormatter<Char>, Char> {
@@ -434,7 +441,7 @@ FMT_FUNC void fmt::SystemError::init(
     int err_code, CStringRef format_str, ArgList args) {
   error_code_ = err_code;
   MemoryWriter w;
-  internal::format_system_error(w, err_code, format(format_str, args));
+  format_system_error(w, err_code, format(format_str, args));
   std::runtime_error &base = *this;
   base = std::runtime_error(w.str());
 }
@@ -592,12 +599,12 @@ FMT_FUNC void fmt::internal::format_windows_error(
 
 #endif  // FMT_USE_WINDOWS_H
 
-FMT_FUNC void fmt::internal::format_system_error(
+FMT_FUNC void fmt::format_system_error(
     fmt::Writer &out, int error_code,
     fmt::StringRef message) FMT_NOEXCEPT {
   FMT_TRY {
-    MemoryBuffer<char, INLINE_BUFFER_SIZE> buffer;
+    internal::MemoryBuffer<char, internal::INLINE_BUFFER_SIZE> buffer;
-    buffer.resize(INLINE_BUFFER_SIZE);
+    buffer.resize(internal::INLINE_BUFFER_SIZE);
     for (;;) {
       char *system_message = &buffer[0];
       int result = safe_strerror(error_code, system_message, buffer.size());
@@ -854,7 +861,7 @@ void fmt::internal::PrintfFormatter<Char>::format(
 FMT_FUNC void fmt::report_system_error(
     int error_code, fmt::StringRef message) FMT_NOEXCEPT {
   // 'fmt::' is for bcc32.
-  fmt::report_error(internal::format_system_error, error_code, message);
+  fmt::report_error(format_system_error, error_code, message);
 }
 
 #if FMT_USE_WINDOWS_H

fmt/format.h

@@ -989,9 +989,6 @@ FMT_API void format_windows_error(fmt::Writer &out, int error_code,
                                   fmt::StringRef message) FMT_NOEXCEPT;
 #endif
 
-FMT_API void format_system_error(fmt::Writer &out, int error_code,
-                                 fmt::StringRef message) FMT_NOEXCEPT;
-
 // A formatting argument value.
 struct Value {
   template <typename Char>
@@ -2246,17 +2243,10 @@ class SystemError : public internal::RuntimeError {
  public:
   /**
    \rst
-   Constructs a :class:`fmt::SystemError` object with the description
+   Constructs a :class:`fmt::SystemError` object with a description
-   of the form
+   formatted with `fmt::format_system_error`. *message* and additional
-
+   arguments passed into the constructor are formatted similarly to
-   .. parsed-literal::
+   `fmt::format`.
-     *<message>*: *<system-message>*
-
-   where *<message>* is the formatted message and *<system-message>* is
-   the system message corresponding to the error code.
-   *error_code* is a system error code as given by ``errno``.
-   If *error_code* is not a valid error code such as -1, the system message
-   may look like "Unknown error -1" and is platform-dependent.
 
    **Example**::
 
@@ -2277,6 +2267,25 @@ class SystemError : public internal::RuntimeError {
   int error_code() const { return error_code_; }
 };
 
+/**
+  \rst
+  Formats an error returned by an operating system or a language runtime,
+  for example a file opening error, and writes it to *out* in the following
+  form:
+   
+  .. 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``.
+  If *error_code* is not a valid error code such as -1, the system message
+  may look like "Unknown error -1" and is platform-dependent.
+  \endrst
+ */
+FMT_API void format_system_error(fmt::Writer &out, int error_code,
+                                 fmt::StringRef message) FMT_NOEXCEPT;
+
 /**
   \rst
   This template provides operations for formatting and writing data into

test/gtest-extra-test.cc

@@ -320,7 +320,7 @@ TEST(StreamingAssertionsTest, EXPECT_WRITE) {
 
 TEST(UtilTest, FormatSystemError) {
   fmt::MemoryWriter out;
-  fmt::internal::format_system_error(out, EDOM, "test message");
+  fmt::format_system_error(out, EDOM, "test message");
   EXPECT_EQ(out.str(), format_system_error(EDOM, "test message"));
 }
 

test/gtest-extra.cc

@@ -105,6 +105,6 @@ std::string read(File &f, std::size_t count) {
 
 std::string format_system_error(int error_code, fmt::StringRef message) {
   fmt::MemoryWriter out;
-  fmt::internal::format_system_error(out, error_code, message);
+  fmt::format_system_error(out, error_code, message);
   return out.str();
 }

test/util-test.cc

@@ -834,10 +834,10 @@ void check_throw_error(int error_code, FormatErrorMessage format) {
 
 TEST(UtilTest, FormatSystemError) {
   fmt::MemoryWriter message;
-  fmt::internal::format_system_error(message, EDOM, "test");
+  fmt::format_system_error(message, EDOM, "test");
   EXPECT_EQ(fmt::format("test: {}", get_system_error(EDOM)), message.str());
   message.clear();
-  fmt::internal::format_system_error(
+  fmt::format_system_error(
         message, EDOM, fmt::StringRef(0, std::numeric_limits<size_t>::max()));
   EXPECT_EQ(fmt::format("error {}", EDOM), message.str());
 }
@@ -846,12 +846,12 @@ TEST(UtilTest, SystemError) {
   fmt::SystemError e(EDOM, "test");
   EXPECT_EQ(fmt::format("test: {}", get_system_error(EDOM)), e.what());
   EXPECT_EQ(EDOM, e.error_code());
-  check_throw_error<fmt::SystemError>(EDOM, fmt::internal::format_system_error);
+  check_throw_error<fmt::SystemError>(EDOM, fmt::format_system_error);
 }
 
 TEST(UtilTest, ReportSystemError) {
   fmt::MemoryWriter out;
-  fmt::internal::format_system_error(out, EDOM, "test error");
+  fmt::format_system_error(out, EDOM, "test error");
   out << '\n';
   EXPECT_WRITE(stderr, fmt::report_system_error(EDOM, "test error"), out.str());
 }