Time.h

Go to the documentation of this file.

// Copyright Onix Solutions Limited [OnixS]. All rights reserved.
//
// This software owned by Onix Solutions Limited [OnixS] and is protected by copyright law
// and international copyright treaties.
//
// Access to and use of the software is governed by the terms of the applicable OnixS Software
// Services Agreement (the Agreement) and Customer end user license agreements granting
// a non-assignable, non-transferable and non-exclusive license to use the software
// for it's own data processing purposes under the terms defined in the Agreement.
//
// Except as otherwise granted within the terms of the Agreement, copying or reproduction of any
// part of this source code or associated reference material to any other location for further
// reproduction or redistribution, and any amendments to this copyright notice, are expressly
// prohibited.
//
// Any reproduction or redistribution for sale or hiring of the Software not in accordance with
// the terms of the Agreement is a violation of copyright law.
//

#pragma once

#include "OnixS/CME/DropCopy/Export.h"
#include "OnixS/CME/DropCopy/Numeric.h"

#include <string>

namespace OnixS { namespace CME { namespace DropCopy {

/// Time span formats supported.
struct ONIXS_CME_DROP_COPY_EXPORT TimeSpanFormats
{
    enum Enum
    {
        /// HH:MM:SS.
        HHMMSS,

        /// HH:MM:SS.sss.
        HHMMSSmsec,

        /// HH:MM:SS.sssssssss.
        SDHHMMSSnsec
    };
};

/// Time span format.
typedef TimeSpanFormats::Enum TimeSpanFormat;

/// Subseconds formats supported.
struct ONIXS_CME_DROP_COPY_EXPORT Subseconds
{
    enum Enum
    {
        /// Milliseconds
        Milli,

        /// Microseconds
        Micro,

        /// Nanoseconds
        Nano
    };
};

/// Time span format.
typedef Subseconds::Enum Subsecond;

/// Represents time interval. Used primarily to
/// present time-only stamps and to measure time
/// intervals between two timestamps.
class ONIXS_CME_DROP_COPY_EXPORT TimeSpan
{
public:
    /// Initializes zero span.
    TimeSpan();

    /// Initializes with given set of values.
    /// Input parameters are treated as quantities,
    /// but not as a time stamp. Therefore, there's
    /// no requirement to fit in a certain range like
    /// hours must fit into [0, 24) range. After
    /// initialization time span will be normalized.
    TimeSpan(Int32 hours, Int32 minutes, Int32 seconds, Int32 nanoseconds = 0);

    /// Initializes with given set of values.
    /// Input parameters are treated as quantities,
    /// but not as a time stamp. Therefore, there's
    /// no requirement to fit in a certain range like
    /// hours must fit into [0, 24) range. After
    /// initialization time span will be normalized.
    TimeSpan(Int32 days, Int32 hours, Int32 minutes, Int32 seconds, Int32 nanoseconds);

    /// Initializes time interval from total number
    /// seconds and its fractional (nanosecond) part.
    TimeSpan(Int64 totalSeconds, Int32 nanoseconds);

    /// Initializes as clone of other instance.
    TimeSpan(const TimeSpan& other);

    /// Whole number of seconds in time interval.
    Int64 totalSeconds() const;

    /// Whole number of subseconds in time interval.
    Int64 totalSubseconds(Subsecond subsecondType) const;

    /// Days component of time interval.
    /// Whole number of days in time interval.
    Int32 days() const;

    /// Hours component of time interval.
    /// Values are in range from -23 through 23.
    Int32 hours() const;

    /// Minutes component of time interval.
    /// Values are in range from -59 through 59.
    Int32 minutes() const;

    /// Seconds component of time interval.
    /// Values are in range from -59 through 59.
    Int32 seconds() const;

    /// Milliseconds component of time interval.
    /// Values are in range from -999 through 999.
    Int32 milliseconds() const;

    /// Microseconds component of time interval.
    /// Values are in range from -999999 through 999999.
    Int32 microseconds() const;

    /// Nanoseconds component of time interval.
    /// Values are in range from -999999999 through 999999999.
    Int32 nanoseconds() const;

