Add fprintf and write docs.

3 files changed, 90 insertions, 42 deletions

diff --git a/doc/index.rst b/doc/index.rst
index 77ef4a3e..ffe615b7 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -6,8 +6,8 @@ Usage
 -----
 
 To use the C++ Format library, add ``format.h`` and ``format.cc`` from
-a `release archive <https://github.com/cppformat/cppformat/releases/latest>`__
-or the `Git repository <https://github.com/cppformat/cppformat>`__ to your project.
+a `release archive <https://github.com/cppformat/cppformat/releases/latest>`_
+or the `Git repository <https://github.com/cppformat/cppformat>`_ to your project.
 
 If you are using Visual C++ with precompiled headers, you might need to add
 the line
@@ -25,6 +25,20 @@ All functions and classes provided by the C++ Format library reside
 in namespace ``fmt`` and macros have prefix ``FMT_``. For brevity the
 namespace is usually omitted in examples.
 
+Formatting functions
+^^^^^^^^^^^^^^^^^^^^
+
+The following functions use `format string syntax`_ similar to the one
+used by Python's `str.format
+<http://docs.python.org/3/library/stdtypes.html#str.format>`_ function.
+They take *format_str* and *args* as arguments.
+
+*format_str* is a format string that contains literal text and replacement
+fields surrounded by braces ``{}``. The fields are replaced with formatted
+arguments in the resulting string.
+
+*args* is an argument list representing arbitrary arguments.
+
 .. doxygenfunction:: fmt::format(StringRef, const ArgList &)
 
 .. doxygenfunction:: fmt::print(StringRef, const ArgList &)
@@ -33,20 +47,25 @@ namespace is usually omitted in examples.
 
 .. doxygenfunction:: fmt::print(std::ostream &, StringRef, const ArgList &)
 
-.. doxygendefine:: FMT_VARIADIC
+Printf formatting functions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. doxygenclass:: fmt::BasicWriter
-   :members:
+The following functions use `printf format string syntax
+<http://pubs.opengroup.org/onlinepubs/009695399/functions/fprintf.html>`_ with
+a POSIX extension for positional arguments.
 
-.. doxygenclass:: fmt::ArgList
-   :members:
+.. doxygenfunction:: fmt::printf(StringRef, const ArgList &)
 
-.. doxygenclass:: fmt::BasicStringRef
-   :members:
+.. doxygenfunction:: fmt::fprintf(std::FILE *, StringRef, const ArgList &)
+
+.. doxygenfunction:: fmt::sprintf(StringRef, const ArgList &)
 
 Write API
 ---------
 
+.. doxygenclass:: fmt::BasicWriter
+   :members:
+
 .. doxygenfunction:: fmt::bin
 
 .. doxygenfunction:: fmt::oct
@@ -59,6 +78,17 @@ Write API
 
 .. _formatstrings:
 
+Utilities
+---------
+
+.. doxygendefine:: FMT_VARIADIC
+
+.. doxygenclass:: fmt::ArgList
+   :members:
+
+.. doxygenclass:: fmt::BasicStringRef
+   :members:
+
 System Errors
 -------------
 
diff --git a/format.cc b/format.cc
index c7405f99..ce9b90da 100644
--- a/format.cc
+++ b/format.cc
@@ -1248,21 +1248,15 @@ void fmt::report_windows_error(
 }
 #endif
 
