APIリファレンス

{fmt}ライブラリのAPIは、次の構成要素からなります。

• fmt/base.h：C++20のコンパイル時チェックと最小限の依存関係を備えた、char/UTF-8向けの主要な書式設定関数を提供する基本API
• fmt/format.h：fmt::formatなどの書式設定関数とロケールサポート
• fmt/ranges.h：範囲とタプルの書式設定
• fmt/chrono.h：日付と時刻の書式設定
• fmt/std.h：標準ライブラリ型のフォーマッター
• fmt/compile.h：書式文字列のコンパイル
• fmt/color.h：端末の色とテキストスタイル
• fmt/os.h：システムAPI
• fmt/ostream.h：std::ostreamのサポート
• fmt/args.h：動的な引数リスト
• fmt/printf.h：安全なprintf
• fmt/xchar.h：任意で利用できるwchar_tサポート

ライブラリが提供するすべての関数と型はfmt名前空間に置かれ、マクロにはFMT_接頭辞が付きます。

C++モジュールAPI

C++モジュールAPIを使う場合、上に挙げたヘッダーをインクルードする必要はありません。代わりにimport fmt;文を使えます。以下で説明するその他の機能はすべて同じです。

基本API

fmt/base.hは、C++20のコンパイル時チェックを備えたchar/UTF-8向けの主要な書式設定関数を提供する基本APIを定義します。コンパイル時間を短くするため、インクルードする依存ヘッダーを最小限に抑えています。このヘッダーの利点が得られるのは、{fmt}を既定のライブラリ形式で使う場合だけで、ヘッダーのみのモードではありません。また、次の型に対するformatterの特殊化も提供します。

• int, long long
• unsigned, unsigned long long
• float, double, long double
• bool
• char
• const char*, fmt::string_view
• const void*

次の関数は、Pythonのstr.formatに似た書式文字列の構文を使います。fmtとargsを引数として受け取ります。

fmtは、通常のテキストと、波括弧{}で囲まれた置換フィールドを含む書式文字列です。結果の文字列では、フィールドが書式設定された引数に置き換わります。fmt::format_stringは、文字列リテラルまたはconstexpr文字列から暗黙に構築できる書式文字列で、C++20ではコンパイル時に検査されます。実行時の書式文字列を渡すには、fmt::runtimeで包みます。

argsは、書式設定するオブジェクトを表す引数リストです。

別途指定されていない限り、入出力エラーはstd::system_error例外として報告されます。

template <typename... T>
void print(format_string<T...> fmt, T&&... args);

fmt::print("The answer is {}.", 42);
 

template <typename... T>
void print(FILE* f, format_string<T...> fmt, T&&... args);

fmt::print(stderr, "Don't {}!", "panic");
 

template <typename... T>
void println(format_string<T...> fmt, T&&... args);

template <typename... T>
void println(FILE* f, format_string<T...> fmt, T&&... args);

template <typename OutputIt, typename... T>
remove_cvref_t<OutputIt> format_to(OutputIt&& out, format_string<T...> fmt, T&&... args);

auto out = std::vector<char>();
fmt::format_to(std::back_inserter(out), "{}", 42);
 

template <typename OutputIt, typename... T>
format_to_n_result<OutputIt> format_to_n(OutputIt out, size_t n, format_string<T...> fmt, T&&... args);

template <typename OutputIt>
struct format_to_n_result;

OutputIt out;

size_t size;

template <typename... T>
size_t formatted_size(format_string<T...> fmt, T&&... args);

ユーザー定義型の書式設定

{fmt}ライブラリは、多くの標準C++型に対するフォーマッターを提供します。std::vectorなどの標準コンテナーを含む範囲とタプルについてはfmt/ranges.h、日付と時刻の書式設定についてはfmt/chrono.h、その他の標準ライブラリ型についてはfmt/std.hを参照してください。

ユーザー定義型を書式設定可能にする方法は2つあります。format_as関数を提供する方法と、formatter構造体テンプレートを特殊化する方法です。void型以外を指すポインター型の書式設定は意図的に禁止されており、どちらの拡張APIを使っても書式設定可能にはできません。

型を別の型として、同じ書式指定子で書式設定可能にしたい場合は、format_asを使います。format_as関数は、その型のオブジェクトを受け取り、書式設定可能な型のオブジェクトを返すようにします。この関数は、対象の型と同じ名前空間に定義するようにします。

