DateTime.h

[詳解]

/// @file
/// @brief マイクロ秒精度の日付時刻を表す構造体 DateTime のヘッダ。
///
/// Copyright(C)SEGA

#ifndef AMDAEMON_UTIL_DATETIME_H
#define AMDAEMON_UTIL_DATETIME_H

#include "amdaemon/env.h"
#include "amdaemon/util/TimeSpan.h"

#include <chrono>
#include <string>
#include <cstdint>
#include <ctime>

namespace amdaemon
{
namespace util
{
/// @addtogroup g_util
/// @{

    //--------------------
    // DateTime 構造体定義
    //--------------------

    /// @brief マイクロ秒精度の日付時刻を表す構造体 DateTime のヘッダ。
    /// @note memcpy 可能。
    ///
    /// 内部値として西暦1年1月1日0時0分0秒からの経過マイクロ秒数値を持つ。
    /// この値の基準時刻(ローカル、UTC等)については関知しないため、利用側で定めること。
    ///
    /// UNIXタイムスタンプ値を用いてインスタンスを生成する各静的メンバ関数には、
    /// 基準時刻をUTCとするかローカルとするか選択するための引数が用意されている。
    /// いずれも引数指定を省略した場合はローカルを基準とする。
    struct DateTime
    {
        /// 内部値の表現型。
        typedef std::uint64_t value_type;

        /// 個別要素値の表現型。
        typedef std::int32_t part_type;

        /// @brief 西暦1年1月1日0時0分0秒からの経過マイクロ秒数値。
        /// @attention
        /// std::time 関数が返す std::time_t 値とは異なる。
        /// std::time_t 値からの変換は静的メンバ関数 #make(std::time_t, bool) で行うこと。
        value_type value;

        /// @brief 表現可能な最小値を持つ日付時刻値を取得する。
        /// @return 最小の日付時刻値。
        static const DateTime& min();

        /// @brief 表現可能な最大値を持つ日付時刻値を取得する。
        /// @return 最大の日付時刻値。
        static const DateTime& max();

        /// @brief エポックを表すUTC(世界協定時刻)の日付時刻値を取得する。
        /// @return エポックを表すUTC(世界協定時刻)の日付時刻値。
        static const DateTime& epoch();

        /// @brief 現在日時を表す日付時刻値を取得する。
        /// @param[in] utc
        ///     UTC(世界協定時刻)の日付時刻値を作成するならば true 。
        ///     ローカルの日付時刻値を作成するならば false (既定値)。
        /// @return 現在日時を表す日付時刻値。
        static DateTime now(bool utc = false);

        /// @brief 現在日の0時0分0秒を表す日付時刻値を取得する。
        /// @param[in] utc
        ///     UTC(世界協定時刻)の日付時刻値を作成するならば true 。
        ///     ローカルの日付時刻値を作成するならば false (既定値)。
        /// @return 現在日の0時0分0秒を表す日付時刻値。
        static DateTime today(bool utc = false)
        {
            return now(utc).getDate();
        }

        /// @brief 日付時刻値を問題なく作成可能な値であるか否かを調べる。
        /// @param[in] year        年。 1 以上 max().year() 以下。
        /// @param[in] month       月。 1 以上 12 以下。
        /// @param[in] day         日。 1 以上かつ月の日数以下。
        /// @param[in] hour        時。 0 以上 23 以下。
        /// @param[in] minute      分。 0 以上 59 以下。
        /// @param[in] second      秒。 0 以上 59 以下。
        /// @param[in] millisecond ミリ秒。 0 以上 999 以下。
        /// @param[in] microsecond マイクロ秒。 0 以上 999 以下。
        /// @retval true  作成可能である場合。
        /// @retval false 作成不可能である場合。
        /// @see make(part_type, part_type, part_type, part_type, part_type, part_type, part_type, part_type)
        ///
        /// この関数が true を返す場合、同じ引数を静的メンバ関数
        /// make(part_type, part_type, part_type, part_type, part_type, part_type, part_type, part_type)
        /// に渡すことで、例外を発生させることなく日付時刻値を作成可能であることが保証される。
        static bool canMake(
            part_type year,
            part_type month,
            part_type day,
            part_type hour,
            part_type minute,
            part_type second = 0,
            part_type millisecond = 0,
            part_type microsecond = 0);