-void fmt::print(StringRef format, const ArgList &args) {
+void fmt::print(std::FILE *f, StringRef format_str, const ArgList &args) {
   Writer w;
-  w.write(format, args);
-  std::fwrite(w.data(), 1, w.size(), stdout);
-}
-
-void fmt::print(std::FILE *f, StringRef format, const ArgList &args) {
-  Writer w;
-  w.write(format, args);
+  w.write(format_str, args);
   std::fwrite(w.data(), 1, w.size(), f);
 }
 
-void fmt::print(std::ostream &os, StringRef format, const ArgList &args) {
+void fmt::print(std::ostream &os, StringRef format_str, const ArgList &args) {
   Writer w;
-  w.write(format, args);
+  w.write(format_str, args);
   os.write(w.data(), w.size());
 }
 
@@ -1274,10 +1268,10 @@ void fmt::print_colored(Color c, StringRef format, const ArgList &args) {
   std::fputs(RESET_COLOR, stdout);
 }
 
-void fmt::printf(StringRef format, const ArgList &args) {
+int fmt::fprintf(std::FILE *f, StringRef format, const ArgList &args) {
   Writer w;
   printf(w, format, args);
-  std::fwrite(w.data(), 1, w.size(), stdout);
+  return std::fwrite(w.data(), 1, w.size(), f);
 }
 
 // Explicit instantiations for char.
diff --git a/format.h b/format.h
index 64859490..94a17475 100644
--- a/format.h
+++ b/format.h
@@ -1745,21 +1745,11 @@ void print_colored(Color c, StringRef format, const ArgList &args);
 
 /**
   \rst
-  Formats a string similarly to Python's `str.format
-  <http://docs.python.org/3/library/stdtypes.html#str.format>`__ function
-  and returns the result as a string.
-
-  *format_str* is a format string that contains literal text and replacement
-  fields surrounded by braces ``{}``. The fields are replaced with formatted
-  arguments in the resulting string.
-  
-  *args* is an argument list representing arbitrary arguments.
+  Formats arguments and returns the result as a string.
 
   **Example**::
 
     std::string message = format("The answer is {}", 42);
-
-  See also `Format String Syntax`_.
   \endrst
 */
 inline std::string format(StringRef format_str, const ArgList &args) {
@@ -1776,36 +1766,38 @@ inline std::wstring format(WStringRef format_str, const ArgList &args) {
 
 /**
   \rst
-  Prints formatted data to ``stdout``.
+  Prints formatted data to the file *f*.
 
   **Example**::
 
-    print("Elapsed time: {0:.2f} seconds", 1.23);
+    print(stderr, "Don't {}!", "panic");
   \endrst
  */
-void print(StringRef format, const ArgList &args);
+void print(std::FILE *f, StringRef format_str, const ArgList &args);
 
 /**
   \rst
-  Prints formatted data to a file.
+  Prints formatted data to ``stdout``.
 
   **Example**::
 
-    print(stderr, "Don't {}!", "panic");
+    print("Elapsed time: {0:.2f} seconds", 1.23);
   \endrst
  */
-void print(std::FILE *f, StringRef format, const ArgList &args);
+inline void print(StringRef format_str, const ArgList &args) {
+  print(stdout, format_str, args);
+}
 
 /**
   \rst
-  Prints formatted data to a stream.
+  Prints formatted data to the stream *os*.
 
   **Example**::
 
     print(cerr, "Don't {}!", "panic");
   \endrst
  */
-void print(std::ostream &os, StringRef format, const ArgList &args);
+void print(std::ostream &os, StringRef format_str, const ArgList &args);
 
 template <typename Char>
 void printf(BasicWriter<Char> &w,
@@ -1813,13 +1805,44 @@ void printf(BasicWriter<Char> &w,
   internal::PrintfFormatter<Char>().format(w, format, args);
 }
 
+/**
+  \rst
+  Formats arguments and returns the result as a string.
+
+  **Example**::
+
+    std::string message = fmt::sprintf("The answer is %d", 42);
+  \endrst
+*/
 inline std::string sprintf(StringRef format, const ArgList &args) {
   Writer w;
   printf(w, format, args);
   return w.str();
 }
 
-void printf(StringRef format, const ArgList &args);
+/**
+  \rst
+  Prints formatted data to the file *f*.
+
+  **Example**::
+
+    fmt::fprintf(stderr, "Don't %s!", "panic");
+  \endrst
+ */
+int fprintf(std::FILE *f, StringRef format, const ArgList &args);
+
+/**
+  \rst
+  Prints formatted data to ``stdout``.
+
+  **Example**::
+
+    fmt::printf("Elapsed time: %.2f seconds", 1.23);
+  \endrst
+ */
+inline int printf(StringRef format, const ArgList &args) {
+  return fprintf(stdout, format, args);
+}
 
 /**
   Fast integer formatter.
@@ -2032,7 +2055,8 @@ FMT_VARIADIC(void, print, std::FILE *, StringRef)
 FMT_VARIADIC(void, print, std::ostream &, StringRef)
 FMT_VARIADIC(void, print_colored, Color, StringRef)
 FMT_VARIADIC(std::string, sprintf, StringRef)
-FMT_VARIADIC(void, printf, StringRef)
+FMT_VARIADIC(int, printf, StringRef)
+FMT_VARIADIC(int, fprintf, std::FILE *, StringRef)
 }
 
 // Restore warnings.