std::formatter<std::chrono::zoned_time>, std::chrono::local_time_format

 

C++

編譯器支援

自由（freestanding）與宿主（hosted）

語言

標準庫

標準庫標頭檔案

具名要求

特性測試宏 (C++20)

語言支援庫

概念庫 (C++20)

診斷庫

記憶體管理庫

超程式設計庫 (C++11)

通用工具庫

容器庫

迭代器庫

範圍庫 (C++20)

演算法庫

字串庫

文字處理庫

數值庫

日期和時間庫

輸入/輸出庫

檔案系統庫 (C++17)

併發支援庫 (C++11)

執行控制庫 (C++26)

技術規範

符號索引

外部庫

 

日期和時間庫

時間點 time_point (C++11) clock_time_conversion (C++20)   clock_cast (C++20) 時長 duration (C++11) 時鐘 system_clock (C++11) steady_clock (C++11) is_clock (C++20) utc_clock (C++20) tai_clock (C++20) high_resolution_clock (C++11) gps_clock (C++20) file_clock (C++20) local_t (C++20) 日間時間 is_amis_pm (C++20)(C++20) make12make24 (C++20)(C++20) hh_mm_ss (C++20)

日曆 day (C++20) month (C++20) year (C++20) weekday (C++20) operator/ (C++20) year_month_day (C++20) year_month_day_last (C++20) year_month_weekday (C++20) year_month_weekday_last (C++20)   weekday_indexed (C++20) weekday_last (C++20) month_day (C++20) month_day_last (C++20) month_weekday (C++20) month_weekday_last (C++20) year_month (C++20) last_speclast (C++20)(C++20) chrono I/O parse (C++20)

時區 tzdb (C++20) tzdb_list (C++20) get_tzdbget_tzdb_listreload_tzdbremote_version (C++20)(C++20)(C++20)(C++20) sys_info (C++20) local_info (C++20) nonexistent_local_time (C++20) ambiguous_local_time (C++20) locate_zone (C++20) current_zone (C++20) time_zone (C++20) choose (C++20) zoned_traits (C++20) zoned_time (C++20) time_zone_link (C++20) leap_second (C++20) leap_second_info (C++20) get_leap_second_info (C++20) C風格日期和時間

 

std::chrono::zoned_time

成員函式

zoned_time::zoned_time

zoned_time::operator=

zoned_time::get_time_zone

zoned_time::get_sys_timezoned_time::operator sys_time

zoned_time::get_local_timezoned_time::operator local_time

zoned_time::get_info

非成員函式

operator==

operator<<

輔助類

formatter<std::chrono::zoned_time>

hash<std::chrono::zoned_time> (C++26)

推導指引

 

定義於標頭檔案 <chrono>
template< class Duration, class TimeZonePtr, class CharT > struct formatter<std::chrono::zoned_time<Duration, TimeZonePtr>, CharT>     : std::formatter</*local-time-format-t*/                          <std::common_type_t<Duration,                                              std::chrono::seconds>>, CharT>	(1)	(C++20 起)
template< class Duration > /*local-time-format-t*/<Duration>     local_time_format( const std::chrono::local_time<Duration>& tp,                        const std::string* abbrev = nullptr,                        const std::chrono::seconds* offset_sec = nullptr );	(2)	(C++20 起)
幫助模板
template< class Duration > struct /*local-time-format-t*/ {     std::chrono::local_time<Duration> /*time*/;     const std::string* /*abbrev*/;     const std::chrono::seconds* /*offset_sec*/; };	(3)	(C++20 起) (僅作說明*)
template< class Duration, class CharT > struct formatter</*local-time-format-t*/<Duration>, CharT>;	(4)	(C++20 起)

1) std::formatter 的特化，它定義了 std::chrono::zoned_time 的格式化規則。

• parse 成員繼承自基類。
• 設 tp 為格式化引數，ctx 為格式化上下文，format 成員的行為等同於

using common_duration_type = std::common_type_t<Duration, std::chrono::seconds>;
using formatter_type = std::formatter<local-time-format-t <common_duration_type>;

std::chrono::sys_info info = tp.get_info();
return formatter_type::format({tp.get_local_time(), &info.abbrev, &info.offset_sec}), ctx);

2) 建立一個可以格式化為 std::chrono::zoned_time 的物件。

返回 {time, abbrev, offset_sec}。

3) 一個僅用於說明的型別，包含格式化 std::chrono::zoned_time 所需的所有資訊。