    /// Compares with other instance for equality.
    bool operator==(const TimeSpan& other) const;

    /// Compares with other instance for in-equality.
    bool operator!=(const TimeSpan& other) const;

    /// Checks whether time interval less than other one.
    bool operator<(const TimeSpan& other) const;

    /// Checks whether time interval greater than other one.
    bool operator>(const TimeSpan& other) const;

    /// Adds time interval to current one.
    TimeSpan& operator+=(const TimeSpan& other);

    /// Subtracts time interval from current one.
    TimeSpan& operator-=(const TimeSpan& other);

    /// Re-assigns time interval from other one.
    TimeSpan& operator=(const TimeSpan& other);

    /// Serializes time stamp into text presentation
    /// using specified time-span presentation format.
    void toString(std::string& str, TimeSpanFormat format = TimeSpanFormats::SDHHMMSSnsec) const;

    /// Serializes time stamp into text presentation
    /// using specified time-span presentation format.
    std::string toString(TimeSpanFormat format = TimeSpanFormats::SDHHMMSSnsec) const;

    /// De-serializes time interval from its text presentation.
    static TimeSpan deserialize(const std::string& str);

    /// Time interval of zero length.
    static const TimeSpan Zero;

private:
    Int64 seconds_;
    Int32 nanoseconds_;
};

inline Int64 TimeSpan::totalSeconds() const
{
    return seconds_;
}

inline Int32 TimeSpan::nanoseconds() const
{
    return nanoseconds_;
}

inline std::string TimeSpan::toString(TimeSpanFormat format) const
{
    std::string str;
    toString(str, format);
    return str;
}

/// Identifies months in year.
struct ONIXS_CME_DROP_COPY_EXPORT Months
{
    enum Enum
    {
        Bad,

        January,
        February,
        March,
        April,
        May,
        June,
        July,
        August,
        September,
        October,
        November,
        December,

        Count = December
    };

    /// Deserializes value from text presentation.
    static Enum deserialize(const char*);

    /// Returns text presentation for given value.
    static const char* toString(Enum);
};

/// Identifies months in year.
typedef Months::Enum Month;

/// Identifies day within week.
struct ONIXS_CME_DROP_COPY_EXPORT DaysOfWeek
{
    enum Enum
    {
        Sunday,
        Monday,
        Tuesday,
        Wednesday,
        Thursday,
        Friday,
        Saturday,

        Total
    };

    /// Deserializes value from text presentation.
    static Enum deserialize(const char*);

    /// Returns text presentation for given value.
    static const char* toString(Enum);
};

/// Identifies days in week.
typedef DaysOfWeek::Enum DayOfWeek;

/// Identifies week number within month.
struct ONIXS_CME_DROP_COPY_EXPORT WeekCodes
{
    enum Enum
    {
        Invalid,
        Week1,
        Week2,
        Week3,
        Week4,
        Week5,

        LastWeek = Week5
    };

    /// Deserializes value from text presentation.
    static Enum deserialize(const char*);

    /// Returns text presentation for given value.
    static const char* toString(Enum);
};

/// Identifies week number within month.
typedef WeekCodes::Enum WeekCode;

/// Represents month-year pair.
/// Year must fit into [0001, 9999] range.
/// Month must fit into [01, 12] range.
class ONIXS_CME_DROP_COPY_EXPORT YearMonth
{
public:
    /// Initializes instance as Jan, 0001.
    YearMonth();

    /// Initializes instance with given values according
    /// YYYYMM (year/month) format.
    /// Input parameters are checked for validness.
    /// \throw exception if input parameters do
    /// not fit into a valid range.
    YearMonth(UInt32 year, Month month);

    /// Initializes instance with given values according
    /// YYYYMMDD (year/month/day) format.
    /// Input parameters are checked for validness.
    /// \throw exception if input parameters do
    /// not fit into a valid range.
    YearMonth(UInt32 year, Month month, UInt32 day);

    /// Initializes instance with given values according
    /// YYYYMMWW (year/month/week) format.
    /// Input parameters are checked for validness.
    /// \throw exception if input parameters do
    /// not fit into a valid range.
    YearMonth(UInt32 year, Month month, WeekCode week);

