本エントリは, 元々 P0355R5 を参考にまとめを行った記事であるが, その後 P0355R7 で

• sunといった曜日を表すリテラルが全てSunday, mayといった月を表すリテラルが全てMayといった形式に変更され, またこれらとstd::chrono::last_spec型のlast¹がstd::literals::chrono_literals名前空間下からstd::chrono名前空間下に移動された.
• system_clock::to_time_tとsystem_clock::from_time_tを Deprecated としていたが, Deprecated でなくなった.

といった他に, 細かい文面の改修や, constexprがつけられるなどの変更が加えられたため, 本エントリにおいても, それに従い該当箇所を改変している (差分を示すことも考えたが, ただ見難くなるように感じたため, そのようなことはしなかった). これらの変更には対応したつもりだが, 細かい厳密な記述に関しては, やはり P0355 の最新リビジョンを追って確かめてほしい(そして, 間違った箇所があれば指摘くださると嬉しい).

要旨

先週, 米国フロリダ州ジャクソンビルで ISO C++ 委員会によって, C++技術仕様(TS, 実験的機能ブランチ) と次の国際標準(IS) C++20 に関する作業が行われた. 同会議で Reddit で紹介されているように, C++20 にいくつかの機能が追加された. そのうちの 1 つである, Calender and timezone library に関する新機能, 概要のメモ.

• 全機能の網羅性を主軸としたエントリではない(が, 独断と偏見により重要に感じた内容は結果的に網羅してしまっている部分もある)ため注意
• 以下, 特に断らない限り, 全てのコード片においてusing namespace std::chrono;, using namespace std::chrono_literals;がされているとする.
• 以下, 特に断らない限り, 各コードブロック以外で言及される内容といった記述については, 名前空間 std::chronoを省略する.

設計

以下の内容が追加される.

• <chrono>に対するカレンダーおよびタイムゾーンライブラリをサポートするための最小限の拡張
• Proleptic Gregorian calendar(civil calendar)
• IANA Time Zone Database を基にしたタイムゾーンライブラリ
• 分数秒, タイムゾーンの略語, UTC オフセットの完全サポートおよびstrftimeのようなフォーマッティング機能
• IANA Time Zone Database でサポートされている, 閏秒を計算するための複数のクロック

カレンダー

本ライブラリ機能によって, 例えば 2016 年を次のように表現することができる.

auto y = std::chrono::year{2016};
auto y = 2016y;

このとき, yearは partial-calendar-type (部分カレンダー型) である. 他の部分カレンダー型と組み合わせることで, year_month_dayなどの full-calendar-type (フルカレンダー型) を生成することができる. フルカレンダー型は, 1 日の制度を持つタイムポイントであり, 部分カレンダー型であるyear, month, day で構成される. これらからyear_month_dayが構築されると, 内部で計算は一切起きず, 唯一起きることは, year_month_day が内部でそれらを格納するということだけである.

std::chrono::year_month_day ymd1{2016y, month{5}, day{29}};

この場合, すべての入力がコンパイル時定数であるので, constexpr にすることができる. さらに, operator/がオーバーロードされているため, 従来の日付の構文が利用できる.

constexpr std::chrono::year_month_day ymd1{2016y, month{5}, day{29}};
constexpr auto ymd2 = 2016y/May/29d;
constexpr auto ymd3 = May/29d/2016y;
constexpr auto ymd4 = 29d/May/2016y;
static_assert(ymd1 == ymd2);
static_assert(ymd2 == ymd3);
static_assert(ymd3 == ymd4);
static_assert(ymd1.year() == 2016y);
static_assert(ymd1.month() == May);
static_assert(ymd1.day() == 29d);

namespace std::chrono {

inline constexpr chrono::month January{1};
inline constexpr chrono::month February{2};
inline constexpr chrono::month March{3};
inline constexpr chrono::month April{4};
inline constexpr chrono::month May{5};
inline constexpr chrono::month June{6};
inline constexpr chrono::month July{7};
inline constexpr chrono::month August{8};
inline constexpr chrono::month September{9};
inline constexpr chrono::month October{10};
inline constexpr chrono::month November{11};
inline constexpr chrono::month December{12};

}

カレンダーライブラリは, 例えばスカラ型で直接日付を指定するといったことはなく, 明示的な型指定による表現によって実現する. なお, 部分カレンダー型(year, month に加えてday型)は, すべて Strong ordering² を満たし, 加えて以下のメンバ関数をもつ.

• デフォルトコンストラクタ, unsigned型(year型のみint型)の値を受け付けるコンストラクタ
• 各型の単位においてそれを前後に進める, {前|後}置{イン|デ}クリメント演算子
• 各型の単位で計算を行う+, -の二項演算子
• 二項演算子と同様の計算を行い自身に代入する+=, -= の複合代入演算子
• unsigned型(year型のみint型)の値への明示的な変換(constexpr explicit operator unsigned() const noexcept;)
• 指定された日付が各単位で適切であるかどうかをチェックするok

