書式文字列の構文

このライブラリの書式設定関数、特にfmt::formatとfmt::printは、ここで説明する構文で記述された書式文字列を受け取ります。

書式文字列は、波括弧{と}で囲まれた置換フィールドを埋め込んだ通常のテキストです。置換フィールドの外側にある文字は、そのまま出力にコピーされます。波括弧自体を出力するには二重にします。{{は1つの{を、}}は1つの}を出力します。

置換フィールドは、次の文法で記述されます。

replacement_field ::= "{" [arg_id] [":" (format_spec | chrono_format_spec)] "}"
arg_id            ::= integer | identifier
integer           ::= digit+
digit             ::= "0"..."9"
identifier        ::= id_start id_continue*
id_start          ::= "a"..."z" | "A"..."Z" | "_"
id_continue       ::= id_start | digit

arg_idは、どの引数を書式設定するかを選びます。非負整数による位置参照、またはfmt::argで渡した引数の名前に一致する識別子による名前参照を指定できます。arg_idを省略すると、引数は左から右へ順に使われます。この自動インデックス指定は書式文字列全体で統一する必要があります。自動指定と明示的な数値IDを混在させると、コンパイル時エラーになります（実行時にはformat_errorになります）。

:の後に置くformat_specは、値をどのように表示するかを記述します。その文法は型によって異なります。標準の組み込み型で使われる形式は、次の節で説明します。

例：

fmt::format("hello, {}", "world");
// Result: "hello, world"

fmt::format("{1}, {0}!", "world", "hello");
// Result: "hello, world!"

fmt::format("{greeting}, {name}!",
            fmt::arg("greeting", "hi"), fmt::arg("name", "fmt"));
// Result: "hi, fmt!"

format_specの中のwidthやprecision自体を、{}または{arg_id}という入れ子の置換フィールドとして書くこともできます。この場合、実行時に整数引数から値を取得します。入れ子のフィールドに指定できるのはarg_idだけで、その中にさらにformat_specを含めることはできません。

書式指定

次の文法は、整数、浮動小数点数、文字、文字列、真偽値、ポインターという組み込み型と、formatterがfmtのパーサーを再利用するユーザー定義型に共通するformat_specを記述しています。

format_spec ::= [[fill]align][sign]["#"]["0"][width]["." precision]["L"][type]
fill        ::= <a character other than '{' or '}'>
align       ::= "<" | ">" | "^"
sign        ::= "+" | "-" | " "
width       ::= integer | "{" [arg_id] "}"
precision   ::= integer | "{" [arg_id] "}"
type        ::= "a" | "A" | "b" | "B" | "c" | "d" | "e" | "E" | "f" | "F" |
                "g" | "G" | "o" | "p" | "s" | "x" | "X" | "?"

各オプションが意味を持つかどうかは、書式設定する値によって決まります。値の型に適用できないオプションは、可能であればコンパイル時に診断され、それ以外の場合はformat_errorを送出します。

詰め文字と配置

alignは、widthによってフィールドが値の通常の表示より広くなるときに、どこに詰め文字を入れるかを選びます。

fill文字は、{と}以外の単一のUnicodeコードポイントで、書式文字列と同じ方法でエンコードします。既定の空白の代わりに使う詰め文字を指定します。fill文字として認識されるのは、その直後にalign文字がある場合だけです。そうでなければ、別の位置にあるオプションと区別できません。したがって、独自の詰め文字を使うときは配置方法も指定する必要があります。

値の通常の表示がすでにwidth以上の幅を持つ場合、配置指定による見た目の変化はありません。幅に合わせるために値が切り詰められることはありません。

fmt::format("[{:<10}]", "42");   // Result: "[42        ]"
fmt::format("[{:>10}]", "42");   // Result: "[        42]"
fmt::format("[{:^10}]", "42");   // Result: "[    42    ]"
fmt::format("[{:*^10}]", "42");  // Result: "[****42****]"  - '*' as fill

符号

signは、数値の符号をどのように出力するかを制御します。符号付き整数と浮動小数点型だけに適用されます。

浮動小数点数の出力では、-0.0の符号が保持されます。

fmt::format("{:+d} {:+d}", 7, -7);  // Result: "+7 -7"
fmt::format("{: d} {: d}", 7, -7);  // Result: " 7 -7"