例（実行）：

#include <fmt/format.h>

namespace kevin_namespacy {

enum class film {
  house_of_cards, american_beauty, se7en = 7
};

auto format_as(film f) { return fmt::underlying(f); }

}

int main() {
  fmt::print("{}\n", kevin_namespacy::film::se7en); // Output: 7
}

特殊化を使う方法はより複雑ですが、解析と書式設定を完全に制御できます。この方法を使うには、対象の型についてformatter構造体テンプレートを特殊化し、parseメソッドとformatメソッドを実装します。

フォーマッターの定義では、継承またはコンポジションによって既存のフォーマッターを再利用する方法が推奨されます。こうすると、標準の書式指定子を自分で実装せずにサポートできます。例：

// color.h:
#include <fmt/base.h>

enum class color {red, green, blue};

template <> struct fmt::formatter<color>: formatter<string_view> {
  // parse is inherited from formatter<string_view>.

  auto format(color c, format_context& ctx) const
    -> format_context::iterator;
};

// color.cc:
#include "color.h"
#include <fmt/format.h>

auto fmt::formatter<color>::format(color c, format_context& ctx) const
    -> format_context::iterator {
  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);
}

formatter<string_view>::formatはfmt/format.hに定義されているため、このヘッダーをソースファイルにインクルードする必要があります。parseはformatter<string_view>から継承されるので、文字列の書式指定をすべて認識します。たとえば、

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

は" blue"を返します。

一般に、フォーマッターは次の形を取ります。

template <> struct fmt::formatter<T> {
  // Parses format specifiers and stores them in the formatter.
  //
  // [ctx.begin(), ctx.end()) is a, possibly empty, character range that
  // contains a part of the format string starting from the format
  // specifications to be parsed, e.g. in
  //
  //   fmt::format("{:f} continued", ...);
  //
  // the range will contain "f} continued". 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 '}'.
  constexpr auto parse(format_parse_context& ctx)
    -> format_parse_context::iterator;

  // Formats value using the parsed format specification stored in this
  // formatter and writes the output to ctx.out().
  auto format(const T& value, format_context& ctx) const
    -> format_context::iterator;
};

少なくとも、オブジェクト全体に適用され、標準フォーマッターと同じ意味を持つfill、align、widthをサポートすることが推奨されます。

クラス階層に対するフォーマッターも記述できます。

// demo.h:
#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_v<A, T>, char>> :
    fmt::formatter<std::string> {
  auto format(const A& a, format_context& ctx) const {
    return formatter<std::string>::format(a.name(), ctx);
  }
};

// demo.cc:
#include "demo.h"
#include <fmt/format.h>

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

formatterの特殊化とformat_asのオーバーロードを両方提供することは禁止されています。

template <typename Char>
using basic_format_parse_context = parse_context<Char>;

class context;

constexpr context(iterator out, format_args args, locale_ref loc);

using format_context = context;

コンパイル時チェック

C++20のconstevalをサポートするコンパイラーでは、書式文字列のコンパイル時チェックが既定で有効です。古いコンパイラーでは、代わりにfmt/format.hで定義されたFMT_STRINGマクロを使えます。

Pythonのstr.formatや通常の関数と同様に、使われない引数を渡すこともできます。

テンプレートによるコードの肥大化を避けながら、fmt::format_stringを使って独自の関数でコンパイル時チェックを有効にする例は、「型消去」を参照してください。

template <typename... T>
struct fstring;

template <typename... T>
using format_string = typename fstring<T...>::t;

runtime_format_string<> runtime(string_view s);

// Check format string at runtime instead of compile-time.
fmt::print(fmt::runtime("{:d}"), "I am not a number");
 

型消去

コンパイル時チェックを備え、バイナリーサイズを小さく抑えた独自の書式設定関数を作成できます。例（実行）：

#include <fmt/format.h>

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

template <typename... T>
void log(const char* file, int line,
         fmt::format_string<T...> fmt, T&&... args) {
  vlog(file, line, fmt, fmt::make_format_args(args...));
}

#define MY_LOG(fmt, ...) log(__FILE__, __LINE__, fmt, __VA_ARGS__)

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

vlogは引数の型をパラメーター化していないため、すべてをパラメーター化した版と比べて、コンパイル時間が短くなり、バイナリーのコードサイズも小さくなります。

