std::format(C++20)

namespace std {
  // 追加宣言なし
}

概要

chronoライブラリのクラスオブジェクトに対する文字列フォーマット。

ここでは宣言はとくにないが、std::format()に対してchronoライブラリの各クラスオブジェクトを出力できるようstd::formatterクラスが各クラスで特殊化されている。

フォーマット構文

chrono-format-spec:
  fill-and-align(opt) width(opt) precision(opt) L(opt) chrono-specs(opt)

• fill (省略可) : アライメントに使う文字 (デフォルト：スペース)
• align (省略可) : アライメント
  • > : 右寄せ
  • < : 左寄せ
  • ^ : 中央寄せ
• width (省略可) : 幅 (省略時は値に応じて幅が決まり、アライメントは機能しない)
• precision (省略可) : 精度(浮動小数点数の場合)、使う文字数(文字列の場合)
• L (省略可) : この関数に指定されたロケールを使用し、指定されなければグローバルロケールを使用する。省略された場合はCロケールを使用する

chronoライブラリでのフォーマットフラグ

std::format()関数の通常の指定では、置換フィールド{}内に基数、精度、0埋め指定、アライメントなどを指定する。

chronoライブラリではこれに加え、たとえばデフォルトでは年・月・日を出力するyear_month_dayクラスに対して「"年/月"」というフォーマットで出力するよう"{%Y/%m}"のように指定することでデフォルトとは異なる出力をさせることができる。

• 便宜上のリテラルキャストSTATICALLY-WIDENを導入する。STATICALLY-WIDEN<charT>("...")は、charTがcharである場合は"..."、charTがwchar_tである場合はL"..."を意味する。
• hh_mm_ssオブジェクトのis_negative()がtrueである場合、出力される文字列の先頭にSTATICALLY-WIDEN<charT>("-")が挿入される

例外

• 指定されたフォーマットフラグに必要な情報が含まれていない場合、format_error例外が送出される (例として、durationには曜日をフォーマットするために必要な情報が含まれていない)
  • ただし、フラグが時刻に関するもの (%H, %I, %pなど) である場合、durationの特殊化は深夜0時からの経過した時刻として解釈する

例

#include <iostream>
#include <format>
#include <chrono>

int main()
{
  auto now = std::chrono::system_clock::now(); // UTC時間の現在日時

  // 日付を出力
  std::cout << std::format("1. {:%Y年%m月%d日}", now) << std::endl;

  // 時間を出力。
  // 秒単位のtime_pointに変換しないと、小数点以下の秒も出力される
  auto now_sec = std::chrono::time_point_cast<std::chrono::seconds>(now);
  std::cout << std::format("2. {:%H時%M分%S秒}", now) << std::endl;
  std::cout << std::format("3. {:%H時%M分%S秒}", now_sec) << std::endl;
  std::cout << std::format("4. {:%p %I時%M分%S秒}", now_sec) << std::endl;

  // その他要素
  std::cout << std::format("5. {:%C}", now) << std::endl; // 世紀 (100で割って切り下げた値)
  std::cout << std::format("6. {:%a}", now) << std::endl; // 曜日の略称
  std::cout << std::format("7. {:%A}", now) << std::endl; // 曜日の完全名
}

出力例

1. 2024年09月24日
2. 08時27分28.1822610秒
3. 08時27分28秒
4. AM 08時27分28秒
5. 20
6. Tue
7. Tuesday

バージョン

言語

• C++20

処理系

• Clang: 17 ✅
• GCC: 13 ✅
• Visual C++: 2019 Update 10 ✅

参照

• P1361R2 Integration of chrono with text formatting
• LWG Issue 3262. Formatting of negative durations is not specified
• LWG Issue 3230. Format specifier %y/%Y is missing locale alternative versions
• LWG Issue 3262. Formatting of negative durations is not specified
• LWG Issue 3270. Parsing and formatting %j with durations
• LWG Issue 3272. %I%p should parse/format duration since midnight
• P2372R1 Fixing locale handling in chrono formatters
  • この提案文書はC++20の策定後に採択されたが、実装が追いついていない時期の採択だったために、C++20の仕様として扱われる