4. format

最終更新日時(UTC):
が更新

履歴 編集

function
<chrono>

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}"のように指定することでデフォルトとは異なる出力をさせることができる。

フォーマットフラグ 説明 例
%a ロケール依存の曜日の略称。
値に有効な曜日が含まれていない場合、std::format_error例外を送出する		 "Fri", "金"
%A ロケール依存の曜日の完全名。
値に有効な曜日が含まれていない場合、std::format_error例外を送出する		 "Friday", "金曜日"
%b ロケール依存の月の略称。
値に有効な月が含まれていない場合、std::format_error例外を送出する		 "Apr", "4月"
%B ロケール依存の月の完全名。
値に有効な月が含まれていない場合、std::format_error例外を送出する		 "April", "4月"
%c ロケール依存の日付・時間の表現。改良コマンド%Ecを指定すると、異なる表現を出力する "Fri Apr 24 17:14:44 2020"
"2020年04月24日 17時14分44秒"
%Ecでは"令和02年04月24日 17時14分44秒"
%C 100で切り下げ除算した年 (世紀)。結果が10進数で1桁の場合、先頭に0がつく。改良コマンド%ECを指定すると、ロケール依存の世紀の異なる表現を出力する "21"
%ECでは"令和" (元号)
%d 10進数での月の日。結果が10進数で1桁の場合、先頭に0がつく。改良コマンド%Odを指定すると、ロケール依存の異なる表現を出力する "24"
%D %m/%d/%yと等価 "04/24/20"
%e 10進数での月の日。結果が10進数で1桁の場合、先頭にスペースがつく。改良コマンド%Oeを指定すると、ロケール依存の異なる表現を出力する " 1"
%F %Y-%m-%dと等価 "2020-04-24"
%g ISOの週ベースのうしろ2桁10進数の年。結果が1桁の場合、先頭に0がつく "20"
%G ISOの週ベースの10進数の年。結果が4桁未満の場合、4桁になるよう左が0で埋められる "2020"
%h %bと等価 "Jan", "4月"
%H 24時間時計での10進数の時。結果が1桁の場合、先頭に0がつく。改良コマンド%OHを指定知ると、ロケール依存の異なる表現を出力する "17"
%I 12時間時計での10進数の時。結果が1桁の場合、先頭に0がつく。改良コマンド%OIを指定知ると、ロケール依存の異なる表現を出力する "05"
%j 10進数での年の日。1月1日は001が出力される。結果が3桁未満の場合、3桁になるよう左が0で埋められる。durationの特殊化が与えられた場合、daysの10進数値として0埋めなしで書式化される "115"
%m 10進数での月。1月は01が出力される。結果が1桁の場合、先頭に0がつく。改良コマンド%Omを指定すると、ロケール依存の異なる表現を出力する "04"
%M 10進数での分。結果が1桁の場合、先頭に0がつく。改良コマンド%OMを指定すると、ロケール依存の異なる表現を出力する "14"
%n 改行文字
%p 12時間時計でのロケール依存の午前・午後の表現 "PM", "午後"
%q duration単位ごとのサフィックス。durationのoperator<<で出力されるサフィックスと等価 "s"
%Q durationの数値。.count()で取得した値 "44"
%r 12時間時計でのロケール依存の時間 "05:14:44 PM"
"午後05時14分44秒"
%R %H:%Mと等価 "17:14"
%S 10進数での秒。10秒未満の場合、先頭に0がつく。入力が秒の精度と正確に一致しない場合、浮動小数点フォーマットで出力される。10進数の浮動小数点数で小数点以下18桁以内で表現できない場合、マイクロ秒で出力される。改良コマンド%OSを指定すると、ロケール依存の異なる表現を出力する "44"
"44.123"
%t 水平タブ文字
%T %H:%M:%Sと等価 "17:14:44.123"
%u 10進数での月曜を1とするISO曜日番号 (1-7)。改良コマンド%Ouを指定すると、ロケール依存の異なる表現を出力する "5"
%U 10進数での年の週番号。年の最初の日曜日が最初の曜日であるとして01、同年のそれより前の日は00となる。結果が1桁の場合、先頭に0がつく。改良コマンド%OUを指定すると、ロケール依存の異なる表現を出力する "16"
%V 10進数でのISO週ベースの週番号。結果が1桁の場合、先頭に0がつく。改良コマンド%OVを指定すると、ロケール依存の異なる表現を出力する "17"
%w 10進数での日曜を0とする曜日番号 (0-6)。改良コマンド%Owを指定すると、ロケール依存の異なる表現を出力する "5"
%W 10進数での年の週番号。年の最初の月曜日が最初の曜日であるとして01、同年のそれより前の日は00となる。結果が1桁の場合、先頭に0がつく。改良コマンド%OWを指定すると、ロケール依存の異なる表現を出力する "16"
%x ロケール依存の日付表現。改良コマンド%Exを指定すると、ロケール依存の異なる表現が出力される "04/24/20"
"2020年04月24日"
%Exでは"令和02年04月24日"
%X ロケール依存の時間表現。改良コマンド%EXを指定すると、ロケール依存の異なる表現が出力される "17:14:44"
"17時14分44秒"
%y 10進数での年のうしろ2桁。結果が1桁の場合、先頭に0がつく。改良コマンド%Oyを指定すると、ロケール依存の異なる表現を出力する。改良コマンド%Eyを指定すると、%ECからのオフセットとしてロケール依存の異なる表現を出力する。 "20"
%Eyでは"02"
%Y 10進数での年。結果が4桁未満の場合、4桁になるよう左が0で埋められる。改良コマンド%EYを指定すると、ロケール依存の異なる表現の完全な年を出力する "2020"
%EYでは"令和02年"
%z ISO 8601フォーマットでのUTCからのオフセット。例として-0430はUTCから4時間30分遅れていることを表す。オフセットがゼロの場合は+0000が使用される。改良コマンド%Ezと%Ozを指定すると、時と分の間にコロン (:) が挿入される。オフセット情報が利用可能でない場合、std::format_error例外を送出する "+0900"
%Ezでは"+09:00"
%Z タイムゾーンの略称。タイムゾーンの略称が利用可能でない場合、std::format_error例外を送出する "JST"
%% 文字% "%"
  • 便宜上のリテラルキャストSTATICALLY-WIDENを導入する。STATICALLY-WIDEN<charT>("...")は、charTがcharである場合は"..."、charTがwchar_tである場合はL"..."を意味する。
  • hh_mm_ssオブジェクトのis_negative()がtrueである場合、出力される文字列の先頭にSTATICALLY-WIDEN<charT>("-")が挿入される

#include <iostream>
#include <format>
#include <chrono>
int main()
{
  const auto now = std::chrono::system_clock::now();
  std::cout << std::format("{:%Y}", now); // => 2021
}

例外

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

バージョン

言語

  • C++20

処理系

  • Clang: (9.0時点で実装なし)
  • GCC: (9.2時点で実装なし)
  • Visual C++: (2019 Update 3時点で実装なし)

参照