• abbrev 包含時區縮寫。
• offset_sec 包含與 UTC 的偏移量。
• time 包含所有其他所需資訊。

4) std::formatter 的特化，它定義了 std::chrono::zoned_time 的底層格式化規則。

設 f 為格式化引數，該特化具有以下額外的格式化規則：

• 如果省略 chrono-spec，結果等同於使用 %F %T %Z 作為 chrono-spec。
• 如果使用 %Z，當 f.abbrev 不是空指標值時，它會被替換為 *f.abbrev；否則丟擲 std::format_error 型別的異常。
• 如果使用 %z 或 %z 的修改變體，當 f.offset_sec 不是空指標值時，它會被替換為 *f.offset_sec；否則丟擲 std::format_error 型別的異常。

std::formatter 特化通常不直接訪問，而是透過格式化函式使用。

格式說明

格式規範的形式為

fill-and-align (可選) width (可選) precision (可選) L(可選) chrono-spec (可選)

fill-and-align、width 和 precision 的含義與標準格式說明中相同。precision 僅對錶示型別 Rep 為浮點型別的 std::chrono::duration 型別有效，否則丟擲 std::format_error。

用於格式化的區域設定確定如下：

• 如果格式規範中不存在 L，則使用預設的 "C" 區域設定，
• 否則，如果傳遞給格式化函式，則使用 std::locale 所表示的區域設定，
• 否則（存在 L 但沒有將 std::locale 傳遞給格式化函式），則使用全域性區域設定。

如果（普通或寬）字串字面量編碼是 Unicode 編碼形式且區域設定在實現定義的區域設定集合中，則每個依賴於區域設定的替換都將執行，如同替換字元序列被轉換為字面量編碼。

chrono-spec 由一個或多個轉換說明符和普通字元（除了 {、} 和 %）組成。chrono-spec 必須以轉換說明符開頭。所有普通字元都會不經修改地寫入輸出。每個未經修改的轉換說明符以 % 字元開頭，後跟一個決定說明符行為的字元。一些轉換說明符具有修改形式，其中在 % 字元後插入 E 或 O 修飾符字元。每個轉換說明符都會被輸出中的適當字元替換，如下所述。

除非另有說明，如果 chrono-spec 為空，則 chrono 物件將按照將其流式傳輸到型別為 std::basic_ostringstream<CharT> 的物件 os 的方式進行格式化，並使用格式化區域設定（std::locale::classic()、傳入的 std::locale 物件和 std::locale::global() 之一）填充，並將 os.str() 複製到輸出緩衝區，並根據格式說明符進行額外的填充和調整。

以下格式說明符可用：