year型は, これに加えて, is_leap, min, max メンバ関数をもつ. is_leapは, 指定された年が閏年であるか判定できる. min, maxは内部型の最小値と最大値を返す. また, 上記の通りyといったリテラル接尾語が定義される.
またday型は, dといったリテラル接尾語が定義される.

フルカレンダー型は, sys_daysという型へ変換できる. これは, 次のように定義されている.

constexpr year_month_day::operator sys_days() const noexcept;

using days = duration<int32_t, ratio_multiply<ratio<24>, hours::period>>;
template <class Duration>
using sys_time = time_point<system_clock, Duration>;
using sys_days = sys_time<days>;

加えて, sys_daysには次の特性がある.

• sys_daysは, system_clock::time_pointがマイクロ秒, またはナノ秒のカウントだけであるのと同様に, system_clockの基点(エポック)からの日数を示す.
• sys_daysは, 切り捨てエラーなしで暗黙的にsystem_clock::time_pointに変換される.
• system_clock::time_pointは, 切り捨てエラーが含まれるため, 暗黙的にsys_daysに変換されない.
• system_clock::time_point_cast またはfloorを使用した明示的な変換によってsystem_clock::time_pointからsys_daysへ変換することができる.

内部で保持する部分カレンダー型year, month, day をそれぞれy_, m_, d_ としたとき, year_month_dayからsys_daysへの変換時には(すなわち上記のoperator sys_days()の呼び出し),

• year_month_day::ok()がtrueの場合, sys_daysの基点から*thisまでの日数を保持するsys_daysを返す
• そうでない場合, y_.ok() && m_.ok() == true ならば sys_days{y_/m_/last} から days(duration<int32_t, ratio_multiply<ratio<24>, hours::period>>) の数だけsys_days{y_,m_,last}.day()からオフセットされたsys_daysを返す
• そうでない場合, 未規定である

ここでyear_month_day::okは, y_.ok() && m_.ok() == true $\land$ 1d $\leq$ d_ $\leq$ (y_/m_/last).day() であるとき true を, そうでない場合, false を返すメンバ関数である.