template <typename Context, typename... T, int NUM_ARGS, int NUM_NAMED_ARGS, ullong DESC>
detail::format_arg_store<Context, NUM_ARGS, NUM_NAMED_ARGS, DESC> make_format_args(T&... args);

template <typename Context>
class basic_format_args;

void vlog(fmt::string_view fmt, fmt::format_args args);  // OK
fmt::format_args args = fmt::make_format_args();  // Dangling reference
 

constexpr basic_format_args(const store<NUM_ARGS, NUM_NAMED_ARGS, DESC>& s);

constexpr basic_format_args(const format_arg* args, int count, bool has_named);

format_arg get(int id);

using format_args = basic_format_args<context>;

template <typename Context>
class basic_format_arg;

decltype(vis(0)) visit(Visitor&& vis);

名前付き引数

template <typename T>
named_arg<T> arg(const char* name, const T& arg);

fmt::print("The answer is {answer}.", fmt::arg("answer", 42));

互換性

template <typename Char>
class basic_string_view;

using string_view = basic_string_view<char>;

書式設定API

fmt/format.hは、追加の書式設定関数とロケールサポートを提供する、完全な書式設定APIを定義します。

template <typename... T>
std::string format(format_string<T...> fmt, T&&... args);

#include <fmt/format.h>
std::string message = fmt::format("The answer is {}.", 42);
 

std::string vformat(string_view fmt, format_args args);

template <detail::fixed_string S>
auto operator""_a();

using namespace fmt::literals;
fmt::print("The answer is {answer}.", "answer"_a=42);
 

ユーティリティー

template <typename T>
const void* ptr(T p);

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

template <typename Enum>
underlying_t<Enum> underlying(Enum e);

enum class color { red, green, blue };
auto s = fmt::format("{}", fmt::underlying(color::red));  // s == "0"
 

template <typename T>
std::string to_string(const T& value);

template <typename T>
group_digits_view<T> group_digits(T value);

fmt::print("{}", fmt::group_digits(12345));
// Output: "12,345"
 

template <typename T>
class detail::buffer;

size_t size();

size_t capacity();

T * data();

void clear();

void append(const U* begin, const U* end);

template <typename T, size_t SIZE, typename Allocator>
class basic_memory_buffer;

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

basic_memory_buffer(basic_memory_buffer&& other);

basic_memory_buffer & operator=(basic_memory_buffer&& other);

void resize(size_t count);

void reserve(size_t new_capacity);

システムエラー

{fmt}は利用者にエラーを伝えるためにerrnoを使いませんが、errnoを設定するシステム関数を呼び出すことがあります。ライブラリ関数がerrnoの値を保持するとは想定しないようにしてください。

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

// 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";
FILE* file = fopen(filename, "r");
if (!file)
  throw fmt::system_error(errno, "cannot open file '{}'", filename);
 

void format_system_error(detail::buffer<char>& out, int error_code, const char* message);

<message>: <system-message>

カスタムアロケーター

{fmt}ライブラリは、カスタムの動的メモリーアロケーターをサポートします。fmt::basic_memory_bufferのテンプレート引数として、カスタムアロケーターのクラスを指定できます。

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

カスタムアロケーターを使う書式設定関数を記述することもできます。

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

auto vformat(custom_allocator alloc, fmt::string_view fmt,
             fmt::format_args args) -> custom_string {
  auto buf = custom_memory_buffer(alloc);
  fmt::vformat_to(std::back_inserter(buf), fmt, args);
  return custom_string(buf.data(), buf.size(), alloc);
}

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

このアロケーターが使われるのは、出力コンテナーだけです。書式設定関数は通常、組み込み型と文字列型に対してメモリーを割り当てません。ただし、既定以外の浮動小数点書式では、場合によってsprintfにフォールバックする例外があります。

ロケール

すべての書式設定は、既定ではロケールに依存しません。ロケールに応じた数値の区切り文字を挿入するには、'L'書式指定子を使います。

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

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

fmt/format.hは、std::localeをパラメーターとして受け取る、次の書式設定関数のオーバーロードを提供します。コストの高い<locale>のインクルードを避けるため、ロケールの型はテンプレートパラメーターになっています。

template <typename... T>
std::string format(locale_ref loc, format_string<T...> fmt, T&&... args);

