API Reference¶

Named Arguments¶

- template<typename Char, typename T> detail::named_arg<Char, T> arg(const Char *name, const T &arg)

Named arguments are not supported in compile-time checks at the moment.

Argument Lists¶

You can create your own formatting function with compile-time checks and small binary footprint, for example (https://godbolt.org/z/oba4Mc):

#include <fmt/format.h>

void vlog(const char* file, int line, fmt::string_view format,
          fmt::format_args args) {
  fmt::print("{}: {}: ", file, line);
  fmt::vprint(format, args);
}

template <typename S, typename... Args>
void log(const char* file, int line, const S& format, Args&&... args) {
  vlog(file, line, format,
      fmt::make_args_checked<Args...>(format, args...));
}

#define MY_LOG(format, ...) \
  log(__FILE__, __LINE__, FMT_STRING(format), __VA_ARGS__)

MY_LOG("invalid squishiness: {}", 42);

Note that vlog is not parameterized on argument types which improves compile times and reduces binary code size compared to a fully parameterized version.

template<typename ...Args, typename S, typename Char = char_t<S>>
inline auto fmt::make_args_checked(const S &format_str, const remove_reference_t<Args>&... args) -> format_arg_store<buffer_context<Char>, remove_reference_t<Args>...>¶

Constructs a format_arg_store object that contains references to arguments and can be implicitly converted to format_args. If format_str is a compile-time string then make_args_checked() checks its validity at compile time.

template<typename Context = format_context, typename ...Args>
inline format_arg_store<Context, Args...> fmt::make_format_args(const Args&... args)¶

Constructs a format_arg_store object that contains references to arguments and can be implicitly converted to format_args. Context can be omitted in which case it defaults to context. See arg for lifetime considerations.

template<typename Context, typename ...Args>
class format_arg_store¶

An array of references to arguments. It can be implicitly converted into basic_format_args for passing into type-erased formatting functions such as vformat().

template<typename Context>
class fmt::dynamic_format_arg_store¶

A dynamic version of fmt::format_arg_store. It’s equipped with a storage to potentially temporary objects which lifetimes could be shorter than the format arguments object.

It can be implicitly converted into basic_format_args for passing into type-erased formatting functions such as vformat().

Public Functions

template<typename T>
inline void push_back(const T &arg)¶

Adds an argument into the dynamic store for later passing to a formatting function.

Note that custom types and string types (but not string views) are copied into the store dynamically allocating memory if necessary.

Example:

fmt::dynamic_format_arg_store<fmt::format_context> store;
store.push_back(42);
store.push_back("abc");
store.push_back(1.5f);
std::string result = fmt::vformat("{} and {} and {}", store);

template<typename T>
inline void push_back(std::reference_wrapper<T> arg)¶

Adds a reference to the argument into the dynamic store for later passing to a formatting function. Supports named arguments wrapped in std::reference_wrapper via std::ref()/std::cref().

Example:

fmt::dynamic_format_arg_store<fmt::format_context> store;
char str[] = "1234567890";
store.push_back(std::cref(str));
int a1_val{42};
auto a1 = fmt::arg("a1_", a1_val);
store.push_back(std::cref(a1));

// Changing str affects the output but only for string and custom types.
str[0] = 'X';

std::string result = fmt::vformat("{} and {a1_}");
assert(result == "X234567890 and 42");

template<typename T>
inline void push_back(const detail::named_arg<char_type, T> &arg)¶

Adds named argument into the dynamic store for later passing to a formatting function.

std::reference_wrapper is supported to avoid copying of the argument.

inline void clear()¶

Erase all elements from the store.

inline void reserve(size_t new_cap, size_t new_cap_named)¶

Reserves space to store at least new_cap arguments including new_cap_named named arguments.

template<typename Context>
class fmt::basic_format_args¶

A view of a collection of formatting arguments. To avoid lifetime issues it should only be used as a parameter type in type-erased functions such as vformat:

void vlog(string_view format_str, format_args args);  // OK
format_args args = make_format_args(42);  // Error: dangling reference

Public Functions

template<typename ...Args>
inline basic_format_args(const format_arg_store<Context, Args...> &store)¶

Constructs a basic_format_args() object from format_arg_store.

inline basic_format_args(const dynamic_format_arg_store<Context> &store)¶

Constructs a basic_format_args() object from dynamic_format_arg_store.

inline basic_format_args(const format_arg *args, int count)¶

Constructs a basic_format_args() object from a dynamic set of arguments.

inline format_arg get(int id) const¶

Returns the argument with the specified id.

struct format_args : public fmt::basic_format_args<format_context>¶

template<typename Context>
class basic_format_arg¶

Compatibility¶

template<typename Char>
class fmt::basic_string_view¶

An implementation of std::basic_string_view for pre-C++17.

It provides a subset of the API. fmt::basic_string_view is used for format strings even if std::string_view is available to prevent issues when a library is compiled with a different -std option than the client code (which is not recommended).

Public Functions

inline constexpr basic_string_view(const Char *s, size_t count)¶

Constructs a string reference object from a C string and a size.

inline basic_string_view(const Char *s)¶

Constructs a string reference object from a C string computing the size with std::char_traits<Char>::length.

template<typename Traits, typename Alloc>
inline basic_string_view(const std::basic_string<Char, Traits, Alloc> &s)¶

Constructs a string reference from a std::basic_string object.

inline constexpr const Char *data() const¶

Returns a pointer to the string data.

inline constexpr size_t size() const¶

Returns the string size.

using fmt::string_view = basic_string_view<char>¶

using fmt::wstring_view = basic_string_view<wchar_t>¶

Locale¶

All formatting is locale-independent by default. Use the 'L' format specifier to insert the appropriate number separator characters from the locale:

#include <fmt/core.h>
#include <locale>

std::locale::global(std::locale("en_US.UTF-8"));
auto s = fmt::format("{:L}", 1000000);  // s == "1,000,000"

Compile-time Format String Checks¶

Compile-time checks are enabled when using FMT_STRING. They support built-in and string types as well as user-defined types with constexpr parse functions in their formatter specializations.

FMT_STRING(s)¶

Constructs a compile-time format string from a string literal s.

Example:

// A compile-time error because 'd' is an invalid specifier for strings.
std::string s = fmt::format(FMT_STRING("{:d}"), "foo");

Formatting User-defined Types¶

To make a user-defined type formattable, specialize the formatter<T> struct template and implement parse and format methods:

#include <fmt/format.h>

struct point { double x, y; };

template <>
struct fmt::formatter<point> {
  // Presentation format: 'f' - fixed, 'e' - exponential.
  char presentation = 'f';

  // Parses format specifications of the form ['f' | 'e'].
  constexpr auto parse(format_parse_context& ctx) {
  // auto parse(format_parse_context &ctx) -> decltype(ctx.begin()) // c++11
    // [ctx.begin(), ctx.end()) is a character range that contains a part of
    // the format string starting from the format specifications to be parsed,
    // e.g. in
    //
    //   fmt::format("{:f} - point of interest", point{1, 2});
    //
    // the range will contain "f} - point of interest". The formatter should
    // parse specifiers until '}' or the end of the range. In this example
    // the formatter should parse the 'f' specifier and return an iterator
    // pointing to '}'.

    // Parse the presentation format and store it in the formatter:
    auto it = ctx.begin(), end = ctx.end();
    if (it != end && (*it == 'f' || *it == 'e')) presentation = *it++;

    // Check if reached the end of the range:
    if (it != end && *it != '}')
      throw format_error("invalid format");

    // Return an iterator past the end of the parsed range:
    return it;
  }

  // Formats the point p using the parsed format specification (presentation)
  // stored in this formatter.
  template <typename FormatContext>
  auto format(const point& p, FormatContext& ctx) {
  // auto format(const point &p, FormatContext &ctx) -> decltype(ctx.out()) // c++11
    // ctx.out() is an output iterator to write to.
    return format_to(
        ctx.out(),
        presentation == 'f' ? "({:.1f}, {:.1f})" : "({:.1e}, {:.1e})",
        p.x, p.y);
  }
};

Then you can pass objects of type point to any formatting function:

point p = {1, 2};
std::string s = fmt::format("{:f}", p);
// s == "(1.0, 2.0)"

You can also reuse existing formatters via inheritance or composition, for example:

enum class color {red, green, blue};

template <> struct fmt::formatter<color>: formatter<string_view> {
  // parse is inherited from formatter<string_view>.
  template <typename FormatContext>
  auto format(color c, FormatContext& ctx) {
    string_view name = "unknown";
    switch (c) {
    case color::red:   name = "red"; break;
    case color::green: name = "green"; break;
    case color::blue:  name = "blue"; break;
    }
    return formatter<string_view>::format(name, ctx);
  }
};

Since parse is inherited from formatter<string_view> it will recognize all string format specifications, for example

fmt::format("{:>10}", color::blue)

will return "      blue".

You can also write a formatter for a hierarchy of classes:

#include <type_traits>
#include <fmt/format.h>

struct A {
  virtual ~A() {}
  virtual std::string name() const { return "A"; }
};

struct B : A {
  virtual std::string name() const { return "B"; }
};

template <typename T>
struct fmt::formatter<T, std::enable_if_t<std::is_base_of<A, T>::value, char>> :
    fmt::formatter<std::string> {
  template <typename FormatCtx>
  auto format(const A& a, FormatCtx& ctx) {
    return fmt::formatter<std::string>::format(a.name(), ctx);
  }
};

int main() {
  B b;
  A& a = b;
  fmt::print("{}", a); // prints "B"
}

If a type provides both a formatter specialization and an implicit conversion to a formattable type, the specialization takes precedence over the conversion.

template<typename Char, typename ErrorHandler = detail::error_handler>
class fmt::basic_format_parse_context : private fmt::detail::error_handler¶

Parsing context consisting of a format string range being parsed and an argument counter for automatic indexing.

You can use one of the following type aliases for common character types:

Type	Definition
format_parse_context	basic_format_parse_context<char>
wformat_parse_context	basic_format_parse_context<wchar_t>

Subclassed by fmt::detail::compile_parse_context< Char, ErrorHandler >, fmt::basic_printf_parse_context< Char >

Public Functions

inline constexpr iterator begin() const¶

Returns an iterator to the beginning of the format string range being parsed.

inline constexpr iterator end() const¶

Returns an iterator past the end of the format string range being parsed.

inline void advance_to(iterator it)¶

Advances the begin iterator to it.

inline int next_arg_id()¶

Reports an error if using the manual argument indexing; otherwise returns the next argument index and switches to the automatic indexing.

inline void check_arg_id(int)¶

Reports an error if using the automatic argument indexing; otherwise switches to the manual indexing.

Literal-based API¶

The following user-defined literals are defined in fmt/format.h.

inline detail::udl_formatter<char> fmt::operator""_format(const char *s, size_t n)¶

User-defined literal equivalent of fmt::format().

Example:

using namespace fmt::literals;
std::string message = "The answer is {}"_format(42);

inline detail::udl_arg<char> fmt::operator""_a(const char *s, size_t)¶

User-defined literal equivalent of fmt::arg().

Example:

using namespace fmt::literals;
fmt::print("Elapsed time: {s:.2f} seconds", "s"_a=1.23);

Utilities¶

template<typename T>
struct is_char : public std::false_type¶

Specifies if T is a character type.

Can be specialized by users.

template<typename S>
using fmt::char_t = typename detail::char_t_impl<S>::type¶

String’s character type.

template<typename T>
inline const void *fmt::ptr(const T *p)¶

Converts p to const void* for pointer formatting.

Example:

auto s = fmt::format("{}", fmt::ptr(p));

template<typename T>
inline const void *fmt::ptr(const std::unique_ptr<T> &p)¶

template<typename T>
inline const void *fmt::ptr(const std::shared_ptr<T> &p)¶

template<typename T>
inline std::string fmt::to_string(const T &value)¶

Converts value to std::string using the default format for type T.

Example:

#include <fmt/format.h>

std::string answer = fmt::to_string(42);

template<typename T>
inline std::wstring fmt::to_wstring(const T &value)¶

Converts value to std::wstring using the default format for type T.

template<typename Char>
inline basic_string_view<Char> fmt::to_string_view(const Char *s)¶

Returns a string view of s. In order to add custom string type support to {fmt} provide an overload of to_string_view() for it in the same namespace as the type for the argument-dependent lookup to work.

Example:

namespace my_ns {
inline string_view to_string_view(const my_string& s) {
  return {s.data(), s.length()};
}
}
std::string message = fmt::format(my_string("The answer is {}"), 42);

template<typename Range>
arg_join<detail::iterator_t<Range>, detail::sentinel_t<Range>, char> fmt::join(Range &&range, string_view sep)¶

Returns an object that formats range with elements separated by sep.

Example:

std::vector<int> v = {1, 2, 3};
fmt::print("{}", fmt::join(v, ", "));
// Output: "1, 2, 3"

fmt::join applies passed format specifiers to the range elements:

fmt::print("{:02}", fmt::join(v, ", "));
// Output: "01, 02, 03"

template<typename It, typename Sentinel>
arg_join<It, Sentinel, char> fmt::join(It begin, Sentinel end, string_view sep)¶

Returns an object that formats the iterator range [begin, end) with elements separated by sep.

template<typename T>
class fmt::detail::buffer¶

A contiguous memory buffer with an optional growing ability. It is an internal class and shouldn’t be used directly, only via basic_memory_buffer.

Subclassed by fmt::basic_memory_buffer< wchar_t >, fmt::basic_memory_buffer< T, SIZE, Allocator >, fmt::detail::iterator_buffer< OutputIt, T, Traits >, fmt::detail::iterator_buffer< T *, T >

Public Functions

inline size_t size() const¶

Returns the size of this buffer.

inline size_t capacity() const¶

Returns the capacity of this buffer.

inline T *data()¶

Returns a pointer to the buffer data.

inline const T *data() const¶

Returns a pointer to the buffer data.

inline void clear()¶

Clears this buffer.

template<typename U>
void append(const U *begin, const U *end)¶

Appends data to the end of the buffer.

template<typename T, size_t SIZE = inline_buffer_size, typename Allocator = std::allocator<T>>
class fmt::basic_memory_buffer : public fmt::detail::buffer<T>¶

A dynamically growing memory buffer for trivially copyable/constructible types with the first SIZE elements stored in the object itself.

You can use one of the following type aliases for common character types:

Type	Definition
memory_buffer	basic_memory_buffer<char>
wmemory_buffer	basic_memory_buffer<wchar_t>

Example:

fmt::memory_buffer out;
format_to(out, "The answer is {}.", 42);

This will append the following output to the out object:

The answer is 42.

The output can be converted to an std::string with to_string(out).

Public Functions

inline basic_memory_buffer(basic_memory_buffer &&other)¶

Constructs a fmt::basic_memory_buffer object moving the content of the other object to it.

inline basic_memory_buffer &operator=(basic_memory_buffer &&other)¶

Moves the content of the other basic_memory_buffer object to this one.

inline void resize(size_t count)¶

Resizes the buffer to contain count elements.

If T is a POD type new elements may not be initialized.

inline void reserve(size_t new_capacity)¶

Increases the buffer capacity to new_capacity.

Protected Functions

virtual void grow(size_t size) final¶

Increases the buffer capacity to hold at least capacity elements.

System Errors¶

fmt does not use errno to communicate errors to the user, but it may call system functions which set errno. Users should not make any assumptions about the value of errno being preserved by library functions.

class fmt::system_error : public std::runtime_error¶

An error returned by an operating system or a language runtime, for example a file opening error.

Subclassed by fmt::windows_error

Public Functions

template<typename ...Args>
inline system_error(int error_code, string_view message, const Args&... args)¶

Constructs a fmt::system_error object with a description formatted with fmt::format_system_error(). message and additional arguments passed into the constructor are formatted similarly to fmt::format().

Example:

// This throws a system_error with the description
//   cannot open file 'madeup': No such file or directory
// or similar (system message may vary).
const char *filename = "madeup";
std::FILE *file = std::fopen(filename, "r");
if (!file)
  throw fmt::system_error(errno, "cannot open file '{}'", filename);

void fmt::format_system_error(detail::buffer<char> &out, int error_code, string_view message)¶

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:

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

class fmt::windows_error : public fmt::system_error¶

A Windows error.

Public Functions

template<typename ...Args>
inline windows_error(int error_code, string_view message, const Args&... args)¶

Constructs a fmt::windows_error object with the description of the form

<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 Windows error code as given by GetLastError. If error_code is not a valid error code such as -1, the system message will look like “error -1”.

Example:

// This throws a windows_error with the description
//   cannot open file 'madeup': The system cannot find the file specified.
// or similar (system message may vary).
const char *filename = "madeup";
LPOFSTRUCT of = LPOFSTRUCT();
HFILE file = OpenFile(filename, &of, OF_READ);
if (file == HFILE_ERROR) {
  throw fmt::windows_error(GetLastError(),
                           "cannot open file '{}'", filename);
}

Custom Allocators¶

The {fmt} library supports custom dynamic memory allocators. A custom allocator class can be specified as a template argument to fmt::basic_memory_buffer:

using custom_memory_buffer =
  fmt::basic_memory_buffer<char, fmt::inline_buffer_size, custom_allocator>;

It is also possible to write a formatting function that uses a custom allocator:

using custom_string =
  std::basic_string<char, std::char_traits<char>, custom_allocator>;

custom_string vformat(custom_allocator alloc, fmt::string_view format_str,
                      fmt::format_args args) {
  custom_memory_buffer buf(alloc);
  fmt::vformat_to(buf, format_str, args);
  return custom_string(buf.data(), buf.size(), alloc);
}

template <typename ...Args>
inline custom_string format(custom_allocator alloc,
                            fmt::string_view format_str,
                            const Args& ... args) {
  return vformat(alloc, format_str, fmt::make_format_args(args...));
}

The allocator will be used for the output container only. Formatting functions normally don’t do any allocations for built-in and string types except for non-default floating-point formatting that occasionally falls back on sprintf.