        /// @brief 日付と時刻を表す値から日付時刻値を作成する。
        /// @param[in] year        年。 1 以上 max().year() 以下。
        /// @param[in] month       月。 1 以上 12 以下。
        /// @param[in] day         日。 1 以上かつ月の日数以下。
        /// @param[in] hour        時。 0 以上 23 以下。
        /// @param[in] minute      分。 0 以上 59 以下。
        /// @param[in] second      秒。 0 以上 59 以下。
        /// @param[in] millisecond ミリ秒。 0 以上 999 以下。
        /// @param[in] microsecond マイクロ秒。 0 以上 999 以下。
        /// @return 作成された日付時刻値。
        /// @see canMake(part_type, part_type, part_type, part_type, part_type, part_type, part_type, part_type)
        ///
        /// @exception Exception
        /// - 引数 year に 0 以下もしくは max().year() より大きい値を指定した場合。
        /// - 引数 month に 0 以下もしくは 13 以上の値を指定した場合。
        /// - 引数 day に 0 以下もしくは月の日数を超える値を指定した場合。
        /// - 引数 hour に負数もしくは 24 以上の値を指定した場合。
        /// - 引数 minute に負数もしくは 60 以上の値を指定した場合。
        /// - 引数 second に負数もしくは 60 以上の値を指定した場合。
        /// - 引数 millisecond に負数もしくは 1000 以上の値を指定した場合。
        /// - 引数 microsecond に負数もしくは 1000 以上の値を指定した場合。
        /// - 内部値に変換した値が表現可能範囲に収まらない場合。
        static DateTime make(
            part_type year,
            part_type month,
            part_type day,
            part_type hour,
            part_type minute,
            part_type second = 0,
            part_type millisecond = 0,
            part_type microsecond = 0);

        /// @brief 日付時刻値を問題なく作成可能な値であるか否かを調べる。
        /// @param[in] year  年。 1 以上 max().year() 以下。
        /// @param[in] month 月。 1 以上 12 以下。
        /// @param[in] day   日。 1 以上かつ月の日数以下。
        /// @retval true  作成可能である場合。
        /// @retval false 作成不可能である場合。
        /// @see make(part_type, part_type, part_type)
        ///
        /// この関数が true を返す場合、同じ引数を静的メンバ関数
        /// make(part_type, part_type, part_type)
        /// に渡すことで、例外を発生させることなく日付時刻値を作成可能であることが保証される。
        static bool canMake(part_type year, part_type month, part_type day)
        {
            return canMake(year, month, day, 0, 0);
        }

        /// @brief 日付を表す値から日付時刻値を作成する。
        /// @param[in] year  年。 1 以上 max().year() 以下。
        /// @param[in] month 月。 1 以上 12 以下。
        /// @param[in] day   日。 1 以上かつ月の日数以下。
        /// @return 作成された日付時刻値。
        /// @see canMake(part_type, part_type, part_type)
        ///
        /// @exception Exception
        /// - 引数 year に 0 以下もしくは max().year() より大きい値を指定した場合。
        /// - 引数 month に 0 以下もしくは 13 以上の値を指定した場合。
        /// - 引数 day に 0 以下もしくは月の日数を超える値を指定した場合。
        /// - 内部値に変換した値が表現可能範囲に収まらない場合。
        ///
        /// make(year, month, day, 0, 0) と等価。
        static DateTime make(part_type year, part_type month, part_type day)
        {
            return make(year, month, day, 0, 0);
        }

        /// @brief 日付時刻値を問題なく作成可能なタイムポイント値であるか否かを調べる。
        /// @param[in] timePoint システムクロックのタイムポイント値。
        /// @param[in] utc
        ///     UTC(世界協定時刻)の日付時刻値を作成するならば true 。
        ///     ローカルの日付時刻値を作成するならば false (既定値)。
        /// @retval true  作成可能である場合。
        /// @retval false 作成不可能である場合。
        /// @see make(const std::chrono::system_clock::time_point&, bool)
        ///
        /// この関数が true を返す場合、同じ引数を静的メンバ関数
        /// make(const std::chrono::system_clock::time_point&, bool)
        /// に渡すことで、例外を発生させることなく日付時刻値を作成可能であることが保証される。
        static bool canMake(
            const std::chrono::system_clock::time_point& timePoint,
            bool utc = false);

        /// @brief タイムポイント値から日付時刻値を作成する。
        /// @param[in] timePoint システムクロックのタイムポイント値。
        /// @param[in] utc
        ///     UTC(世界協定時刻)の日付時刻値を作成するならば true 。
        ///     ローカルの日付時刻値を作成するならば false (既定値)。
        /// @return 作成された日付時刻値。
        /// @see canMake(const std::chrono::system_clock::time_point&, bool)
        ///
        /// @exception Exception
        /// 内部値に変換した値が表現可能範囲に収まらない場合。
        static DateTime make(
            const std::chrono::system_clock::time_point& timePoint,
            bool utc = false);