轉換 說明符	解釋
%%	寫入字面量 % 字元。
%n	寫入換行符。
%t	寫入水平製表符。
年
%C %EC	使用向下取整除法寫入年份除以 100 的結果。如果結果是一個十進位制數字，則在其前面加上 0。 修改後的命令 %EC 寫入區域設定的世紀的替代表示。
%y %Oy %Ey	寫入年份的最後兩位十進位制數字。如果結果是一位數字，則在其前面加上 0。 修改後的命令 %Oy 寫入區域設定的替代表示。 修改後的命令 %Ey 寫入區域設定的從 %EC 偏移量（僅年份）的替代表示。
%Y %EY	將年份作為十進位制數字寫入。如果結果小於四位數字，則在其前面用 0 填充到四位數字。 修改後的命令 %EY 寫入區域設定的替代完整年份表示。
月
%b %h	寫入區域設定的縮寫月份名稱。
%B	寫入區域設定的完整月份名稱。
%m %Om	將月份作為十進位制數字寫入（一月為 01）。如果結果是一個數字，則在其前面加上 0。 修改後的命令 %Om 寫入區域設定的替代表示。
日
%d %Od	將月份中的日期作為十進位制數字寫入。如果結果是一個十進位制數字，則在其前面加上 0。 修改後的命令 %Od 寫入區域設定的替代表示。
%e %Oe	將月份中的日期作為十進位制數字寫入。如果結果是一個十進位制數字，則在其前面加上一個空格。 修改後的命令 %Oe 寫入區域設定的替代表示。
星期幾
%a	寫入區域設定的縮寫工作日名稱。
%A	寫入區域設定的完整工作日名稱。
%u %Ou	將 ISO 工作日作為十進位制數字寫入 (1-7)，其中星期一為 1。 修改後的命令 %Ou 寫入區域設定的替代表示。
%w %Ow	將工作日作為十進位制數字寫入 (0-6)，其中星期日為 0。 修改後的命令 %Ow 寫入區域設定的替代表示。
ISO 8601 基於周的年份
在ISO 8601中，周以星期一開始，一年的第一週必須滿足以下要求 包含1月4日 包含一年中的第一個星期四
%g	寫入 ISO 8601 基於周的年份的最後兩位十進位制數字。如果結果是一位數字，則在其前面加上 0。
%G	將 ISO 8601 基於周的年份作為十進位制數字寫入。如果結果小於四位數字，則在其前面用 0 填充到四位數字。
%V %OV	將 ISO 8601 年份的週數作為十進位制數字寫入。如果結果是一個數字，則在其前面加上 0。 修改後的命令 %OV 寫入區域設定的替代表示。
年份中的周/天
%j	將年份中的日期作為十進位制數字寫入（1 月 1 日為 001）。如果結果小於三位數字，則在其前面用 0 填充到三位數字。
%U %OU	將年份的週數作為十進位制數字寫入。年份的第一個星期日是第 01 周的第一天。在此之前的同年日期屬於第 00 周。如果結果是一個數字，則在其前面加上 0。 修改後的命令 %OU 寫入區域設定的替代表示。
%W %OW	將年份的週數作為十進位制數字寫入。年份的第一個星期一是第 01 周的第一天。在此之前的同年日期屬於第 00 周。如果結果是一個數字，則在其前面加上 0。 修改後的命令 %OW 寫入區域設定的替代表示。
日期
%D	等效於"%m/%d/%y"。
%F	等同於 "%Y-%m-%d"。
%x %Ex	寫入區域設定的日期表示。 修改後的命令 %Ex 生成區域設定的替代日期表示。
日間時間
%H %OH	將小時（24 小時制）作為十進位制數字寫入。如果結果是一個數字，則在其前面加上 0。 修改後的命令 %OH 寫入區域設定的替代表示。
%I %OI	將小時（12 小時制）作為十進位制數字寫入。如果結果是一個數字，則在其前面加上 0。 修改後的命令 %OI 寫入區域設定的替代表示。
%M %OM	將分鐘作為十進位制數字寫入。如果結果是一個數字，則在其前面加上 0。 修改後的命令 %OM 寫入區域設定的替代表示。
%S %OS	將秒作為十進位制數字寫入。如果秒數小於 10，則結果前面加上 0。 如果輸入的精度不能用秒精確表示，則格式為固定格式的十進位制浮點數，其精度與輸入精度匹配（如果轉換為浮點十進位制秒不能在 18 位小數內完成，則為微秒精度）。小數點字元根據區域設定進行本地化。 修改後的命令 %OS 寫入區域設定的替代表示。
%p	寫入區域設定中與 12 小時制相關聯的 AM/PM 表示。
%R	等效於"%H:%M"。
%T	等效於"%H:%M:%S"。
%r	寫入區域設定的 12 小時制時間。
%X %EX	寫入區域設定的時間表示。 修改後的命令 %EX 寫入區域設定的替代時間表示。
時區
%z %Ez %Oz	以 ISO 8601 格式寫入與 UTC 的偏移量。例如 -0430 表示比 UTC 晚 4 小時 30 分鐘。如果偏移量為零，則使用 +0000。 修改後的命令 %Ez 和 %Oz 在小時和分鐘之間插入 :（例如，-04:30）。
%Z	寫入時區縮寫。
雜項
%c %Ec	寫入區域設定的日期和時間表示。 修改後的命令 %Ec 寫入區域設定的替代日期和時間表示。

以下說明符可識別，但會丟擲 std::format_error

轉換 說明符	解釋
持續時間計數
%Q	寫入持續時間的滴答計數，即透過 count() 獲得的值。
%q	寫入持續時間的單位字尾，如 operator<<() 中指定。

缺陷報告

下列更改行為的缺陷報告追溯地應用於以前出版的 C++ 標準。

缺陷報告	應用於	釋出時的行為	正確的行為
LWG 4124	C++20	1. chrono-spec 無法省略 2. zoned_time 無法格式化     精度低於秒	1. 可以省略 2. 可以格式化為     這些精度
P2372R3	C++20	formatter 使用全域性區域設定或傳入的區域設定	當 L 不存在時，使用預設的 "C" 區域設定

參見

format (C++20)

將引數的格式化表示儲存在新字串中 (函式模板)