text: android
  /
  platform
  /
  external
  /
  fmtlib
  /
  93fd473b8f0bde1f68c3d6ce9c150b83cd633c0e
  /
  .
  /
  README.rst
  blob: 3e43b308cc4f29d1797458b8e9fc53d5a0f153b8 [
  file
  ] [
  log
  ] [
  blame
  ]
  {fmt}
  =====
  .. image::
  :target:
  .. image::
  :target:
  .. image::
  :alt: Join the chat at
  :target:
  **{fmt}** is an open-source formatting library for C++.
  It can be used as a safe and fast alternative to (s)printf and IOStreams.
  `Documentation <>`__
  This is a development branch that implements the C++ standards proposal `P0645
  Text Formatting <>`__.
  Released versions are available from the `Releases page
  <>`__.
  Features
  --------
  * Replacement-based `format API <>`_ with
  positional arguments for localization.
  * `Format string syntax <>`_ similar to the one minimum configuration
  consists of just three header files, ``core.h``, ``format.h`` and
  ``format-inl.h``) and compiled code. See `Compile time and code bloat`_.
  * Reliability: the library has an extensive set of `unit tests
  <>`_.
  * Safety: the library is fully type safe, errors in format strings can be
  reported at compile time,`` macro.
  See the `documentation <>`_ for more details.
  Examples
  --------
  This prints ``Hello, world!`` to stdout:
  .. code:: c++
  fmt::print("Hello, {}!", "world"); // uses Python-like format string syntax
  fmt::printf("Hello, %s!", "world"); // uses printf format string syntax
  Arguments can be accessed by position and arguments' indices can be repeated:
  .. code:: c++
  std::string s = fmt::format("{0}{1}{0}", "abra", "cad");
  // s == "abracadabra"
  Format strings can be checked at compile time:
  .. code:: c++
  // test.cc
  #define FMT_STRING_ALIAS 1
  #include <fmt/format.h>
  std::string s = format(fmt("{2}"), 42);
  .. code::
  $ c++ -Iinclude -std=c++14 test.cc
  ...
  test.cc:4:17: note: in instantiation of function template specialization 'fmt::v5::format<S, int>' requested here
  std::string s = format(fmt("{2}"), 42);
  ^
  include/fmt/core.h:778:19: note: non-constexpr function 'on_error' cannot be used in a constant expression
  ErrorHandler::on_error(message);
  ^
  include/fmt/format.h:2226:16: note: in call to '&checker.context_->on_error(&"argument index out of range"[0])'
  context_.on_error("argument index out of range");
  ^
  {fmt} can be used as a safe portable replacement for ``itoa``
  (`godbolt <>`_):
  .. code:: c++
  fmt::memory_buffer buf;
  format_to(buf, "{}", 42); // replaces itoa(42, buffer, 10)
  format_to(buf, "{:x}", 42); // replaces itoa(42, buffer, 16)
  // access the string using to_string(buf) or buf.data()
  Formatting of user-defined types is supported via a simple
  `extension API <>`_:
  .. code:: c++
  #include "fmt/format.h""
  You can create your own functions similar to `format
  <>`_ and
  `print <>`_
  which take arbitrary arguments (`godbolt <>`_):
  .. code:: c++
  // Prints formatted error message.
  void vreport_error(const char *format, fmt::format_args args) {
  fmt::print("Error: ");
  fmt::vprint(format, args);
  }
  template <typename... Args>
  void report_error(const char *format, const Args & ... args) {
  vreport_error(format, fmt::make_format_args(args...));
  }
  report_error("file not found: {}", path);
  Note that ``vreport_error`` is not parameterized on argument types which can
  improve compile times and reduce code size compared to fully parameterized
  version.
  Projects using this library
  ---------------------------
  * `0 A.D. <>`_: A free, open-source, cross-platform real-time
  strategy game
  * `AMPL/MP <>`_:
  An open-source library for mathematical programming
  * `AvioBook <>`_: A comprehensive aircraft
  operations suite
  * `Celestia <>`_: Real-time 3D visualization of space
  * `Ceph <>`_: A scalable distributed storage system
  * `CUAUV <>`_: Cornell University's autonomous underwater
  vehicle
  * `HarpyWar/pvpgn <>`_:
  Player vs Player Gaming Network with tweaks
  * `KBEngine <>`_: An open-source MMOG server engine
  * `Keypirinha <>`_: A semantic launcher for Windows
  * `Kodi <>`_ (formerly xbmc): Home theater software
  * `Lifeline <>`_: A 2D game
  * `Drake <>`_: A planning, control, and analysis toolbox
  for nonlinear dynamical systems (MIT)
  * `Envoy <>`_: C++ L7 proxy and communication bus
  (Lyft)
  * `FiveM <>`_: a modification framework for GTA V
  * `MongoDB Smasher <>`_: A small tool to
  generate randomized datasets
  * `OpenSpace <>`_: An open-source astrovisualization
  framework
  * `PenUltima Online (POL) <>`_:
  An MMO server, compatible with most Ultima Online clients
  * `quasardb <>`_: A distributed, high-performance,
  associative database
  * `readpe <>`_: Read Portable Executable
  * `redis-cerberus <>`_: A Redis cluster
  proxy
  * `rpclib <>`_: A modern C++ msgpack-RPC server and client
  library
  * 
  `More... <>`_
  If you are aware of other projects using this library, please let me know
  by `email <mailto:victor.zverovich@gmail.com>`_ or by submitting an
  `issue <>`_.
  Motivation
  ----------s
  ~~~~~~~~~
  The main issue with IOStreams is best illustrated with an example:
  .. code:: c++
  std::cout << std::setprecision(2) << std::fixed << 1.23456 << "\n";
  which is a lot of typing compared to printf:
  .. code:: c++
  ~~~~~~~~~~~~~~~~~~~~
  This is a very powerful library which supports both printf-like format
  strings and positional arguments. Its main drawback is performance.
  According to various benchmarks it is much slower than other methods
  considered here. Boost Format also has excessive build times and severe
  code bloat issues (see `Benchmarks`_).
  Fast
  ~~~~~~~~~~~~~~~
  SafeFormat is a formatting library which uses printf-like format strings
  and is type safe. It doesn't support user-defined types or positional
  arguments. It makes unconventional use of ``operator()`` for passing
  format arguments.
  Tinyformat
  ~~~~~~~~~~
  This library supports printf-like format strings and is very small and
  fast. Unfortunately it doesn't support positional arguments and wrapping
  it in C++98 is somewhat difficult. Also its performance and code compactness
  are limited by IOStreams.
  Boost
  ----------
  Speed
  <>`_.
  ================= ============= ===========
  Library Method Run Time, s
  ================= ============= ===========
  libc printf 1.35
  libc++ std::ostream 3.42
  fmt 534bff7 fmt::print 1.56
  tinyformat 2.0.1 tfm::printf 3.73
  Boost Format 1.54 boost::format 8.44
  Folly Format folly::format 2.54
  ================= ============= =========== (Apple LLVM version 8.1.0 (clang-802.0.42),
  macOS Sierra, best of three) is shown in the following tables.
  **Optimized build (-O3)**
  ============= =============== ==================== ==================
  Method Compile Time, s Executable size, KiB Stripped size, KiB
  ============= =============== ==================== ==================
  printf 2.6 29 26
  printf+string 16.4 29 26
  IOStreams 31.1 59 55
  fmt 19.0 37 34
  tinyformat 44.0 103 97
  Boost Format 91.9 226 203
  Folly Format 115.7 101 88
  ============= =============== ==================== ==================
  As you can see, fmt has 60% less overhead in terms of resulting binary code
  size compared to IOStreams and comes pretty close to ``printf``. Boost Format
  and Folly Format have the largest overheads.
  ``printf+string`` is the same as ``printf`` but with extra ``<string>``
  include to measure the overhead of the latter.
  **Non-optimized build**
  ============= =============== ==================== ==================
  Method Compile Time, s Executable size, KiB Stripped size, KiB
  ============= =============== ==================== ==================
  printf 2.2 33 30
  printf+string 16.0 33 30
  IOStreams 28.3 56 52
  fmt 18.2 59 50
  tinyformat 32.6 88 82
  Boost Format 54.1 365 303
  Folly Format 79.9 445 430
  ============= =============== ==================== ==================
  ``libc``, ``lib(std)c++`` and ``libfmt`` are all linked as shared
  libraries to compare formatting function overhead only. Boost Format
  and tinyformat are header-only libraries so they don't provide any
  linkage options.
  Running
  ---
  Q: how can I capture formatting arguments and format them later?
  A: use ``std::tuple``:
  .. code:: c++
  template <typename... Args>
  auto capture(const Args&... args) {
  return std::make_tuple(args...);
  }
  auto print_message = [](const auto&... args) {
  fmt::print(args...);
  };
  // Capture and store arguments:
  auto args = capture("{} {}", 42, "foo");
  // Do formatting:
  std::apply(print_message, args);
  License
  -------.