代替形式（#）

#フラグは代替形式を選びます。正確な意味は表示型によって異なります：

• 2進、8進、16進で表示する整数には、適切な基数接頭辞（0b/0B、0、0x/0X）を前に付けます。接頭辞の大文字・小文字は型指定子に従います。xには0x、Xには0Xという対応です。
• 浮動小数点数では、本来なら小数部の数字が出力されない場合にも小数点を表示させ、g/Gの表示型が仮数部の末尾のゼロを取り除くことを防ぎます。

数値以外の型では、#フラグは使えません。

ゼロ埋め（0）

widthの直前に0を置くと、数値型に対して符号を考慮したゼロ埋めが有効になります。ゼロは、符号（または基数接頭辞がある場合はその接頭辞）と最上位桁の間に挿入されます。そのため、符号や0x接頭辞は空白で数字から離されず、数字に隣接したままになります。たとえば、120に{:+08d}を適用すると、+0000120になります。

ゼロ埋めの性質：

• 数値型だけに適用されます。
• infやnanには影響しません。
• 明示的なalignも指定されている場合は無視されます。

幅

widthは、フィールドが占める文字数の最小値を表す非負の10進整数です。書式設定した値がwidthより短ければ、alignとfillに従って埋めます。長ければ、値全体を出力します。widthが原因で値が切り詰められることはありません。

実行時にwidthを指定するには、次の引数を使う{}、または位置や名前で整数引数を参照する{arg_id}をフィールドに記述します。

文字列の書式設定では、Unicodeを考慮した推定で「幅」を表示列数として測ります。東アジアの幅広文字・全角文字と一般的な絵文字の範囲は2列、それ以外は1列と数えます。これにより、ラテン文字とCJK文字を組み合わせた等幅表示でも、固定のwidth値が見た目に一貫した幅になります。

fmt::format("[{:6}]", 42);
// Result: "[    42]"  - right-aligned by default
fmt::format("[{:6}]", "hi");
// Result: "[hi    ]"  - left-aligned by default
fmt::format("[{:{}}]", 42, 6);
// Result: "[    42]"  - width from an argument

精度

precisionは、.の後に置く非負の10進整数で、その意味は書式設定する値によって異なります。widthと同じく、入れ子の置換フィールドで指定して実行時に評価することもできます。

整数、文字、真偽値、ポインター型ではprecisionを指定できません。precisionでC文字列から取り出す文字数を制限する場合でも、その文字列はヌル終端されている必要があります。

fmt::format("{:.2f}", 3.14159);        // Result: "3.14"
fmt::format("{:.3g}", 3.14159);        // Result: "3.14"
fmt::format("{:.4}", "hello, world");  // Result: "hell"
fmt::format("{:.{}f}", 3.14159, 4);
// Result: "3.1416"  - precision from an argument

ロケール（L）

Lフラグは、数値型に対してロケールに応じた書式設定を選びます。フォーマッターは書式設定関数に渡されたC++ロケールを調べ、渡されていなければグローバルロケールを使います。そのロケールの桁区切り文字と、浮動小数点数では小数点を挿入します。このフラグは数値以外の型には影響しません。

auto loc = std::locale("en_US.UTF-8");
fmt::format(loc, "{:L}", 1234567890);     // Result: "1,234,567,890"
fmt::format(loc, "{:.2Lf}", 1234567.89);  // Result: "1,234,567.89"

表示型

値の表現はtypeで選びます。以下では、適用される値の種類ごとに指定子をまとめています。

整数、真偽値、文字：

fmt::format("{:d} {:#x} {:#o} {:#b}", 42, 42, 42, 42);
// Result: "42 0x2a 052 0b101010"

fmt::format("{:#06x}", 0xfe);  // # adds the prefix, 06 zero-pads to width 6
// Result: "0x00fe"

浮動小数点数：

文字列と文字：

fmt::format("{}",   "tab\there");  // Result contains a literal tab character.
fmt::format("{:?}", "tab\there");  // Result: "\"tab\\there\""

ポインター：

C文字列（char*またはconst char*）では、文字列の表示型とpの両方を使えます。そのため、同じ値をテキストとしてもアドレスとしても書式設定できます。

chronoの書式指定