template <typename OutputIt, typename... T>
OutputIt format_to(OutputIt out, locale_ref loc, format_string<T...> fmt, T&&... args);

template <typename... T>
size_t formatted_size(locale_ref loc, format_string<T...> fmt, T&&... args);

従来のコンパイル時チェック

FMT_STRINGは、古いコンパイラーでコンパイル時チェックを有効にします。C++14以降が必要で、C++11では何も行いません。

FMT_STRING(s)

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

従来のコンパイル時チェックの使用を強制するには、プリプロセッサー変数FMT_ENFORCE_COMPILE_STRINGを定義します。これを設定すると、FMT_STRINGを受け取る関数に通常の文字列を渡した場合、コンパイルが失敗します。

範囲とタプルの書式設定

fmt/ranges.hは、範囲とタプルの書式設定をサポートします。

#include <fmt/ranges.h>

fmt::print("{}", std::tuple<char, int>{'a', 42});
// Output: ('a', 42)

fmt::joinを使うと、任意の区切り文字でタプルの要素を区切れます。

#include <fmt/ranges.h>

auto t = std::tuple<int, char>{1, 'a'};
fmt::print("{}", fmt::join(t, ", "));
// Output: 1, a

template <typename Range>
join_view<decltype(detail::range_begin(r)), decltype(detail::range_end(r))> join(Range&& r, string_view sep);

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

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

template <typename It, typename Sentinel>
join_view<It, Sentinel> join(It begin, Sentinel end, string_view sep);

template <typename T>
join_view<const T*, const T*> join(std::initializer_list<T> list, string_view sep);

fmt::print("{}", fmt::join({1, 2, 3}, ", "));
// Output: "1, 2, 3"
 

日付と時刻の書式設定

fmt/chrono.hは、次の型のフォーマッターを提供します。

• std::chrono::duration
• std::chrono::time_point
• std::tm

書式の構文は、「Chronoの書式指定」で説明しています。

例：

#include <fmt/chrono.h>

int main() {
  auto now = std::chrono::system_clock::now();

  fmt::print("The date is {:%Y-%m-%d}.\n", now);
  // Output: The date is 2020-11-07.
  // (with 2020-11-07 replaced by the current date)

  using namespace std::literals::chrono_literals;

  fmt::print("Default format: {} {}\n", 42s, 100ms);
  // Output: Default format: 42s 100ms

  fmt::print("strftime-like format: {:%H:%M:%S}\n", 3h + 15min + 30s);
  // Output: strftime-like format: 03:15:30
}

std::tm gmtime(std::time_t time);

標準ライブラリ型の書式設定

fmt/std.hは、次の型のフォーマッターを提供します。

• std::atomic
• std::atomic_flag
• std::bitset
• std::error_code
• std::exception
• std::filesystem::path
• std::monostate
• std::optional
• std::source_location
• std::thread::id
• std::variant

template <typename T, typename Deleter>
const void* ptr(const std::unique_ptr<T, Deleter>& p);

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

バリアント

std::variantを書式設定できるのは、すべての選択肢の型が書式設定可能な場合だけです。また、ライブラリー機能__cpp_lib_variantが必要です。

例：

#include <fmt/std.h>

fmt::print("{}", std::variant<char, float>('x'));
// Output: variant('x')

fmt::print("{}", std::variant<std::monostate, char>());
// Output: variant(monostate)

ビットフィールドとパックされた構造体

ビットフィールドや、__attribute__((packed))を適用した構造体のフィールドを書式設定するには、キャストまたは単項+によって、基底型または互換性のある型に変換する必要があります（godbolt）。

struct smol {
  int bit : 1;
};

auto s = smol();
fmt::print("{}", +s.bit);

これは、C++の「完全」転送に関する既知の制限です。

コンパイル時のサポート

fmt/compile.hは、書式文字列のコンパイルと、コンパイル時（constexpr）の書式設定を提供します。これらはFMT_COMPILEマクロ、またはfmt::literals名前空間で定義されたユーザー定義リテラル_cfで有効になります。FMT_COMPILEまたは_cfを付けた書式文字列は、コンパイル時に解析・検査され、効率的な書式設定コードへ変換されます。組み込み型と文字列型の引数に加え、formatterの特殊化で、書式設定コンテキストの型をテンプレートパラメーターとして受け取るformatメソッドを持つユーザー定義型もサポートします。例（実行）：