    /// Initializes as copy of other instance.
    YearMonth(const YearMonth& other);

    /// Year component.
    /// Valid range of values is [0001, 9999].
    UInt32 year() const
    {
        return year_;
    }

    /// Month component.
    /// Valid range of values is [01, 12].
    Month month() const
    {
        return month_;
    }

    /// Day component.
    /// Valid range of values is [01, 31].
    UInt32 day() const
    {
        return day_;
    }

    /// Week component.
    /// Valid range of values is [1, 5].
    WeekCode week() const
    {
        return week_;
    }

    /// Checks that instance has valid day component.
    /// Note: it's not valid to have both valid day and week, only one of them allowed.
    bool hasDay() const
    {
        return day_ != 0;
    }

    /// Checks that instance has valid week component.
    /// Note: it's not valid to have both valid day and week, only one of them allowed.
    bool hasWeek() const
    {
        return week_ != WeekCodes::Invalid;
    }

    /// Compares with other instance for equality.
    bool operator==(const YearMonth&) const;

    /// Compares with other instance for inequality.
    bool operator!=(const YearMonth&) const;

    /// Checks whether this instance is less than other one.
    /// Note: when comparing objects with different date components,
    /// e.g. days vs weeks (but same year and month) following order is applied:
    /// YYYYMM < YYYYMMWW < YYYYMMDD
    bool operator<(const YearMonth& other) const;

    /// Checks whether this instance is greater than other one.
    /// Note: when comparing objects with different date components,
    /// e.g. days vs weeks (but same year and month) following order is applied:
    /// YYYYMMDD > YYYYMMWW > YYYYMM
    bool operator>(const YearMonth& other) const;

    // Re-initializes instance as copy of other one.
    YearMonth& operator=(const YearMonth& other);

    /// Serializes into text (YYYYMM/YYYYMMDD/YYYYMMWW) presentation.
    std::string toString() const;

    /// Serializes into text (YYYYMM/YYYYMMDD/YYYYMMWW) presentation.
    void toString(std::string&) const;

    /// De-serializes instance from its string
    /// presentation (YYYYMM/YYYYMMDD/YYYYMMWW) as it's used by CME Globex.
    static YearMonth deserialize(const StringRef&);

private:
    // Year component.
    UInt32 year_;

    // Month component.
    Month month_;

    // Day component.
    UInt32 day_;

    // Week component.
    WeekCode week_;
};

inline std::string YearMonth::toString() const
{
    std::string str;
    toString(str);
    return str;
}

/// Collection of timestamp formats supported.
struct ONIXS_CME_DROP_COPY_EXPORT TimestampFormats
{
    enum Enum
    {
        /// YYYYMMDD.
        YYYYMMDD,

        /// YYYYMMDD-HH:MM:SS.
        YYYYMMDDHHMMSS,

        /// YYYYMMDD-HH:MM:SS.sss.
        YYYYMMDDHHMMSSmsec,

        /// YYYYMMDD-HH:MM:SS.sssssssss.
        YYYYMMDDHHMMSSnsec
    };
};

/// Timestamp format.
typedef TimestampFormats::Enum TimestampFormat;

/// Since epoch time units supported.
struct ONIXS_CME_DROP_COPY_EXPORT SinceEpochUnits
{
    enum Enum
    {
        Nanoseconds,
        Days
    };
};

/// Since epoch units format.
typedef SinceEpochUnits::Enum SinceEpochUnit;

/// Represents timestamp without time-zone information.
class ONIXS_CME_DROP_COPY_EXPORT Timestamp
{
public:
    /// Initializes as Jan 1, 1970, 00:00:00.
    Timestamp();

    /// Initializes as date with zero time component.
    ///
    /// Input parameters are validated, therefore
    /// constructor throws exception if input values
    /// do not fit into their valid ranges.
    Timestamp(UInt32 year, Month month, UInt32 day);

