TimeSpan.h

[詳解]

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

#ifndef AMDAEMON_UTIL_TIMESPAN_H
#define AMDAEMON_UTIL_TIMESPAN_H

#include "amdaemon/env.h"

#include <chrono>
#include <limits>
#include <string>
#include <cstdint>

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

    //--------------------
    // TimeSpan 構造体定義
    //--------------------

    /// @brief マイクロ秒精度の時間間隔を表す構造体。
    /// @note memcpy 可能。
    struct TimeSpan
    {
        /// 内部値の表現型。
        typedef std::int64_t value_type;

        /// マイクロ秒数値。
        value_type value;

        /// @brief マイクロ秒数値からインスタンスを作成する。
        /// @param[in] microseconds マイクロ秒数値。
        /// @return 作成されたインスタンス。
        static TimeSpan fromMicroseconds(value_type microseconds)
        {
            TimeSpan result = { microseconds };
            return result;
        }

        /// @brief ミリ秒数値からインスタンスを作成する。
        /// @param[in] milliseconds ミリ秒数値。
        /// @return 作成されたインスタンス。
        /// @see tryFromMilliseconds
        ///
        /// @exception Exception
        /// マイクロ秒数値に変換した値が表現可能範囲に収まらない場合。
        static TimeSpan fromMilliseconds(value_type milliseconds)
        {
            return multiply(fromMicroseconds(milliseconds), static_cast<value_type>(1000));
        }

        /// @brief ミリ秒数値からインスタンスを作成する。
        /// @param[in] milliseconds ミリ秒数値。
        /// @param[out] result 作成されたインスタンスの設定先。
        /// @retval true  作成に成功した場合。
        /// @retval false マイクロ秒数値に変換した値が表現可能範囲に収まらない場合。
        /// @see fromMilliseconds
        static bool tryFromMilliseconds(value_type milliseconds, TimeSpan& result)
        {
            return
                tryMultiply(
                    fromMicroseconds(milliseconds),
                    static_cast<value_type>(1000),
                    result);
        }

        /// @brief 秒数値からインスタンスを作成する。
        /// @param[in] seconds 秒数値。
        /// @return 作成されたインスタンス。
        /// @see tryFromSeconds
        ///
        /// @exception Exception
        /// マイクロ秒数値に変換した値が表現可能範囲に収まらない場合。
        static TimeSpan fromSeconds(value_type seconds)
        {
            return
                multiply(
                    fromMicroseconds(seconds),
                    static_cast<value_type>(1000) * 1000);
        }

        /// @brief 秒数値からインスタンスを作成する。
        /// @param[in] seconds 秒数値。
        /// @param[out] result 作成されたインスタンスの設定先。
        /// @retval true  作成に成功した場合。
        /// @retval false マイクロ秒数値に変換した値が表現可能範囲に収まらない場合。
        /// @see fromSeconds
        static bool tryFromSeconds(value_type seconds, TimeSpan& result)
        {
            return
                tryMultiply(
                    fromMicroseconds(seconds),
                    static_cast<value_type>(1000) * 1000,
                    result);
        }

        /// @brief 分数値からインスタンスを作成する。
        /// @param[in] minutes 分数値。
        /// @return 作成されたインスタンス。
        /// @see tryFromMinutes
        ///
        /// @exception Exception
        /// マイクロ秒数値に変換した値が表現可能範囲に収まらない場合。
        static TimeSpan fromMinutes(value_type minutes)
        {
            return
                multiply(
                    fromMicroseconds(minutes),
                    static_cast<value_type>(1000) * 1000 * 60);
        }

        /// @brief 分数値からインスタンスを作成する。
        /// @param[in] minutes 分数値。
        /// @param[out] result 作成されたインスタンスの設定先。
        /// @retval true  作成に成功した場合。
        /// @retval false マイクロ秒数値に変換した値が表現可能範囲に収まらない場合。
        /// @see fromMinutes
        static bool tryFromMinutes(value_type minutes, TimeSpan& result)
        {
            return
                tryMultiply(
                    fromMicroseconds(minutes),
                    static_cast<value_type>(1000) * 1000 * 60,
                    result);
        }

        /// @brief 時数値からインスタンスを作成する。
        /// @param[in] hours 時数値。
        /// @return 作成されたインスタンス。
        /// @see tryFromHours
        ///
        /// @exception Exception
        /// マイクロ秒数値に変換した値が表現可能範囲に収まらない場合。
        static TimeSpan fromHours(value_type hours)
        {
            return
                multiply(
                    fromMicroseconds(hours),
                    static_cast<value_type>(1000) * 1000 * 60 * 60);
        }

        /// @brief 時数値からインスタンスを作成する。
        /// @param[in] hours 時数値。
        /// @param[out] result 作成されたインスタンスの設定先。
        /// @retval true  作成に成功した場合。
        /// @retval false マイクロ秒数値に変換した値が表現可能範囲に収まらない場合。
        /// @see fromHours
        static bool tryFromHours(value_type hours, TimeSpan& result)
        {
            return
                tryMultiply(
                    fromMicroseconds(hours),
                    static_cast<value_type>(1000) * 1000 * 60 * 60,
                    result);
        }

        /// @brief 日数値からインスタンスを作成する。
        /// @param[in] days 日数値。
        /// @return 作成されたインスタンス。
        /// @see tryFromDays
        ///
        /// @exception Exception
        /// マイクロ秒数値に変換した値が表現可能範囲に収まらない場合。
        static TimeSpan fromDays(value_type days)
        {
            return
                multiply(
                    fromMicroseconds(days),
                    static_cast<value_type>(1000) * 1000 * 60 * 60 * 24);
        }

        /// @brief 日数値からインスタンスを作成する。
        /// @param[in] days 日数値。
        /// @param[out] result 作成されたインスタンスの設定先。
        /// @retval true  作成に成功した場合。
        /// @retval false マイクロ秒数値に変換した値が表現可能範囲に収まらない場合。
        /// @see fromDays
        static bool tryFromDays(value_type days, TimeSpan& result)
        {
            return
                tryMultiply(
                    fromMicroseconds(days),
                    static_cast<value_type>(1000) * 1000 * 60 * 60 * 24,
                    result);
        }

        /// @brief 時間間隔値からインスタンスを作成する。
        /// @tparam TCount 内部カウンタ値の表現型。
        /// @tparam TPeriod 秒に対する割合を表す有理数型。
        /// @param[in] duration 時間間隔値。
        /// @return 作成されたインスタンス。
        template<class TCount, class TPeriod>
        static TimeSpan fromDuration(const std::chrono::duration<TCount, TPeriod>& duration)
        {
            return
                fromMicroseconds(
                    std::chrono::duration_cast<std::chrono::microseconds>(duration).count());
        }

        /// @brief ゼロ値のインスタンスを作成する。
        /// @return 作成されたインスタンス。
        static TimeSpan zero()
        {
            TimeSpan result = { 0 };
            return result;
        }

        /// @brief 表現可能な最小値を持つインスタンスを作成する。
        /// @return 作成されたインスタンス。
        static TimeSpan min()
        {
            return fromMicroseconds(std::numeric_limits<value_type>::min());
        }

        /// @brief 表現可能な最大値を持つインスタンスを作成する。
        /// @return 作成されたインスタンス。
        static TimeSpan max()
        {
            return fromMicroseconds(std::numeric_limits<value_type>::max());
        }

        /// @brief 経過時間の計算に利用できるクロック時間からインスタンスを作成する。
        /// @param[in] forceStdClock 必ず標準関数 std::clock を用いるならば true 。
        /// @return 作成されたインスタンス。 0 より大きい内部値を持つ。
        /// @see #tryClock, Clock
        ///
        /// @exception Exception
        /// 内部で乗算した値が表現可能範囲に収まらない場合。
        ///
        /// 返される時間値そのものに意味はない。
        /// この関数で得た2値の差分によって経過時間を求める目的で用いる。
        ///
        /// Windows環境かつ引数 forceStdClock に false を指定した場合、
        /// 高分解能パフォーマンスカウンタが用いられる。
        ///
        /// 長期間の連続稼働により表現可能な上限値に達する場合がある。
        /// 長期間稼働する可能性がある場合、この関数ではなく Clock クラスの利用を推奨する。
        static TimeSpan clock(bool forceStdClock = false);

        /// @brief 経過時間の計算に利用できるクロック時間からインスタンスを作成する。
        /// @param[out] result 作成されたインスタンスの設定先。 0 より大きい内部値を持つ。
        /// @param[in] forceStdClock 必ず標準関数 std::clock を用いるならば true 。
        /// @retval true  作成に成功した場合。
        /// @retval false 内部で乗算した値が表現可能範囲に収まらない場合。
        /// @see #clock, Clock
        ///
        /// 返される時間値そのものに意味はない。
        /// この関数で得た2値の差分によって経過時間を求める目的で用いる。
        ///
        /// Windows環境かつ引数 forceStdClock に false を指定した場合、
        /// 高分解能パフォーマンスカウンタが用いられる。
        ///
        /// 長期間の連続稼働により表現可能な上限値に達する場合がある。
        /// 長期間稼働する可能性がある場合、この関数ではなく Clock クラスの利用を推奨する。
        static bool tryClock(TimeSpan& result, bool forceStdClock = false);

        /// @brief TimeSpan 値の符号を反転させた値を算出する。
        /// @param[in] span 演算対象。
        /// @return span の符号を反転させた値。
        static TimeSpan negate(const TimeSpan& span)
        {
            return fromMicroseconds(-span.value);
        }

        /// @brief TimeSpan 値の絶対値を算出する。
        /// @param[in] span 演算対象。
        /// @return span の絶対値。
        static TimeSpan abs(const TimeSpan& span)
        {
            return span.isMinus() ? negate(span) : span;
        }

        /// @brief 2つの TimeSpan 値を加算する。
        /// @param[in] span1 加算対象1。
        /// @param[in] span2 加算対象2。
        /// @return 加算結果値。
        /// @see tryAdd
        ///
        /// @exception Exception
        /// 演算結果値が表現可能範囲に収まらない場合。
        static TimeSpan add(const TimeSpan& span1, const TimeSpan& span2);

        /// @brief 2つの TimeSpan 値を加算する。
        /// @param[in] span1 加算対象1。
        /// @param[in] span2 加算対象2。
        /// @param[out] result 加算結果値の設定先。
        /// @retval true  加算できた場合。
        /// @retval false 演算結果値が表現可能範囲に収まらない場合。
        /// @see add
        static bool tryAdd(const TimeSpan& span1, const TimeSpan& span2, TimeSpan& result);

        /// @brief TimeSpan 値から別の TimeSpan 値を減算する。
        /// @param[in] span1 減算対象。
        /// @param[in] span2 減算量。
        /// @return 減算結果値。
        /// @see trySubtract
        ///
        /// @exception Exception
        /// 演算結果値が表現可能範囲に収まらない場合。
        static TimeSpan subtract(const TimeSpan& span1, const TimeSpan& span2);

        /// @brief TimeSpan 値から別の TimeSpan 値を減算する。
        /// @param[in] span1 減算対象。
        /// @param[in] span2 減算量。
        /// @param[out] result 減算結果値の設定先。
        /// @retval true  減算できた場合。
        /// @retval false 演算結果値が表現可能範囲に収まらない場合。
        /// @see subtract
        static bool trySubtract(
            const TimeSpan& span1,
            const TimeSpan& span2,
            TimeSpan& result);

        /// @brief TimeSpan 値に整数値を乗算する。
        /// @param[in] span 乗算対象。
        /// @param[in] value 乗算値。
        /// @return 乗算結果値。
        /// @see tryMultiply
        ///
        /// @exception Exception
        /// 演算結果値が表現可能範囲に収まらない場合。
        static TimeSpan multiply(const TimeSpan& span, value_type value);

        /// @brief TimeSpan 値に整数値を乗算する。
        /// @param[in] span 乗算対象。
        /// @param[in] value 乗算値。
        /// @param[out] result 乗算結果値の設定先。
        /// @retval true  乗算できた場合。
        /// @retval false 演算結果値が表現可能範囲に収まらない場合。
        /// @see multiply
        static bool tryMultiply(const TimeSpan& span, value_type value, TimeSpan& result);

        /// @brief TimeSpan 値を整数値で除算する。
        /// @param[in] span 除算対象。
        /// @param[in] value 除算値。
        /// @return 除算結果値。
        ///
        /// @exception Exception
        /// 引数 value に 0 を指定した場合。
        static TimeSpan divide(const TimeSpan& span, value_type value);

        /// @brief マイクロ秒数値に変換する。
        /// @return マイクロ秒数値。
        value_type toMicroseconds() const
        {
            return value;
        }

        /// @brief ミリ秒数値に変換する。
        /// @return ミリ秒数値。ミリ秒数未満の値は切り捨てられる。
        value_type toMilliseconds() const
        {
            return value / static_cast<value_type>(1000);
        }

        /// @brief 秒数値に変換する。
        /// @return 秒数値。秒数未満の値は切り捨てられる。
        value_type toSeconds() const
        {
            return value / (static_cast<value_type>(1000) * 1000);
        }

        /// @brief 分数値に変換する。
        /// @return 分数値。分数未満の値は切り捨てられる。
        value_type toMinutes() const
        {
            return value / (static_cast<value_type>(1000) * 1000 * 60);
        }

        /// @brief 時数値に変換する。
        /// @return 時数値。時数未満の値は切り捨てられる。
        value_type toHours() const
        {
            return value / (static_cast<value_type>(1000) * 1000 * 60 * 60);
        }

        /// @brief 日数値に変換する。
        /// @return 日数値。日数未満の値は切り捨てられる。
        value_type toDays() const
        {
            return value / (static_cast<value_type>(1000) * 1000 * 60 * 60 * 24);
        }

        /// @brief 時間間隔値に変換する。
        /// @return 時間間隔値。
        std::chrono::microseconds toDuration() const
        {
            return std::chrono::microseconds(toMicroseconds());
        }

        /// @brief マイクロ秒数パート値を取得する。
        /// @return マイクロ秒数パート値。常に正数を返す。
        value_type getPartOfMicroseconds() const
        {
            return abs(*this).toMicroseconds() % 1000;
        }

        /// @brief ミリ秒数パート値を取得する。
        /// @return ミリ秒数パート値。常に正数を返す。
        value_type getPartOfMilliseconds() const
        {
            return abs(*this).toMilliseconds() % 1000;
        }

        /// @brief 秒数パート値を取得する。
        /// @return 秒数パート値。常に正数を返す。
        value_type getPartOfSeconds() const
        {
            return abs(*this).toSeconds() % 60;
        }

        /// @brief 分数パート値を取得する。
        /// @return 分数パート値。常に正数を返す。
        value_type getPartOfMinutes() const
        {
            return abs(*this).toMinutes() % 60;
        }

        /// @brief 時数パート値を取得する。
        /// @return 時数パート値。常に正数を返す。
        value_type getPartOfHours() const
        {
            return abs(*this).toHours() % 24;
        }

        /// @brief 日数パート値を取得する。
        /// @return 日数パート値。常に正数を返す。
        value_type getPartOfDays() const
        {
            return abs(*this).toDays();
        }

        /// @brief ゼロ値であるか否かを取得する。
        /// @retval true  内部値が 0 である場合。
        /// @retval false 内部値が 0 以外である場合。
        bool isZero() const
        {
            return (value == 0);
        }

        /// @brief 負数であるか否かを取得する。
        /// @retval true  内部値が 0 未満である場合。
        /// @retval false 内部値が 0 以上である場合。
        bool isMinus() const
        {
            return (value < 0);
        }

        /// @brief パート分割された時間間隔値を取得する。
        /// @param[out] days         日数パートの設定先。取得しないならば nullptr 。
        /// @param[out] hours        時数パートの設定先。取得しないならば nullptr 。
        /// @param[out] minutes      分数パートの設定先。取得しないならば nullptr 。
        /// @param[out] seconds      秒数パートの設定先。取得しないならば nullptr 。
        /// @param[out] milliseconds ミリ秒数パートの設定先。取得しないならば nullptr 。
        /// @param[out] microseconds マイクロ秒数パートの設定先。取得しないならば nullptr 。
        ///
        /// 特定のパートに nullptr を指定した場合、非 nullptr を指定したパートに
        /// nullptr を指定したパート分の値も加算される。
        ///
        /// 例えば引数 hours (時数パート)と引数 seconds (秒数パート)のみに非 nullptr を
        /// 指定した場合、次のように格納される。
        ///
        /// - ミリ秒数パート以下の値は切り捨てられる。
        /// - 引数 seconds のポインタ先には 0 以上 3599 以下の値が格納される。
        ///   即ち分数パート値を 60 倍した値が本来の秒数パート値に加算される。
        /// - 引数 hours のポインタ先には時数以上のすべての値の合算値が格納される。
        ///   即ち日数パート値を 24 倍した値が本来の時数パート値に加算される。
        void toParts(
            value_type* days,
            value_type* hours = nullptr,
            value_type* minutes = nullptr,
            value_type* seconds = nullptr,
            value_type* milliseconds = nullptr,
            value_type* microseconds = nullptr) const;

        /// @brief 文字列表現値を作成する。
        /// @param[in] format フォーマット文字列。
        /// @return 文字列表現値。
        ///
        /// 引数 format には下記のフォーマット文字列と任意の文字列の組み合わせを指定する。
        /// 大文字と小文字は区別されることに注意。
        ///
        /// - "%d" -- 日数パート値。
        /// - "%h" -- 時数パート値。
        /// - "%m" -- 分数パート値。
        /// - "%s" -- 秒数パート値。
        /// - "%i" -- ミリ秒数パート値。
        /// - "%u" -- マイクロ秒数パート値。
        /// - "%+" -- 負数の場合は文字 '-' 、正数あるいはゼロ値の場合は文字 '+' 。
        /// - "%-" -- 負数の場合は文字 '-' 、正数あるいはゼロ値の場合は空文字列。
        /// - "%v" -- value 値そのもの。負数の場合は頭に '-' が付く。
        /// - "%V" -- value の絶対値。
        /// - "%%" -- 文字 '%' 。
        ///
        /// 数値を表すフォーマット文字列は、1文字目の '%' の直後に幅指定を行う事ができる。
        /// 幅指定は「数字」か、「文字 '0' + 数字」の形式で指定でき、例えば次のようになる。
        ///
        /// - "%4s"  -- 最小4文字幅になるよう先頭に空白文字が付与される。
        /// - "%04s" -- 最小4文字幅になるよう先頭に文字 '0' が付与される。
        ///
        /// フォーマット文字列中に特定のパートが存在しない場合、
        /// 存在するパートに存在しないパート分の値も加算して文字列化される。
        /// "%+", "%-", "%v", "%V", "%%" はこの処理には関与しない。
        ///
        /// 例えば "%h%s" のように時数パートと秒数パートのみから構成される
        /// フォーマット文字列を指定した場合、次のように文字列化される。
        ///
        /// - ミリ秒数パート以下の値は挿入されない。
        /// - "%s" 部分には 0 以上 3599 以下の値が文字列化されて挿入される。
        ///   即ち分数パート値を 60 倍した値が本来の秒数パート値に加算される。
        ///   これはフォーマット文字列中に分数パートが存在しないためである。
        /// - "%h" 部分には時数以上のすべての値の合算値が文字列化されて挿入される。
        ///   即ち日数パート値を 24 倍した値が本来の時数パート値に加算される。
        ///   これはフォーマット文字列中に日数パートが存在しないためである。
        ///
        /// 引数 format に nullptr を指定した場合、 "%v" を指定したものとして扱う。
        std::wstring toString(const wchar_t* format = nullptr) const;

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

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

/// @}

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

    /// @brief 単項プラス演算子のオーバロード。
    /// @param[in] u 単項値。
    /// @return u の値そのもの。
    /// @relatesalso TimeSpan
    inline TimeSpan operator+(const TimeSpan& u)
    {
        return u;
    }

    /// @brief 単項マイナス演算子のオーバロード。
    /// @param[in] u 単項値。
    /// @return u の符号を反転させた値。
    /// @relatesalso TimeSpan
    inline TimeSpan operator-(const TimeSpan& u)
    {
        return TimeSpan::negate(u);
    }

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

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

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

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

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

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

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

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

#endif // AMDAEMON_UTIL_TIMESPAN_H