        /// @brief 日付時刻値を問題なく作成可能なUNIXタイムスタンプ値であるか否かを調べる。
        /// @param[in] timeStamp UNIXタイムスタンプ値。
        /// @param[in] utc
        ///     UTC(世界協定時刻)の日付時刻値を作成するならば true 。
        ///     ローカルの日付時刻値を作成するならば false (既定値)。
        /// @retval true  作成可能である場合。
        /// @retval false 作成不可能である場合。
        /// @see make(std::time_t, bool)
        ///
        /// この関数が true を返す場合、同じ引数を静的メンバ関数
        /// make(std::time_t, bool)
        /// に渡すことで、例外を発生させることなく日付時刻値を作成可能であることが保証される。
        static bool canMake(std::time_t timeStamp, bool utc = false);

        /// @brief UNIXタイムスタンプ値から日付時刻値を作成する。
        /// @param[in] timeStamp UNIXタイムスタンプ値。
        /// @param[in] utc
        ///     UTC(世界協定時刻)の日付時刻値を作成するならば true 。
        ///     ローカルの日付時刻値を作成するならば false (既定値)。
        /// @return 作成された日付時刻値。
        /// @see canMake(std::time_t, bool)
        ///
        /// @exception Exception
        /// 内部値に変換した値が表現可能範囲に収まらない場合。
        static DateTime make(std::time_t timeStamp, bool utc = false);

        /// @brief 日付時刻値を問題なく作成可能な std::tm 構造体値であるか否かを調べる。
        /// @param[in] tm std::tm 構造体値。夏時間情報は無視される。
        /// @retval true  作成可能である場合。
        /// @retval false 作成不可能である場合。
        /// @see make(const std::tm&)
        ///
        /// この関数が true を返す場合、同じ引数を静的メンバ関数
        /// make(const std::tm&)
        /// に渡すことで、例外を発生させることなく日付時刻値を作成可能であることが保証される。
        static bool canMake(const std::tm& tm);

        /// @brief std::tm 構造体値から日付時刻値を作成する。
        /// @param[in] tm std::tm 構造体値。夏時間情報は無視される。
        /// @return 作成された日付時刻値。
        /// @see canMake(const std::tm&)
        ///
        /// @exception Exception
        /// - 引数 tm のいずれかのメンバ値が有効範囲外である場合。
        /// - 内部値に変換した値が表現可能範囲に収まらない場合。
        static DateTime make(const std::tm& tm);

        /// @brief DateTime 値に TimeSpan 値を加算する。
        /// @param[in] dt 加算対象。
        /// @param[in] span 加算値。
        /// @return 加算結果の日付時刻値。
        ///
        /// @exception Exception
        /// 演算結果値が表現可能範囲に収まらない場合。
        static DateTime add(const DateTime& dt, const TimeSpan& span);

        /// @brief DateTime 値から TimeSpan 値を減算する。
        /// @param[in] dt 減算対象。
        /// @param[in] span 減算値。
        /// @return 減算結果の日付時刻値。
        ///
        /// @exception Exception
        /// 演算結果値が表現可能範囲に収まらない場合。
        static DateTime subtract(const DateTime& dt, const TimeSpan& span);

        /// @brief DateTime 値から別の DateTime 値を減算して時間間隔を算出する。
        /// @param[in] dt1 減算対象。
        /// @param[in] dt2 減算値。
        /// @return 減算結果の時間間隔値。
        ///
        /// @exception Exception
        /// 演算結果値が表現可能範囲に収まらない場合。
        static TimeSpan subtract(const DateTime& dt1, const DateTime& dt2);

        /// @brief 指定した年が閏年であるか否かを取得する。
        /// @param[in] year  年。 1 以上 max().year() 以下。
        /// @retval true  閏年である場合。
        /// @retval false 閏年ではない場合。
        ///
        /// @exception Exception
        /// 引数 year に 0 以下もしくは max().year() より大きい値を指定した場合。
        static bool isLeapYear(part_type year);