constexpr std::chrono::system_clock::time_point tp = std::chrono::sys_days{2016y/May/29d}; // Convert date to time_point
static_assert(tp.time_since_epoch() == 1'464'480'000'000'000us);
constexpr auto ymd = std::chrono::year_month_day{std::chrono::floor<days>(tp)}; // Convert time_point to date
static_assert(ymd == 2016y/May/29d);
constexpr auto tp = std::chrono::sys_days{2016y/May/29d} + 7h + 30min; // 2016-05-29 07:30 UTC
static_assert(year_month_day{sys_days{2017y/January/0}}  == 2016y/December/31);
static_assert(year_month_day{sys_days{2017y/January/31}} == 2017y/January/31);
static_assert(year_month_day{sys_days{2017y/January/32}} == 2017y/February/1);

using weeks  = duration</* signed integer type of at least 22 bits */, ratio_multiply<ratio<7>, days::period>>;
using years  = duration</* signed integer type of at least 17 bits */, ratio_multiply<ratio<146097, 400>, days::period>>;
using months = duration</* signed integer type of at least 20 bits */, ratio_divide<years::period, ratio<12>>>;

• days, weeks, months, years型は, それぞれ少なくとも $$40000 年の範囲をカバーする.
• hoursのリテラル接尾語がh, minutesのリテラル接尾語がmin, というように, 今までのリテラル接尾語はduration型へ対応していたが, 新規に追加される y, dといったリテラル接尾語は, years, daysに対応するリテラル接尾語ではなく, 上述したように, year, dayの部分カレンダー型に対応するリテラル接尾語である.
• 1 年を, 365.2425 日(グレゴリオ暦の平均長)と定義し, 1 月を, 30.436875 日$(\dfrac{1}{12})$ と定義するため, システム時刻(time_point)を利用した算出結果と, year_month_day を利用した算出結果は異なる.

constexpr auto date1 = sys_days{1997y/May/30d} - months{5}; // 1996-12-28 19:34:30
constexpr auto date2 = sys_days{1997y/December/29d} - years{1}; // 1996-12-28 18:10:48

現実のカレンダーの利用方法として, たとえば「2016 年の 5 月 29 日」を, 「2016 年の 5 月第 5 日曜日」ということもよくあり, これを表現することもできる.

constexpr std::chrono::system_clock::time_point tp = std::chrono::sys_days{Sunday[5]/May/2016}; // Convert date to time_point
static_assert(tp.time_since_epoch() == 1'464'480'000'000'000us);
constexpr auto ymd = std::chrono::year_month_weekday{std::chrono::floor<days>(tp)}; // Convert time_point to date
static_assert(ymd == Sunday[5]/std::chrono::May/2016);
static_assert(2016y/May/29d == std::chrono::year_month_day{Sunday[5]/May/2016});

constexpr auto wdi = Sunday[5]; // wdi is the 5th Sunday of an as yet unspecified month
static_assert(wdi.weekday() == Sunday);
static_assert(wdi.index() == 5);
static_assert(std::is_same<decltype(Sunday), std::chrono::weekday>::value);
static_assert(std::is_same<decltype(wdi.index()), std::chrono::weekday_indexed>::value);

namespace std::chrono {

inline constexpr chrono::weekday Sunday{0};
inline constexpr chrono::weekday Monday{1};
inline constexpr chrono::weekday Tuesday{2};
inline constexpr chrono::weekday Wednesday{3};
inline constexpr chrono::weekday Thursday{4};
inline constexpr chrono::weekday Friday{5};
inline constexpr chrono::weekday Saturday{6};

}

weekday型は, Strong equality³ を満たし, 加えて, 次のメンバ関数を持つ.

• デフォルトコンストラクタ, unsigned, sys_days, 後に取り上げているlocal_days型のオブジェクトを受け付けるコンストラクタ
• 曜日を前後に進める{前|後}置{イン|デ}クリメント演算子
• weekday, days型のオブジェクトを受け付けて曜日の計算を行う+, -の二項演算子
• 二項演算子と同様の計算を行い自身に代入する+=, -= の複合代入演算子
• 指定された曜日が適切であるかどうかをチェックするok
• operator []

operator []は, unsigned型を引数として呼び出すと, weekday_indexed型のオブジェクトが返され, last_spec型のオブジェクトを引数として呼び出すと, weekday_last型のオブジェクトが返される.

• weekday_indexed型は, 月の第 1, 第 2, 第 3, 第 4 または第 5 曜日を表すために使用され, 上記の通り, weekdayメンバ関数, indexメンバ関数を持つ他, okメンバ関数を持つ.
• weekday_last型は, 月の最後のweekdayを表すために使用され, weekdayメンバ関数, okメンバ関数を持つ,
• last_spec型は, 最終日を表すために使用され, 同型のオブジェクトlastがchrono名前空間下に定義される.

例えば次のようにして, ある月の最終日, 最終 $X$ 曜日などを表現することができる.

auto today = std::chrono::year_month_day{std::chrono::floor<std::chrono::days>(std::chrono::system_clock::now())};
auto last_day = today.year()/today.month()/last; // last day of this month
auto last_Sunday = today.year()/today.month()/Sunday[last]; // last Sundayday of this month

static_assert(std::is_same<decltype(Sunday[5]), std::chrono::weekday_indexed>::value);
static_assert(std::is_same<decltype(Sunday[last]), std::chrono::weekday_last>::value);

他に, 年を未指定とし, 特定の月日を表す, month_day, 月の最終日を表すmonth_day_last, $N$ 番目の曜日を表すmonth_weekday, 月の最終曜日を表すmonth_weekday_lastと, 日を未指定とし, 特定の年月を表す, year_month, 前述したyear_month_day, 特定の年月の最終日を表すyear_month_day_last, 特定の年月の $N$ 番目の曜日を表すyear_month_weekday, 特定の年月の最終曜日を表すyear_month_weekday_last が提供される.

constexpr auto md = February/1d;
static_assert(std::is_same<decltype(md), std::chrono::month_day>::value);
constexpr auto mdl = February/last;  // mdl is the last day of February of an as yet unspecified year
static_assert(mdl.month() == February);
static_assert(std::is_same<decltype(mdl), std::chrono::month_day_last>::value);
constxpr auto mw = February/Sunday[5];
static_assert(std::is_same<decltype(mw), std::chrono::month_weekday>::value);
constexpr auto mwl = February/Sunday[last];
static_assert(std::is_same<decltype(mwl), std::chrono::month_weekday_last>::value);
constexpr auto ym = 2016y/February;
static_assert(std::is_same<decltype(ym), std::chrono::year_month>::value);
constexpr auto ymd = 2016y/February/1d;
static_assert(std::is_same<decltype(ymd), std::chrono::year_month_day>::value);
constexpr auto ymdl = 2016y/February/last;
static_assert(std::is_same<decltype(ymdl), std::chrono::year_month_day_last>::value);
constexpr auto ymw = 2016y/February/Sunday[1];
static_assert(std::is_same<decltype(ymw), std::chrono::year_month_weekday>::value);
constexpr auto ymwl = 2016y/February/last;
static_assert(std::is_same<decltype(ymwl), std::chrono::year_month_day_last>::value);

フルカレンダー型, 部分カレンダー型, sys_days型の全てで, operator <<のオーバーロードによる IO ストリームへの出力機能が提供される他, 非メンバ関数として, to_stream, from_stream が提供される. これらはそれぞれ, 指定されたフォーマットの通りに出力する機能と, 指定されたフォーマットを使用して入力ストリームから解析する機能を持つ.

std::cout << std::chrono::sys_days{Sunday[5]/May/2016} << std::endl; // 2016-05-29
std::chrono::to_stream(std::cout, "%b/%d/%Y %A %T", std::chrono::sys_days{2016y/May/29d} + 30min); // May/29/2016 Sunday 00:30:00

auto is = std::istringstream{"2016-5-26"};
auto tp = std::chrono::sys_days{};
std::chrono::from_stream(in, "%F", tp);
if (!is.fail()) std::cout << tp << std::endl; // 2016-05-26

また, time_of_dayクラスが提供される. これは, hours, minutes, seconds, duration<Rep, Period> の 4 つに対する特殊化が行われており, それぞれ午前 0 時からの時間, 時間:分, 時間:分:秒, 時間:分:秒:$X$ といった書式設定ができる.

std::chrono::time_of_day<std::chrono::hours> todh(1h);
todh.make12();
std::cout << todh << '\n'; // 1am
todh.make24();
std::cout << todh << '\n'; // 0100

std::chrono::time_of_day<std::chrono::minutes> todm(1h + 30min);
todm.make12();
std::cout << todm << '\n'; // 1:30am
todm.make24();
std::cout << todm << '\n'; // 01:30

std::chrono::time_of_day<std::chrono::seconds> tods(1h + 30min + 30s);
tods.make12();
std::cout << tods << '\n'; // 1:30:30am
tods.make24();
std::cout << tods << '\n'; // 01:30:30

std::chdono::time_of_day<std::chrono::milliseconds> todms(1h + 30min + 30s + 30ms);
todms.make12();
std::cout << todms << '\n'; // 1:30:30.030am
todms.make24();
std::cout << todms << '\n'; // 01:30:30.030

タイムゾーン

namespace std { namespace chrono {

struct local_t {};
template <class Duration>
using local_time = time_point<local_t, Duration>;
using local_seconds = local_time<seconds>;
using local_days = local_time<days>;

struct sys_info {
    sys_seconds   begin;
    sys_seconds   end;
    seconds       offset;
    minutes       save;
    string        abbrev;
};

struct local_info {
    enum {unique, nonexistent, ambiguous} result;
    sys_info first;
    sys_info second;
};

enum class choose {earliest, latest};

class time_zone {
public:
    time_zone(const time_zone&) = delete;
    time_zone& operator=(const time_zone&) = delete;
    const string& name() const noexcept;
    template <class Duration> sys_info   get_info(sys_time<Duration> st)   const;
    template <class Duration> local_info get_info(local_time<Duration> tp) const;

    template <class Duration>
    sys_time<typename common_type<Duration, seconds>::type>
    to_sys(local_time<Duration> tp) const;

    template <class Duration>
    sys_time<typename common_type<Duration, seconds>::type>
    to_sys(local_time<Duration> tp, choose z) const;

    template <class Duration>
    local_time<typename common_type<Duration, seconds>::type>
    to_local(sys_time<Duration> tp) const;
};

struct tzdb {
    string            version;
    vector<time_zone> zones;
    vector<link>      links;
    vector<leap>      leaps;

    const time_zone* locate_zone(string_view tz_name) const;
    const time_zone* current_zone() const;
};

class tzdb_list {
    atomic<tzdb*> head_{nullptr};  // exposition only
public:
    class const_iterator;
    const tzdb& front() const noexcept;
    const_iterator erase_after(const_iterator p) noexcept;

    const_iterator begin() const noexcept;
    const_iterator end()   const noexcept;

    const_iterator cbegin() const noexcept;
    const_iterator cend()   const noexcept;
};

} }

• local_timeはlocal_tという空の擬似クロック型が指定されており, これは当然 C++ の Clock ライブラリコンセプトを満たしていないが, 未定義のタイムゾーンに関するローカル時刻であることを示す.
• sys_info構造体は, time_zoneとsys_time, またはlocal_timeの組み合わせ, およびzoned_timeから取得することができる. 実質的には, time_zoneとsys_timeのペアであり, 低レベル API を表現する. sys_timeからlocal_timeへの通常の変換では, 暗黙的にこの構造体が使用される.
  • begin, endフィールドは, time_zoneおよびtime_pointについてoffsetとabbrevが$[$begin, end$)$ であることを示す.
  • offsetフィールドは, 関連するtime_zoneおよびtime_pointに有効な UTC オフセットを示す(offset = local_time - sys_time).
  • saveフィールドは, 通常local_timeとsys_timeの変換では必要のない”余分な”情報であるが, サマータイムの対応で必要となる. save != 0minの場合, この sys_info はサマータイムの時間帯にあると判断する. offset - saveによって, このtime_zoneがサマータイムに対応できていない可能性を導出できる. しかし, この情報は正式なものではなく, そのような情報を確実に取得する唯一の方法は, save == 0minであるsys_infoを返すtime_pointと, 確認したいtime_zoneを照会することである.
  • abbrevフィールドは, 関連するtime_zoneおよびtime_pointに使用される現在の略語を示す. 略語は, time_zone間で一意でないため, 略語をtime_zoneと UTC のオフセットに確実にマッピングすることはできない
  • IO ストリームに対応している. zoned_time zt = { "Asia/Tokyo", system_clock::now() }; std::cout << zt.get_info() << '\n';
• local_info構造体は, 低レベル API を表す. local_timeからsys_timeへの通常の変換では, 暗黙的にこの構造体が使用される.
  • local_timeからsys_timeへの変換が唯一(サマータイムでない)で, result == unique である場合, firstが正しいsys_infoがセットされ, secondが 0 で初期化される.
  • 変換が存在しない(result == noexistent)⁶場合, firstはlocal_timeの直前で終了するsys_infoがセットされ, secondはlocal_timeの直後に開始するsys_infoがセットされる.
  • 変換が曖昧(result == ambiguous)⁷な場合, firstはlocal_timeの直後に終了するsys_infoがセットされ, secondはlocal_timeの直前で開始するsys_infoがセットされる.
  • IO ストリームに対応している. std::cout << get_tzdb().current_zone()->get_info(local_days{2016y/May/29d}) << '\n';
• time_zone構造体は, 特定の地域の全てのタイムゾーン遷移を表現する. データベースの初期化の過程で, 現在地のタイムゾーン, およびタイムゾーンの情報をなんらかの方法⁸⁹で構築する. Strong ordering¹⁰ を満たす.
  • nameメンバ関数によって, time_zoneの名前¹¹を取得できる.
  • get_infoメンバ関数によって, sys_info, local_infoを取得できる.
  • to_sysメンバ関数によって, sys_time, local_timeを取得できる.
    • time_zone::to_sys(local_time<Duration> tp) const;: 少なくともsecondsと同じぐらいのsys_timeであり, 引数の精度がさらに高ければそれに合わせられる. tpからsys_timeへの変換が曖昧¹²である場合, ambiguous_local_time例外をスローする¹³. tpからsys_timeへの変換が存在しない¹⁴場合, nonexistent_local_time例外をスローする¹⁵.
    • time_zone::to_sys(local_time<Duration> tp, choose z) const;: 少なくともsecondsと同じぐらいのsys_timeであり, 引数の精度がさらに高ければそれに合わせられる. tpからsys_timeへの変換が曖昧¹⁶があいまいである場合, z == choose::earliestの場合は, サマータイム以前のsys_timeを返し, z == choose::latestの場合は, サマータイム以後のsys_timeを返す. tp が 2 つの UTC time_pointの間に存在しない時間を表す場合, 2 つの UTC time_pointは同じになり, UTC time_pointが返される.
    • time_zone::to_local(sys_time<Duration> tp) const;: tp と自身のtime_zoneに関連づけられたlocal_timeを返す.
      
• tzdbは, 前述した通り, タイムゾーンデータベースを表現する.
  • versionは, そのデータベースバージョンを表す. zones, links, leapsは, 検索の高速化のために, 構築時に昇順ソートされる.
  • locate_zoneメンバ関数から, 与えられたstring_viewオブジェクトとname()が等価であるtime_zoneが見つかった場合, そのtime_zoneへのポインタを取得できる. そうでない場合, 与えられたstring_viewとlink.name()(ここで, linkは後述しているtime_zoneの代替名を表現するクラスである)が等価であるlinkが見つかった場合, zone.name() == link.target()のtime_zoneポインタが取得できる. そうでない場合, runtime_error例外を送出する. 例外送出以外でこの関数から処理が返るとき, 返される戻り値は必ず有効なtime_zoneへのポインタである.
  • current_zoneメンバ関数から, コンピューターに設定されたローカルタイムゾーンを取得できる.
• tzdb_listは, tzdbのアトミックポインターをもつ, tzdbのシングルトンリストである.　複数のバージョンのデータベースを, 同リストを介して一度に使用することができる. 例:for (auto&& v : get_tzdb_list()) { std::cout << v << '\n'; }
  • frontメンバ関数によって, 先頭tzdbの参照を得ることができる. これは, reload_tzdb非メンバ関数に対してスレッドセーフである.
  • erase_afterメンバ関数によって, 与えられたイテレータの後に参照するtzdbを消去する. 消去された要素の次の要素を指すイテレータが返される. そのような要素が存在しない場合, メンバ関数endを呼び出し, その結果を返す. なお, ここで消去されたtzdbを参照することを除いて, ポインター, 参照, イテレータは無効にならない. また, メンバ関数beginを呼び出し, それによって参照されるtzdbを消去することはできない.
  • beginメンバ関数によって, コンテナ内の最初のtzdbを参照するイテレータ取得できる. cbeginメンバ関数はbeginメンバ関数のconst版である.
  • endメンバ関数によって, コンテナ内の最後のtzdbより 1 つ後ろの位置を参照するイテレータを取得できる. cendメンバ関数はendメンバ関数のconst版である.
  • get_tzdb_list非メンバ関数によって, 同リストの参照を得ることができる. 同メンバ関数への呼び出しがデータベースへの最初のアクセスである場合, データベースを初期化する. この呼び出しによってデータベースが初期化された場合, tzdbを一つ持つtzdb_listが構築される. 同メンバ関数を一度に複数のスレッドから呼び出しても競合せず, スレッドセーフである. 何らかの理由で有効なリストの参照を返せず, 1 つ以上の有効なtzdbを含む場合, runtime_error例外を送出する.
  • get_tzdb非メンバ関数によって, 同リストの先頭tzdbの参照を得ることができる(get_tzdb_list().front()).
  • locate_zone非メンバ関数によって, 次の値を得ることができる. なお, これがデータベースへの最初のアクセスである場合, データベースを初期化する. get_tzdb().locate_zone(tz_name);
  • current_zone非メンバ関数によって, 次の値を得ることができる. get_tzdb().current_zone();

namespace std { namespace chrono {

const tzdb& reload_tzdb();
string remote_version();

} }

• reload_tzdb非メンバ関数は, 最初にリモートタイムゾーンデータベースのチェックを行い, ローカルデータベースとリモートデータベースのバージョンが同じである場合はなにもしない. それ以外の場合, リモートデータベースは, get_tzdb_list非メンバ関数によってアクセスされるtzdb_listの先頭にプッシュされる. いずれの場合も, get_tzdb_list().front() が返される. この関数は, get_tzdb_list().front()とget_tzdb_list().erase_after()に対してスレッドセーフである. 何らかの理由で有効なtzdbの参照が戻されない場合, runtime_error例外が送出される.
• remote_version非メンバ関数は, 最新のリモートデータベースバージョンの文字列(std::string)を返す. リモートバージョンが利用できない場合, 空の文字列が返される. 空でない場合, これをget_tzdb_list().versionと比較して, ローカルデータベースとリモートデータベースが同等かどうかをチェックできる.

namespace std { namespace chrono {

template <class T> struct zoned_traits {};
template <>
struct zoned_traits<const time_zone*> {
    static const time_zone* default_zone();
    static const time_zone* locate_zone(string_view name);
};

} }

zoned_traitsによって, zoned_timeのデフォルトコンストラクタの動作をカスタマイズすることができる.

• zoned_traits<const time_zone*>::default_zone(); は, std::chrono::locate_zone("UTC") を返す.
• zoned_traits<const time_zone*>::locate_zone(string_view name); は, std::chrono::locate_zone(name) を返す.

template <class Duration, class TimeZonePtr = const time_zone*>
class zoned_time {
public:
    using duration = common_type_t<Duration, seconds>;

private:
    TimeZonePtr        zone_;  // exposition only
    sys_time<duration> tp_;    // exposition only

public:
    zoned_time();
    zoned_time(const zoned_time&) = default;
    zoned_time& operator=(const zoned_time&) = default;

             zoned_time(const sys_time<Duration>& st);
    explicit zoned_time(TimeZonePtr z);
    explicit zoned_time(string_view name);

    template <class Duration2>
        zoned_time(const zoned_time<Duration2>& zt) noexcept;

    zoned_time(TimeZonePtr z,    const sys_time<Duration>& st);
    zoned_time(string_view name, const sys_time<Duration>& st);

    zoned_time(TimeZonePtr z,    const local_time<Duration>& tp);
    zoned_time(string_view name, const local_time<Duration>& tp);
    zoned_time(TimeZonePtr z,    const local_time<Duration>& tp, choose c);
    zoned_time(string_view name, const local_time<Duration>& tp, choose c);

    template <class Duration2, class TimeZonePtr2>
        zoned_time(TimeZonePtr z, const zoned_time<Duration2, TimeZonePtr2>& zt);
    template <class Duration2, class TimeZonePtr2>
        zoned_time(TimeZonePtr z, const zoned_time<Duration2, TimeZonePtr2>& zt, choose);

    zoned_time(string_view name, const zoned_time<Duration>& zt);
    zoned_time(string_view name, const zoned_time<Duration>& zt, choose);

    zoned_time& operator=(const sys_time<Duration>& st);
    zoned_time& operator=(const local_time<Duration>& ut);

             operator sys_time<duration>()   const;
    explicit operator local_time<duration>() const;

    TimeZonePtr          get_time_zone()  const;
    local_time<duration> get_local_time() const;
    sys_time<duration>   get_sys_time()   const;
    sys_info             get_info()       const;
};

• invariant なzoned_time<Duration>は常に有効なtime_zoneを参照し, 曖昧でない時間を表す.
• デフォルコンストラクタは, zone_をzoned_traits::default_zone()で初期化し, tp_をデフォルト構築してzoned_timeを構築する.
• コピーコンストラクタは, 関連するtime_zoneを転送する. Durationがnoexceptコピーコンストラクタである場合, zoned_time<Duration>はnoexceptコピーコンストラクタである.
• zoned_time(const sys_time<Duration>& st): zone_をzoned_traits::default_zoneで初期化し, tp_をstで初期化してzoned_timeを構築する.
• zoned_time(TimeZonePtr z): std::move(z)でzone_を初期化し, zoned_timeを構築する. このとき, zは有効なtime_zoneを指していなければならない.
• zoned_time(string_view name): zoned_traits::locate_zone(name)でzone_を初期化し, tp_をデフォルト構築してzoned_timeを構築する.
• zoned_time(const zoned_time<Duration2, TimeZonePtr>& y) noexcept: x == yとなるzoned_time, xを構築する.
• zoned_time(TimeZonePtr z, const sys_time<Duration>& st): zone_をstd::move(z)で初期化し, tp_をstで初期化してzoned_timeを構築する. このとき, zは有効なtime_zoneを指していなければならない.
• zoned_time(string_view name, const sys_time<Duration>& st): {zoned_traits<TimeZonePtr>::locate_zone(name), st}と同等の構築を行う.
• zoned_time(TimeZonePtr z, const local_time<Duration>& tp): zone_をstd::move(z)で初期化し, tp_をzone_->to_sys(t)で初期化してzoned_timeを構築する. このとき, zは有効なtime_zoneを指していなければならない.
• zoned_time(string_view name, const local_time<Duration>& tp): {zoned_traits<TimeZonePtr>::locate_zone(name), tp}と同等の構築を行う.
• zoned_time(TimeZonePtr z, const local_time<Duration>& tp, choose c): zoned_をstd::moev(z)で初期化し, tpをzone_->to_sys(t, c)で初期化してzoned_timeを構築する. このとき, zは有効なtime_zoneを指していなければならない.
• zoned_time(string_view name, const local_time<Duration>& tp, choose c): {zoned_traits<TimeZonePtr>::locate_zone(name), tp, c}と同等の構築を行う.
• zoned_time(TimeZonePtr z, const zoned_time<Duration2, TimeZonePtr2>& y): zone_をstd::move(z)で初期化し, tp_をz.tp_で初期化してzoned_timeを構築する. このとき, zは有効なtime_zoneを指していなければならない.
• zoned_time(TimeZonePtr z, const zoned_time<Duration2, TimeZonePtr2>& y, choose): {z, y}と同等の構築を行う. このとき, zは有効なtime_zoneを指していなければならない. chooseパラメータを渡すことができるが, これによって挙動が変わることはない.
• zoned_time(string_view name, const zoned_time<Duration>& y): {zoned_traits<TimeZonePtr>::locate_zone(name), y}と同等の構築を行う.
• zoned_time(string_view name, const zoned_time<Duration>& y, choose c): {locate_zone(name), y, c}と同等の構築を行う. chooseパラメータを渡すことができるが, これによって挙動が変わることはない.
• operator=(const local_time<Duration>& lt): 代入後, get_local_time() == ltとなるよう代入し*thisを返す. この代入は, get_time_zoneの戻り値には影響しない.
• operator sys_time<duration>() const: get_sys_time()を返す.
• operator local_time<duration>() const: get_local_time() を返す.
• get_time_zoneメンバ関数によって, zone_のポインタを取得できる.
• get_local_timeメンバ関数によって, 構築時に設定されたタイムゾーンでのlocal_timeオブジェクトを取得できる(retunr zone_->to_local(tp_);).
• get_sys_timeメンバ関数によって, 構築時に設定されたタイムゾーンでのsys_timeオブジェクトを取得できる(return tp_;).
• get_infoメンバ関数によって, 構築時に設定されたタイムゾーンでのsys_infoオブジェクトを取得できる(return zone_->get_info(tp_);).

同ライブラリを利用して, 例えば次のように, ある日時の東京の時間帯を得ることができる¹⁸.

auto tp1 = std::chrono::sys_days{2016y/May/29d} + 7h + 30min + 6s + 153ms; // 2016-05-29 07:30:06.153 UTC
std::chrono::zoned_time zt1 = {"Asia/Tokyo", tp1};
std::cout << zt1 << '\n'; // 2016-05-29 16:30:06.153 JST

auto tp2 = std::chrono::local_days{2016y/May/29d} + 7h + 30min + 6s + 153ms; // 2016-05-29 07:30:06.153 JTC
auto zt2 = std::chrono::zoned_time{"Asia/Tokyo", tp2};
std::cout << zt << '\n'; // 2016-05-29 07:30:06.153 JST

class leap
{
    sys_seconds date_;  // exposition only
public:
    leap(const leap&)            = default;
    leap& operator=(const leap&) = default;

    // Undocumented constructors
    sys_seconds date() const;
};

• dateメンバ関数によって, date_を取得できる. date_には閏秒挿入の日付が格納されている.
• 閏秒挿入の全ての日付をfor (auto& l : get_tzdb().leaps) std::cout << l.date() << '\n';で確認できる.

またタイムゾーンデータベースの構築時に作成される, time_zoneの代替名を表現するlinkというクラスも提供される.

Clock

新たに utc_clock, tai_clock, gps_clock, file_clock の 4 つのクロック, また, そのtime_point型のエイリアス(utc_time, utc_seconds, tai_time, tai_seconds, gps_time, gps_seconds) が提供される.

• utc_clock は, 協定世界時(UTC)を表現するクロックであり, 1970 年 1 月 1 日木曜日午後 00:00:00 分からの時間を測定する. これには, 閏秒が含まれる.
• tai_clockは, 国際原始時計(TAI)を表現するクロックであり, 1958 年 1 月 1 日 00:00:00 からの時間を測定し, この日の UTC(1957-12-31 23:59:50 UTC)よりも 10 秒前にオフセットされている. これには, 閏秒が含まれない²⁰.
• gps_clockは GPS 時刻を表現するクロックであり, UTC 1980 年 1 月 6 日 00:00:00 からの時間を測定する. 閏秒は含まれない²¹.
• file_clockは, C++20 で追加されたエイリアス, using file_time_type = std::chrono::time_point<std::chrono::file_clock>;で利用されるファイルクロックである²².

試用

同ライブラリを利用した任意月のカレンダーを出力するプログラムは, 既にあったのだが, 特別何か別のものは思いつかないので, とりあえず, 任意年の全ての月のカレンダーを出力するプログラムを書いて試用.

#include <algorithm>
#include <array>
#include <chrono>
#include <iostream>
#include <iomanip>
#include <utility>

namespace ns {

template <class> struct weeks_init;
template <std::size_t... s>
struct weeks_init<std::index_sequence<s...>> {
    constexpr weeks_init() = default;
    constexpr std::array<std::chrono::weekday, sizeof...(s)> operator()() const noexcept { return {{ std::chrono::weekday{s}... }}; }
};
constexpr auto weeks = weeks_init<std::make_index_sequence<7>>()();

inline void print_weeks(std::ostream& os)
{
    namespace sc = std::chrono;
    std::copy(std::begin(weeks), std::end(weeks), std::ostream_iterator<sc::weekday>(os, "  "));
    os << '\n';
}

} // namespace ns

struct print_calendar_year {
    explicit constexpr print_calendar_year(std::chrono::year y) noexcept
        : y_(y) {}

    friend std::ostream& operator<<(std::ostream& os, const print_calendar_year& this_)
    {
        using namespace std::chrono_literals;
        namespace sc = std::chrono;
        constexpr int width = 5;

        for (unsigned i = 1u, uweek = static_cast<unsigned>(sc::weekday{sc::sys_days{this_.y_/sc::January/1d}}); i <= 12u; ++i) {
            auto lastday = (this_.y_/sc::month{i}/sc::last).day();
            os << std::setw(ns::weeks.size() * width / 2) << sc::month{i} << '\n';
            ns::print_weeks(os << std::setw(width));

            unsigned k = 0;
            for (; k < uweek; ++k) os << std::setw(width) << " ";
            for (sc::day d{1}; d <= lastday; ++d) {
                os << std::setw(width) << static_cast<unsigned>(d);
                if (++k > 6) {
                    k = 0;
                    os << '\n';
                }
            }
            if (k) os << '\n';
            uweek = k;
        }
        return os;
    }
private:
    std::chrono::year y_;
};

int main()
{
    std::cout << print_calendar_year{std::chrono::year{2000}} << std::endl;
}

実行結果.

タイムゾーンに関するサンプルは, 元の実装のドキュメントで多く取り上げられている. フライトタイムの計算や, IANA タイムゾーンデータベースを利用しないカスタムタイムゾーンを作成する例などが掲示されている.

感想

• とてもよく作り込まれていて, 使いやすそうに感じる.
• C++ にこのような高レベル API が導入されるのは, 少し新鮮.