struct point {
  double x;
  double y;
};

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

  template <typename FormatContext>
  auto format(const point& p, FormatContext& ctx) const {
    return format_to(ctx.out(), "({}, {})"_cf, p.x, p.y);
  }
};

using namespace fmt::literals;
std::string s = fmt::format("{}"_cf, point(4, 2));

書式文字列のコンパイルでは、既定のAPIより多くのバイナリーコードが生成されることがあります。書式設定が性能のボトルネックになっている箇所でのみ、使用が推奨されます。

同じAPIは、constexpr関数やconsteval関数などでのコンパイル時の書式設定もサポートします。さらに、必要なサイズと厳密に一致する文字列へコンパイル時に書式設定できる、実験的なFMT_STATIC_FORMATもあります。コンパイル時の書式設定は、constexprのformatメソッドを持つ、組み込みおよびユーザー定義のフォーマッターで利用できます。例：

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

  template <typename FormatContext>
  constexpr auto format(const point& p, FormatContext& ctx) const {
    return format_to(ctx.out(), "({}, {})"_cf, p.x, p.y);
  }
};

constexpr auto s = FMT_STATIC_FORMAT("{}", point(4, 2));
const char* cstr = s.c_str(); // Points the static string "(4, 2)".

template <detail::fixed_string Str>
auto operator""_cf();

FMT_COMPILE(s)

// Converts 42 into std::string using the most efficient method and no
// runtime format string processing.
std::string s = fmt::format(FMT_COMPILE("{}"), 42);
 

FMT_STATIC_FORMAT(fmt_str, ...)

// Produces the static string "42" at compile time.
static constexpr auto result = FMT_STATIC_FORMAT("{}", 42);
const char* s = result.c_str();
 

端末の色とテキストスタイル

fmt/color.hは、端末の色とテキストスタイルを指定した出力をサポートします。

template <typename... T>
void print(text_style ts, format_string<T...> fmt, T&&... args);

fmt::print(fmt::emphasis::bold | fg(fmt::color::red),
           "Elapsed time: {0:.2f} seconds", 1.23);
 

text_style fg(detail::color_type foreground);

text_style bg(detail::color_type background);

template <typename T>
detail::styled_arg<remove_cvref_t<T>> styled(const T& value, text_style ts);

fmt::print("Elapsed time: {0:.2f} seconds",
           fmt::styled(1.23, fmt::fg(fmt::color::green) |
                             fmt::bg(fmt::color::blue)));
 

システムAPI

class ostream;

void print(format_string<T...> fmt, T&&... args);

template <typename... T>
ostream output_file(cstring_view path, T... params);

auto out = fmt::output_file("guide.txt");
out.print("Don't {}", "Panic");
 

template <typename... T>
std::system_error windows_error(int error_code, string_view message, const T&... args);

<message>: <system-message>

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

std::ostreamのサポート

fmt/ostream.hは、挿入演算子（operator<<）をオーバーロードしたユーザー定義型の書式設定など、std::ostreamのサポートを提供します。std::ostreamを通して型を書式設定可能にするには、ostream_formatterから継承したformatterの特殊化を提供するようにします。

#include <fmt/ostream.h>

struct date {
  int year, month, day;

  friend std::ostream& operator<<(std::ostream& os, const date& d) {
    return os << d.year << '-' << d.month << '-' << d.day;
  }
};

template <> struct fmt::formatter<date> : ostream_formatter {};

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

template <typename T>
detail::streamed_view<T> streamed(const T& value);

fmt::print("Current thread id: {}\n",
           fmt::streamed(std::this_thread::get_id()));
 

template <typename... T>
void print(std::ostream& os, format_string<T...> fmt, T&&... args);

fmt::print(cerr, "Don't {}!", "panic");
 

動的な引数リスト

ヘッダーfmt/args.hは、書式設定引数のリストを動的に構築できる、ビルダーのようなAPIであるdynamic_format_arg_storeを提供します。

template <typename Context>
class dynamic_format_arg_store;

void push_back(const T& arg);

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

void push_back(std::reference_wrapper<T> arg);

fmt::dynamic_format_arg_store<fmt::format_context> store;
char band[] = "Rolling Stones";
store.push_back(std::cref(band));
band[9] = 'c'; // Changing str affects the output.
std::string result = fmt::vformat("{}", store);
// result == "Rolling Scones"
 