chronoの期間型・時点型とstd::tmの書式指定は、次の構文を使います：

chrono_format_spec ::= [[fill]align][width]["." precision][chrono_specs]
chrono_specs       ::= conversion_spec |
                       chrono_specs (conversion_spec | literal_char)
conversion_spec    ::= "%" [padding_modifier] [locale_modifier] chrono_type
literal_char       ::= <a character other than '{', '}' or '%'>
padding_modifier   ::= "-" | "_"  | "0"
locale_modifier    ::= "E" | "O"
chrono_type        ::= "a" | "A" | "b" | "B" | "c" | "C" | "d" | "D" | "e" |
                       "F" | "g" | "G" | "h" | "H" | "I" | "j" | "m" | "M" |
                       "n" | "p" | "q" | "Q" | "r" | "R" | "S" | "t" | "T" |
                       "u" | "U" | "V" | "w" | "W" | "x" | "X" | "y" | "Y" |
                       "z" | "Z" | "%"

リテラル文字は、そのまま出力にコピーされます。精度を指定できるのは、表現型が浮動小数点型であるstd::chrono::durationだけです。

利用できる表示型（chrono_type）は次のとおりです：

日付の要素を持つ指定子、たとえば月内の日を表す'd'は、std::tmと時点に対してだけ有効で、期間には使えません。

利用できる桁埋め修飾子（padding_modifier）は次のとおりです：

これらの修飾子を使える表示型は、'H'、'I'、'M'、'S'、'U'、'V'、'W'、'Y'、'd'、'j'、'm'だけです。

例：

#include <fmt/chrono.h>

auto t = std::tm();
t.tm_year = 2010 - 1900;
t.tm_mon = 7;
t.tm_mday = 4;
t.tm_hour = 12;
t.tm_min = 15;
t.tm_sec = 58;
fmt::print("{:%Y-%m-%d %H:%M:%S}", t);
// Prints: 2010-08-04 12:15:58

範囲の書式指定

範囲型の書式指定は、次の構文を使います：

range_format_spec ::= ["n"][range_type][":" range_underlying_spec]

'n'オプションは、範囲の前後の括弧を付けずに書式設定します。

range_typeで利用できる表示型は次のとおりです：

range_typeが's'または'?s'の場合、範囲の要素型は文字型でなければなりません。'n'オプションとrange_underlying_specは、's'および'?s'と併用できません。

range_underlying_specは、範囲の要素型のフォーマッターに基づいて解析されます。

既定では、文字や文字列の範囲はエスケープされ、引用符で囲んで出力されます。ただし、range_underlying_specを指定した場合は、空であっても、その指定に従って文字や文字列が出力されます。

例：

fmt::print("{}", std::vector{10, 20, 30});
// Output: [10, 20, 30]
fmt::print("{::#x}", std::vector{10, 20, 30});
// Output: [0xa, 0x14, 0x1e]
fmt::print("{}", std::vector{'h', 'e', 'l', 'l', 'o'});
// Output: ['h', 'e', 'l', 'l', 'o']
fmt::print("{:n}", std::vector{'h', 'e', 'l', 'l', 'o'});
// Output: 'h', 'e', 'l', 'l', 'o'
fmt::print("{:s}", std::vector{'h', 'e', 'l', 'l', 'o'});
// Output: "hello"
fmt::print("{:?s}", std::vector{'h', 'e', 'l', 'l', 'o', '\n'});
// Output: "hello\n"
fmt::print("{::}", std::vector{'h', 'e', 'l', 'l', 'o'});
// Output: [h, e, l, l, o]
fmt::print("{::d}", std::vector{'h', 'e', 'l', 'l', 'o'});
// Output: [104, 101, 108, 108, 111]
fmt::print("{:n:f}", std::array{std::numbers::pi, std::numbers::e});
// Output: 3.141593, 2.718282

組み合わせた例

次の例は、ここまでに説明した入れ子の置換フィールド、詰め文字、中央配置を組み合わせ、メッセージの周囲に固定幅の枠を描きます：

fmt::print(
    "┌{0:─^{2}}┐\n"
    "│{1: ^{2}}│\n"
    "└{0:─^{2}}┘\n", "", "Hello, world!", 20);

出力：

┌────────────────────┐
│   Hello, world!    │
└────────────────────┘