"Fossies" - the Fresh Open Source Software Archive

Member "mkvtoolnix-40.0.0/lib/fmt/doc/api.rst" (9 Nov 2019, 11315 Bytes) of package /linux/misc/mkvtoolnix-40.0.0.tar.xz:


As a special service "Fossies" has tried to format the requested source page into HTML format (assuming markdown format). Alternatively you can here view or download the uninterpreted source code file. A member file download can also be achieved by clicking within a package contents listing on the according byte size field. See also the last Fossies "Diffs" side-by-side code changes report for "api.rst": 37.0.0_vs_38.0.0.

API Reference

The {fmt} library API consists of the following parts:

All functions and types provided by the library reside in namespace fmt and macros have prefix FMT_ or fmt.

Core API

fmt/core.h defines the core API which provides argument handling facilities and a lightweight subset of formatting functions.

The following functions use format string syntax <syntax> similar to that of Python's str.format. 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. A function taking format_str doesn't participate in an overload resolution if the latter is not a string.

args is an argument list representing objects to be formatted.

format(const S&, Args&&...)

vformat(const S&, basic_format_args<buffer_context<Char>>)

print(const S&, Args&&...)

vprint(string_view, format_args)

print(std::FILE *, const S&, Args&&...)

vprint(std::FILE *, string_view, format_args)

vprint(std::FILE *, wstring_view, wformat_args)

Named Arguments

fmt::arg(const S&, const T&)

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

Argument Lists

fmt::make_format_args(const Args&...)

fmt::format_arg_store

fmt::basic_format_args

fmt::format_args

fmt::basic_format_arg

Compatibility

fmt::basic_string_view

fmt::string_view

fmt::wstring_view

Format API

fmt/format.h defines the full format API providing compile-time format string checks, output iterator and user-defined type support.

Compile-time Format String Checks

FMT_STRING

fmt

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; };

namespace fmt {
template <>
struct formatter<point> {
  template <typename ParseContext>
  constexpr auto parse(ParseContext &ctx) { return ctx.begin(); }

  template <typename FormatContext>
  auto format(const point &p, FormatContext &ctx) {
    return format_to(ctx.out(), "({:.1f}, {:.1f})", 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("{}", p);
// s == "(1.0, 2.0)"

In the example above the formatter<point>::parse function ignores the contents of the format string referred to by ctx.begin() so the object will always be formatted in the same way. See formatter<tm>::parse in fmt/chrono.h for an advanced example of how to parse the format string and customize the formatted output.

You can also reuse existing formatters, 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);
  }
};

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"
}

Output Iterator Support

fmt::format_to(OutputIt, const S&, Args&&...)

fmt::format_to_n(OutputIt, std::size_t, string_view, Args&&...)

fmt::format_to_n_result

Literal-based API

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

operator""_format(const char *, std::size_t)

operator""_a(const char *, std::size_t)

Utilities

fmt::is_char

fmt::char_t

fmt::formatted_size(string_view, const Args&...)

fmt::to_string(const T&)

fmt::to_wstring(const T&)

fmt::to_string_view(const Char *)

fmt::join(const Range&, string_view)

fmt::join(It, It, string_view)

fmt::basic_memory_buffer

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.

fmt::system_error

fmt::format_system_error

fmt::windows_error

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. If you are using named arguments, the container that stores pointers to them will be allocated using the default allocator. Also floating-point formatting falls back on sprintf which may do allocations.

Custom Formatting of Built-in Types

It is possible to change the way arguments are formatted by providing a custom argument formatter class:

using arg_formatter =
  fmt::arg_formatter<fmt::back_insert_range<fmt::internal::buffer>>;

// A custom argument formatter that formats negative integers as unsigned
// with the ``x`` format specifier.
class custom_arg_formatter : public arg_formatter {
 public:
  custom_arg_formatter(fmt::format_context &ctx,
                       fmt::format_specs *spec = nullptr)
    : arg_formatter(ctx, spec) {}

  using arg_formatter::operator();

  auto operator()(int value) {
    if (spec().type() == 'x')
      return (*this)(static_cast<unsigned>(value)); // convert to unsigned and format
    return arg_formatter::operator()(value);
  }
};

std::string custom_vformat(fmt::string_view format_str, fmt::format_args args) {
  fmt::memory_buffer buffer;
  // Pass custom argument formatter as a template arg to vformat_to.
  fmt::vformat_to<custom_arg_formatter>(buffer, format_str, args);
  return fmt::to_string(buffer);
}

template <typename ...Args>
inline std::string custom_format(
    fmt::string_view format_str, const Args &... args) {
  return custom_vformat(format_str, fmt::make_format_args(args...));
}

std::string s = custom_format("{:x}", -42); // s == "ffffffd6"

fmt::arg_formatter

Date and Time Formatting

The library supports strftime-like date and time formatting:

#include <fmt/chrono.h>

std::time_t t = std::time(nullptr);
// Prints "The date is 2016-04-29." (with the current date)
fmt::print("The date is {:%Y-%m-%d}.", *std::localtime(&t));

The format string syntax is described in the documentation of strftime.

std::ostream Support

fmt/ostream.h provides std::ostream support including formatting of user-defined types that have overloaded operator<<:

#include <fmt/ostream.h>

class date {
  int year_, month_, day_;
public:
  date(int year, int month, int day): year_(year), month_(month), day_(day) {}

  friend std::ostream &operator<<(std::ostream &os, const date &d) {
    return os << d.year_ << '-' << d.month_ << '-' << d.day_;
  }
};

std::string s = fmt::format("The date is {}", date(2012, 12, 9));
// s == "The date is 2012-12-9"

print(std::basic_ostream<Char>&, const S&, Args&&...)

printf Formatting

The header fmt/printf.h provides printf-like formatting functionality. The following functions use printf format string syntax with the POSIX extension for positional arguments. Unlike their standard counterparts, the fmt functions are type-safe and throw an exception if an argument type doesn't match its format specification.

printf(const S&, const Args&...)

fprintf(std::FILE *, const S&, const Args&...)

fprintf(std::basic_ostream<Char>&, const S&, const Args&...)

sprintf(const S&, const Args&...)