Time.h

Go to the documentation of this file.

/*
 * Copyright (c) Onix Solutions Limited. All rights reserved.
 *
 * This software owned by Onix Solutions Limited 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 "Export.h"

#include <iosfwd>
#include <string>

namespace OnixS { namespace ICE { namespace iMpact { namespace MarketData {

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

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

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

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

/// Represents time interval. Used primarily to
/// present time-only stamps and to measure time
/// intervals between two timestamps.
class ONIXS_ICEMDH_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(int hours, int minutes, int seconds, int 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(int days, int hours, int minutes, int seconds, int nanoseconds);

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

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

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

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

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

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

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

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

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

    /// Nanoseconds component of time interval.
    /// Values are in range from -999999999 through 999999999.
    int 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);

    /// De-serializes time-span from presentation as it's used by the ICE.
    static TimeSpan deserialize(unsigned long long presentation, TimeSpanFormat format);

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

private:
    long long seconds_;
    int nanoseconds_;
};

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

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

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

    toString(str, format);

    return str;
}

/// Make it printable using C++ I/O streams.
ONIXS_ICEMDH_EXPORT std::ostream& operator<<(std::ostream&, const TimeSpan&);

/// Identifies months in year.
struct ONIXS_ICEMDH_EXPORT Months
{
    enum Enum
    {
        Undefined,

        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_ICEMDH_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 day within week.
typedef DaysOfWeek::Enum DayOfWeek;

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

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

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

    /// Year component.
    /// Valid range of values is [0001, 9999].
    unsigned int year() const;

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

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

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

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

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

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

    /// De-serializes instance from its numeric
    /// presentation as it's used by ICE.
    static YearMonth deserialize(unsigned long long);

protected:
    /// Suppresses verification.
    struct NoVerify {};

    /// Initializes instance
    /// without verifying input.
    YearMonth(unsigned int, Month, const NoVerify&);

private:
    unsigned int year_;
    Month month_;
};

inline unsigned int YearMonth::year() const
{
    return year_;
}

inline Month YearMonth::month() const
{
    return month_;
}

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

    toString(str);

    return str;
}

/// Make it printable using C++ I/O streams.
ONIXS_ICEMDH_EXPORT std::ostream& operator<<(std::ostream&, const YearMonth&);

/// Represents date without time component.
class ONIXS_ICEMDH_EXPORT Date : public YearMonth
{
public:
    /// Initializes as Jan 1, 0001.
    Date();

    /// Explicit initialization.
    ///
    /// \throw exception if input parameters
    /// do not form valid date.
    Date(unsigned int year, Month month, unsigned int day);

    /// Initializes as copy of other date.
    Date(const Date& other);

    /// Day component of date.
    /// Valid range of values is [01, 31].
    unsigned int day() const;

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

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

    /// Checks whether given date is less than other one.
    bool operator <(const Date& other) const;

    /// Checks whether given date is greater than other one.
    bool operator >(const Date& other) const;

    /// Adds time interval to the date.
    Date& operator +=(TimeSpan& span);

    /// Subtracts time interval from the date.
    Date& operator -=(TimeSpan& span);

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

    /// Serializes date into YYYYMMDD presentation.
    std::string toString() const;

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

    /// De-serializes date from its numeric
    /// presentation as it's used by ICE.
    static Date deserialize(unsigned long long);

private:
    unsigned int day_;

    /// Initializes without verifying input parameters.
    Date(unsigned int year, Month month, unsigned int day, const NoVerify&);
};

inline unsigned int Date::day() const
{
    return day_;
}

inline std::string Date::toString() const
{
    std::string str;

    toString(str);

    return str;
}

/// Calculates time interval between two given dates.
ONIXS_ICEMDH_EXPORT TimeSpan operator -(const Date& left, const Date& right);

/// Make it printable using C++ I/O streams.
ONIXS_ICEMDH_EXPORT std::ostream& operator<<(std::ostream&, const Date&);

/// Collection of timestamp formats supported.
struct ONIXS_ICEMDH_EXPORT TimestampFormats
{
    enum Enum
    {
        /// YYYYMMDD-HH:MM:SS.
        YYYYMMDDHHMMSS,

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

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

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

/// Represents timestamp without time-zone information.
class ONIXS_ICEMDH_EXPORT Timestamp
{
public:
    /// Initializes as Jan 1, 0001, 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(unsigned year, Month month, unsigned day);

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

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

    /// Initializes from time
    /// interval since the Epoch.
    Timestamp(const TimeSpan&);

    /// Year component of timestamp.
    unsigned int year() const;

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

    /// Day component of timestamp.
    unsigned int day() const;

    /// Hour component of timestamp.
    unsigned int hour() const;

    /// Minute component of timestamp.
    unsigned int minute() const;

    /// Second component of timestamp.
    unsigned int second() const;

    /// Millisecond component of timestamp.
    unsigned int millisecond() const;

    /// Microsecond component of timestamp.
    unsigned int microsecond() const;

    /// Nanosecond component of timestamp.
    unsigned int nanosecond() const;

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

    /// Returns date component of timestamp.
    void date(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 UTC time.
    static Timestamp utcNow();

    /// 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 std::string&);

    /// De-serializes timestamp from its numeric
    /// presentation as it's used by the ICE.
    static Timestamp deserialize(unsigned long long presentation, TimestampFormat format);

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

    /// Time interval since the Epoch.
    TimeSpan sinceEpoch_;
};

inline unsigned int Timestamp::hour() const
{
    return static_cast<unsigned int>(sinceEpoch_.hours());
}

inline unsigned int Timestamp::minute() const
{
    return static_cast<unsigned int>(sinceEpoch_.minutes());
}

inline unsigned int Timestamp::second() const
{
    return static_cast<unsigned int>(sinceEpoch_.seconds());
}

inline unsigned int Timestamp::millisecond() const
{
    return static_cast<unsigned int>(sinceEpoch_.milliseconds());
}

inline unsigned int Timestamp::microsecond() const
{
    return static_cast<unsigned int>(sinceEpoch_.microseconds());
}

inline unsigned int Timestamp::nanosecond() const
{
    return static_cast<unsigned int>(sinceEpoch_.nanoseconds());
}

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

    toString(str, format);

    return str;
}

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

/// Make it printable using C++ I/O streams.
ONIXS_ICEMDH_EXPORT std::ostream& operator<<(std::ostream&, const Timestamp&);

}}}}                                                        // namespace MarketData, iMpact, ICE, OnixS