        /// @brief 指定した年月の日数を取得する。
        /// @param[in] year  年。 1 以上 max().year() 以下。
        /// @param[in] month 月。 1 以上 12 以下。
        /// @return 指定した年月の日数。 28 以上 31 以下。
        ///
        /// @exception Exception
        /// - 引数 year に 0 以下もしくは max().year() より大きい値を指定した場合。
        /// - 引数 month に 0 以下もしくは 13 以上の値を指定した場合。
        static part_type getDaysOf(part_type year, part_type month);

        /// @brief 指定したUTC日付時刻値のUNIXタイムスタンプを表す時間間隔値を算出する。
        /// @param[in] utcTime UTC日付時刻値。既定では現在日時を用いる。
        /// @return UNIXタイムスタンプを表す時間間隔値。
        ///
        /// @exception Exception
        /// - 演算結果値が表現可能範囲に収まらない場合。
        /// - 引数 utcTime がエポックより過去である場合。
        ///
        /// UTCにおけるエポックからの経過時間を算出して返す。
        /// 引数 utcTime の基準時刻がUTCである前提で計算する。
        static TimeSpan calcUnixTimestampOf(const DateTime& utcTime = now(true));

        /// @brief 日時表現における年を取得する。
        /// @return 年。
        part_type year() const;

        /// @brief 日時表現における月を取得する。
        /// @return 月。
        part_type month() const;

        /// @brief 日時表現における日を取得する。
        /// @return 日。
        part_type day() const;

        /// @brief 日時表現における時を取得する。
        /// @return 時。
        part_type hour() const;

        /// @brief 日時表現における分を取得する。
        /// @return 分。
        part_type minute() const;

        /// @brief 日時表現における秒を取得する。
        /// @return 秒。
        part_type second() const;

        /// @brief 日時表現におけるミリ秒を取得する。
        /// @return ミリ秒。
        part_type millisecond() const;

        /// @brief 日時表現におけるマイクロ秒を取得する。
        /// @return マイクロ秒。
        part_type microsecond() const;

        /// @brief 日時表現における曜日を表す数値を取得する。
        /// @return 曜日を表す数値。 0 が日曜、 6 が土曜。
        part_type week() const;

        /// @brief 1年1月1日からの通算日数を取得する。
        /// @return 1年1月1日からの通算日数。
        value_type getTotalDays() const;

        /// @brief 時刻部分を0時0分0秒にした日付時刻値を取得する。
        /// @return 時刻部分を0時0分0秒にした日付時刻値。
        DateTime getDate() const;

        /// @brief 日時表現における各要素値をまとめて取得する。
        /// @param[in] year        年の設定先。取得しないならば nullptr 。
        /// @param[in] month       月の設定先。取得しないならば nullptr 。
        /// @param[in] day         日の設定先。取得しないならば nullptr 。
        /// @param[in] hour        時の設定先。取得しないならば nullptr 。
        /// @param[in] minute      分の設定先。取得しないならば nullptr 。
        /// @param[in] second      秒の設定先。取得しないならば nullptr 。
        /// @param[in] millisecond ミリ秒の設定先。取得しないならば nullptr 。
        /// @param[in] microsecond マイクロ秒の設定先。取得しないならば nullptr 。
        void getParts(
            part_type* year,
            part_type* month = nullptr,
            part_type* day = nullptr,
            part_type* hour = nullptr,
            part_type* minute = nullptr,
            part_type* second = nullptr,
            part_type* millisecond = nullptr,
            part_type* microsecond = nullptr) const;

        /// @brief 文字列表現値を作成する。
        /// @param[in] format フォーマット文字列。
        /// @return 文字列表現値。
        ///
        /// 引数 format には下記のフォーマット文字列と任意の文字列の組み合わせを指定する。
        /// 大文字と小文字は区別されることに注意。
        ///
        /// - "%Y" -- 年。
        /// - "%y" -- 年の下2桁。
        /// - "%M" -- 月。
        /// - "%D" -- 日。
        /// - "%h" -- 時。
        /// - "%m" -- 分。
        /// - "%s" -- 秒。
        /// - "%i" -- ミリ秒。
        /// - "%u" -- マイクロ秒。
        /// - "%w" -- 英語略式の曜日。 "Sun" 等。
        /// - "%W" -- 日本語の曜日。 "日" 等。
        /// - "%x" -- "%Y/%02M/%02D" と等価。
        /// - "%X" -- "%02h:%02m:%02s" と等価。
        /// - "%t" -- "%x %X" と等価。
        /// - "%v" -- value 値そのもの。
        /// - "%%" -- 文字 '%' 。
        ///
        /// 数値を表すフォーマット文字列は、1文字目の '%' の直後に幅指定を行う事ができる。
        /// 幅指定は「数字」か、「文字 '0' + 数字」の形式で指定でき、例えば次のようになる。
        ///
        /// - "%2s"  -- 最小2文字幅になるよう先頭に空白文字が付与される。
        /// - "%02s" -- 最小2文字幅になるよう先頭に文字 '0' が付与される。
        ///
        /// 引数 format に nullptr を指定した場合、 "%t" を指定したものとして扱う。
        std::wstring toString(const wchar_t* format = nullptr) const;