    /// Explicit timestamp initialization.
    ///
    /// Input parameters are validated, therefore
    /// constructor throws exception if input values
    /// do not fit into their valid ranges.
    Timestamp(
        UInt32 year,
        Month month,
        UInt32 day,
        UInt32 hour,
        UInt32 minute,
        UInt32 second,
        UInt32 nanosecond
    );

    /// Initializes as copy of other instance.
    Timestamp(const Timestamp& other);

    /// Year component of timestamp.
    UInt32 year() const;

    /// Month component of timestamp.
    Month month() const;

    /// Day component of timestamp.
    UInt32 day() const;

    /// Hour component of timestamp.
    UInt32 hour() const;

    /// Minute component of timestamp.
    UInt32 minute() const;

    /// Second component of timestamp.
    UInt32 second() const;

    /// Millisecond component of timestamp.
    UInt32 millisecond() const;

    /// Microsecond component of timestamp.
    UInt32 microsecond() const;

    /// Nanosecond component of timestamp.
    UInt32 nanosecond() const;

    /// Returns timestamp without time part.
    Timestamp date() const;

    /// Return time part of timestamp.
    TimeSpan time() const;

    /// Returns day of the week.
    DayOfWeek dayOfWeek() const;

    /// Compares with other instance for equality.
    bool operator==(const Timestamp& other) const;

    /// Compares with other instance for inequality.
    bool operator!=(const Timestamp& other) const;

    /// Checks whether timestamp is less than other one.
    bool operator<(const Timestamp& other) const;

    /// Checks whether timestamp is greater than other one.
    bool operator>(const Timestamp& other) const;

    /// Adds time interval to given timestamp.
    Timestamp& operator+=(const TimeSpan& span);

    /// Subtracts time interval from given timestamp.
    Timestamp& operator-=(const TimeSpan& span);

    /// Re-initializes as copy of other timestamp.
    Timestamp& operator=(const Timestamp& other);

    /// Return timestamp that is current date
    /// and time expressed as local time.
    static Timestamp now();

    /// Return timestamp that is current date
    /// and time expressed as local time.
    static void now(Timestamp&);

    /// Return timestamp that is current date
    /// and time expressed as UTC time.
    static Timestamp utcNow();

    /// Return timestamp that is current date
    /// and time expressed as UTC time.
    static void utcNow(Timestamp&);

    /// Returns text presentation of timestamp
    /// using specified presentation format.
    std::string toString(TimestampFormat format = TimestampFormats::YYYYMMDDHHMMSSnsec) const;

    /// Returns text presentation of timestamp
    /// using specified presentation format.
    void
    toString(std::string& str, TimestampFormat format = TimestampFormats::YYYYMMDDHHMMSSnsec) const;

    /// De-serializes timestamp from text presentation.
    static Timestamp deserialize(const StringRef&);

    /// Converts timestamp from its numeric presentation
    /// (Unix timestamp in nanoseconds or days since 01-01-1970 UTC)
    /// as it's used by the CME Globex.
    static Timestamp fromUnixTimestamp(UInt64 sinceEpoch, SinceEpochUnit unit);

    /// Converts timestamp into its numeric presentation
    /// (Unix timestamp in nanoseconds or days since 01-01-1970 UTC)
    /// as it's used by the CME Globex.
    UInt64 toUnixTimestamp(SinceEpochUnit unit) const;

    /// Returns the maximal possible timestamp (year 2554)
    static Timestamp maxTimestamp();

private:
    friend ONIXS_CME_DROP_COPY_EXPORT TimeSpan
    operator-(const Timestamp& left, const Timestamp& right);

    /// Initializes from time interval since the Unix Epoch
    /// (in nanoseconds since 01-01-1970 UTC).
    Timestamp(UInt64);

    /// Time interval since the Unix Epoch
    /// (nanoseconds since 01-01-1970 UTC).
    UInt64 sinceEpoch_;
};

inline std::string Timestamp::toString(TimestampFormat format) const
{
    std::string str;
    toString(str, format);
    return str;
}

/// Calculates time interval between two timestamps.
ONIXS_CME_DROP_COPY_EXPORT TimeSpan operator-(const Timestamp& left, const Timestamp& right);

}}}