API Reference¶

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");

To force the use of compile-time checks, define the preprocessor variable FMT_ENFORCE_COMPILE_STRING. When set, functions accepting FMT_STRING will fail to compile with regular strings. Runtime-checked formatting is still possible using fmt::vformat, fmt::vprint, etc.

Named Arguments¶

template<typename Char, typename T>
auto fmt::arg(const Char *name, const T &arg)¶

Returns a named argument to be used in a formatting function. It should only be used in a call to a formatting function or dynamic_format_arg_store::push_back.

Example:

fmt::print("Elapsed time: {s:.2f} seconds", fmt::arg("s", 1.23));

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>>
auto fmt::make_args_checked(const S &fmt, const remove_reference_t<Args>&... args)¶

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

template<typename Context = format_context, typename ...Args>
constexpr auto 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 dynamic_format_arg_store¶

template<typename Context>
class 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>
constexpr basic_format_args(const format_arg_store<Context, Args...> &store)¶

Constructs a basic_format_args object from format_arg_store.

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

Constructs a basic_format_args object from dynamic_format_arg_store.

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

Constructs a basic_format_args object from a dynamic set of arguments.

auto get(int id) const¶

Returns the argument with the specified id.

using fmt::format_args = basic_format_args<format_context>¶

An alias to basic_format_args<format_context>.

template<typename Context>
class basic_format_arg¶

template<typename OutputIt, typename Char>
class basic_format_context¶

Public Types

template<>
using char_type = Char¶

The character type for the output.

Public Functions

constexpr basic_format_context(OutputIt out, basic_format_args<basic_format_context> ctx_args, detail::locale_ref loc = detail::locale_ref())¶

Constructs a basic_format_context object.

References to the arguments are stored in the object so make sure they have appropriate lifetimes.

using fmt::format_context = buffer_context<char>¶

Compatibility¶

template<typename Char>
class 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

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

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

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>
basic_string_view(const std::basic_string<Char, Traits, Alloc> &s)¶

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

constexpr auto data() const¶

Returns a pointer to the string data.

constexpr auto size() const¶

Returns the string size.

using fmt::string_view = basic_string_view<char>¶

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"

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) -> decltype(ctx.begin()) {
    // [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) -> decltype(ctx.out()) {
    // 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 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 the `format_parse_context type alias for char instead.

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

Public Functions

constexpr auto begin() const¶

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

constexpr auto end() const¶

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

void advance_to(iterator it)¶

Advances the begin iterator to it.

auto next_arg_id()¶

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

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.

- constexpr auto fmt::literals::operator""_format(const char*, size_t)
- constexpr auto fmt::literals::operator""_format(const wchar_t*, size_t)

- constexpr auto fmt::literals::operator""_a(const char*, size_t)
- constexpr detail::udl_arg<wchar_t> fmt::literals::operator""_a(const wchar_t*, size_t)

Utilities¶

- template<typename T>
  auto fmt::ptr(T)
- template<typename T>
  auto fmt::ptr(const std::shared_ptr<T>&)
- template<typename T>
  auto fmt::ptr(const std::unique_ptr<T>&)

- template<typename T>
  auto fmt::ptr(T)
- template<typename T>
  auto fmt::ptr(const std::shared_ptr<T>&)
- template<typename T>
  auto fmt::ptr(const std::unique_ptr<T>&)

- template<typename T>
  auto fmt::ptr(T)
- template<typename T>
  auto fmt::ptr(const std::shared_ptr<T>&)
- template<typename T>
  auto fmt::ptr(const std::unique_ptr<T>&)

- template<typename Char, size_t SIZE>
  auto fmt::to_string(const basic_memory_buffer<Char, SIZE>&)
- template<typename T>
  auto fmt::to_string(T)
- template<typename T>
  auto fmt::to_string(const T&)

- template<typename Char, typename Traits, typename Alloc>
  auto fmt::to_string_view(const std::basic_string<Char, Traits, Alloc>&)
- template<typename Char>
  auto fmt::to_string_view(const Char*)
- template<typename Char>
  auto fmt::to_string_view(detail::std_string_view<Char>)
- template<typename Char>
  constexpr auto fmt::to_string_view(basic_string_view<Char>)
- template<typename S>
  constexpr auto fmt::to_string_view(const S&)

- template<typename It, typename Sentinel>
  auto fmt::join(It, Sentinel, string_view)
- template<typename It, typename Sentinel>
  auto fmt::join(It, Sentinel, wstring_view)
- template<typename Range>
  auto fmt::join(Range&&, string_view)
- template<typename Range>
  auto fmt::join(Range&&, wstring_view)
- template<typename T>
  auto fmt::join(std::initializer_list<T>, wstring_view)

- template<typename It, typename Sentinel>
  auto fmt::join(It, Sentinel, string_view)
- template<typename It, typename Sentinel>
  auto fmt::join(It, Sentinel, wstring_view)
- template<typename Range>
  auto fmt::join(Range&&, string_view)
- template<typename Range>
  auto fmt::join(Range&&, wstring_view)
- template<typename T>
  auto fmt::join(std::initializer_list<T>, wstring_view)

template<typename T>
class 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

auto size() const¶

Returns the size of this buffer.

auto capacity() const¶

Returns the capacity of this buffer.

auto data()¶

Returns a pointer to the buffer data.

auto data() const¶

Returns a pointer to the buffer data.

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 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 the `memory_buffer type alias for char instead.

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

basic_memory_buffer(basic_memory_buffer &&other)¶

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

auto operator=(basic_memory_buffer &&other)¶

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

void resize(size_t count)¶

Resizes the buffer to contain count elements.

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

void reserve(size_t new_capacity)¶

Increases the buffer capacity to new_capacity.

Protected Functions

void grow(size_t capacity)¶

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.

template<typename ...T>
auto fmt::system_error(int error_code, format_string<T...> fmt, T&&... args)¶

Constructs std::system_error with a message formatted with fmt::format(fmt, args...).

error_code is a system error code as given by errno.

Example:

// This throws std::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, const char *message)¶

Formats an error message for an error returned by an operating system or a language runtime, for example a file opening error, and writes it to out. The format is the same as the one used by std::system_error(ec, message) where ec is std::error_code(error_code, std::generic_category()}). It is implementation-defined but normally looks like:

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

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.