        /// @brief 加算代入演算子のオーバロード。
        /// @param[in] r 右辺値。
        /// @return 自身の参照。
        ///
        /// @exception Exception
        /// 演算結果値が表現可能範囲に収まらない場合。
        DateTime& operator+=(const TimeSpan& r)
        {
            return (*this = add(*this, r));
        }

        /// @brief 減算代入演算子のオーバロード。
        /// @param[in] r 右辺値。
        /// @return 自身の参照。
        ///
        /// @exception Exception
        /// 演算結果値が表現可能範囲に収まらない場合。
        DateTime& operator-=(const TimeSpan& r)
        {
            return (*this = subtract(*this, r));
        }
    };

/// @}

    //--------------------
    // インライン関数定義
    //--------------------

    /// @brief 加算演算子のオーバロード。
    /// @param[in] l 左辺値。
    /// @param[in] r 右辺値。
    /// @return 演算結果値。
    /// @relatesalso DateTime
    ///
    /// @exception Exception
    /// 演算結果値が表現可能範囲に収まらない場合。
    inline DateTime operator+(const DateTime& l, const TimeSpan& r)
    {
        return DateTime::add(l, r);
    }

    /// @brief 減算演算子のオーバロード。
    /// @param[in] l 左辺値。
    /// @param[in] r 右辺値。
    /// @return 演算結果値。
    /// @relatesalso DateTime
    ///
    /// @exception Exception
    /// 演算結果値が表現可能範囲に収まらない場合。
    inline DateTime operator-(const DateTime& l, const TimeSpan& r)
    {
        return DateTime::subtract(l, r);
    }

    /// @brief 減算演算子のオーバロード。
    /// @param[in] l 左辺値。
    /// @param[in] r 右辺値。
    /// @return 演算結果値。
    /// @relatesalso DateTime
    ///
    /// @exception Exception
    /// 演算結果値が表現可能範囲に収まらない場合。
    inline TimeSpan operator-(const DateTime& l, const DateTime& r)
    {
        return DateTime::subtract(l, r);
    }

    /// @brief 等価比較演算子のオーバロード。
    /// @param[in] l 左辺値。
    /// @param[in] r 右辺値。
    /// @return 比較結果値。
    /// @relatesalso DateTime
    inline bool operator==(const DateTime& l, const DateTime& r)
    {
        return (l.value == r.value);
    }

    /// @brief 非等価比較演算子のオーバロード。
    /// @param[in] l 左辺値。
    /// @param[in] r 右辺値。
    /// @return 比較結果値。
    /// @relatesalso DateTime
    inline bool operator!=(const DateTime& l, const DateTime& r)
    {
        return !(l == r);
    }

    /// @brief 小なり比較演算子のオーバロード。
    /// @param[in] l 左辺値。
    /// @param[in] r 右辺値。
    /// @return 比較結果値。
    /// @relatesalso DateTime
    inline bool operator<(const DateTime& l, const DateTime& r)
    {
        return (l.value < r.value);
    }

    /// @brief 大なり比較演算子のオーバロード。
    /// @param[in] l 左辺値。
    /// @param[in] r 右辺値。
    /// @return 比較結果値。
    /// @relatesalso DateTime
    inline bool operator>(const DateTime& l, const DateTime& r)
    {
        return (r < l);
    }

    /// @brief 小なり等価比較演算子のオーバロード。
    /// @param[in] l 左辺値。
    /// @param[in] r 右辺値。
    /// @return 比較結果値。
    /// @relatesalso DateTime
    inline bool operator<=(const DateTime& l, const DateTime& r)
    {
        return !(r < l);
    }

    /// @brief 大なり等価比較演算子のオーバロード。
    /// @param[in] l 左辺値。
    /// @param[in] r 右辺値。
    /// @return 比較結果値。
    /// @relatesalso DateTime
    inline bool operator>=(const DateTime& l, const DateTime& r)
    {
        return !(l < r);
    }
} // namespace util
} // namespace amdaemon

#endif // AMDAEMON_UTIL_DATETIME_H