void push_back(const named_arg<T, char_type>& arg);

void clear();

void reserve(size_t new_cap, size_t new_cap_named);

size_t size();

安全なprintf

ヘッダーfmt/printf.hは、printfに似た書式設定機能を提供します。次の関数は、位置指定引数のPOSIX拡張を含むprintfの書式文字列構文を使います。対応する標準関数とは異なり、fmtの関数は型安全で、引数の型が書式指定に合わない場合は例外を送出します。

template <typename... T>
int printf(string_view fmt, const T&... args);

template <typename... T>
int fprintf(std::FILE* f, string_view fmt, const T&... args);

fmt::fprintf(stderr, "Don't %s!", "panic");
 

template <typename... T>
std::string sprintf(string_view fmt, const T&... args);

std::string message = fmt::sprintf("The answer is %d", 42);
 

ワイド文字列

任意で利用するヘッダーfmt/xchar.hは、wchar_tや特殊な文字型のサポートを提供します。

using wstring_view = basic_string_view<wchar_t>;

using wformat_context = buffered_context<wchar_t>;

template <typename T>
std::wstring to_wstring(const T& value);

C++20のstd::formatとの互換性

{fmt}は、次の相違点を除き、C++20の書式設定ライブラリーのほぼすべてを実装しています。

• 標準ライブラリーの実装との衝突を避けるため、名前はstdではなくfmt名前空間に定義されます。

• 幅の計算では、書記素クラスターへの分割を使いません。これは別のブランチでは実装されていますが、まだ統合されていません。

• {fmt}の既定の浮動小数点表現は、JavaやPythonなどの他の言語と同様に、ラウンドトリップを保証できる最小の精度を使います。std::formatは現在、std::to_charsに基づいて規定されています。std::to_charsは、指数の冗長な桁と符号を無視して、文字数を最小にしようとするため、必要以上の十進桁を出力することがあります。

設定オプション

{fmt}は、機能の有効・無効の切り替えやバイナリーサイズの最適化のために、CMakeオプションとプリプロセッサーマクロによる設定を提供します。たとえば、CMakeの設定時に-DFMT_OS=OFFを指定すると、fmt/os.hで定義されたOS固有のAPIを無効にできます。

CMakeオプション

• FMT_OS：OFFに設定すると、OS固有のAPI（fmt/os.h）を無効にします。
• FMT_UNICODE：OFFに設定すると、Windows/MSVCでUnicodeサポートを無効にします。他のプラットフォームでは、Unicodeサポートは常に有効です。

マクロ

• FMT_HEADER_ONLY：定義すると、ヘッダーのみのモードを有効にします。CMakeターゲットfmt::fmt-header-onlyを使う代わりの方法です。既定：未定義。

• FMT_USE_EXCEPTIONS：0に設定すると、例外の使用を無効にします。既定：1（-fno-exceptionsでコンパイルした場合は0）。

• FMT_USE_LOCALE：0に設定すると、ロケールサポートを無効にします。既定：1（FMT_OPTIMIZE_SIZE > 1の場合は0）。

• FMT_CUSTOM_ASSERT_FAIL：1に設定すると、利用者が独自のfmt::assert_fail関数を提供できるようになります。この関数はアサーションの失敗時に呼ばれ、例外が無効の場合は実行時エラーでも呼ばれます。既定：0。

• FMT_BUILTIN_TYPES：0に設定すると、int以外の算術型と文字列型の組み込み処理を無効にします。これにより、呼び出しごとのオーバーヘッドと引き換えにライブラリーのサイズが小さくなります。既定：1。

• FMT_OPTIMIZE_SIZE：バイナリーサイズの最適化を制御します。

  • 0 - 無効（既定）
  • 1 - ロケールサポートを無効にし、いくつかの最適化を適用します
  • 2 - 一部のUnicode機能と名前付き引数を無効にし、より積極的な最適化を適用します

バイナリーサイズの最適化

一部の機能を制限して{fmt}のバイナリーサイズをできる限り小さくするには、次の設定を使えます。

• CMakeオプション：
  • FMT_OS=OFF
• マクロ：
  • FMT_BUILTIN_TYPES=0
  • FMT_OPTIMIZE_SIZE=2