Time.h

Go to the documentation of this file.

/**--------------------------------------------------------------------------------------------
Copyright (c) 2019, NDEVR LLC
tyler.parke@ndevr.org
  __    __   ____     _____ __     __  _______
 |  \  |  | |  __ \  |  ___|\ \   / / |   __  \
 |   \ |  | | |  \ \ | |___  \ \ / /  |  |__)  |
 |  . \|  | | |__/ / | |___   \ V /   |   _   /
 |  |\    |_|_____/__|_____|___\_/____|  | \  \
 |__| \__________________________________|  \__\
 
Subject to the terms of the Enterprise+ Agreement, NDEVR hereby grants 
Licensee a limited, non-exclusive, non-transferable, royalty-free license 
(without the right to sublicense) to use the API solely for the purpose of 
Licensee's internal development efforts to develop applications for which 
the API was provided.
 
The above copyright notice and this permission notice shall be included in all 
copies or substantial portions of the Software.
 
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE
FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
 
Library: Base
File: Time
Included in API: True
Author(s): Tyler Parke
 *-----------------------------------------------------------------------------------------**/
#pragma once
#include "DLLInfo.h"
#include <NDEVR/BaseValues.h>
#include <NDEVR/ObjectInfo.h>
#include <functional>
struct tm;
namespace NDEVR
{
    class String;
    class Exception;
    /**
     * @class Time
     * @brief Represents a timestamp with utilities for manipulation and conversion.
     *
     * The `Time` class provides a framework for working with timestamps. It supports
     * various time operations such as getting and setting components (year, month,
     * day, hour, etc.), formatting, and conversions between time zones.
     *
     * This class is designed for flexibility, making it suitable for a variety of
     * applications, including scheduling, logging, and time-based calculations.
     */
    class Time
    {
    public:
        /**
         * @enum Months
         * @brief Enumerates the months of the year.
         *
         * Values range from `JANUARY` (1) to `DECEMBER` (12) for easy reference
         * in operations involving months.
         */
        enum Months
        {
              JANUARY = 1
            , FEBRUARY
            , MARCH
            , APRIL
            , MAY
            , JUNE
            , JULY
            , AUGUST
            , SEPTEMBER
            , OCTOBER
            , NOVEMBER
            , DECEMBER
        };
        // Static Variables
        //------------------------
    public:
        static constexpr uint08 NANOSECOND = 1;
        static constexpr uint08 MICROSECOND = 1000 * NANOSECOND;
        static constexpr uint08 MILLISECOND = 1000000;
        static constexpr uint08 SECOND = 1000000000;
        static constexpr uint08 MINUTE = SECOND * 60;
        static constexpr uint08 HOUR = MINUTE * 60;
        static constexpr uint08 DAY = HOUR * 24;
        static constexpr uint08 WEEK = DAY * 7;
        static constexpr uint08 YEAR = DAY * 365;
        static constexpr uint08 LEAP_YEAR = DAY * 366;
        // Member Functions
        //------------------------
    public:
        /**
         * @brief Default constructor initializing an invalid timestamp.
         */
        constexpr Time()
            : m_time(Constant<uint08>::NaN)
        {}
        /**
         * @brief Constructor initializing the timestamp with a specific value.
         * @param time Timestamp in nanoseconds.
         */
        constexpr explicit Time(const uint08& time)
            : m_time(time)
        {}
        /**
         * @brief Constructs a `Time` object using date and time components.
         * @param year Year component.
         * @param month Month component (1-12).
         * @param day Day of the month.
         * @param hour Hour of the day (default is 0).
         * @param minute Minute of the hour (default is 0).
         * @param second Second of the minute (default is 0).
         * @param is_local_time Indicates whether the time is local or UTC.
         */
        NDEVR_BASE_API Time(uint04 year, uint04 month, uint04 day, uint04 hour = 0, uint04 minute = 0, uint04 second = 0, bool is_local_time = false);
        /**
         * @brief Constructs a Time from a string representation.
         * https://ndevr.org/time-patterns/
         * @param get_local_time Whether to convert to local time.
         * @param format_string The format for the string representation.
         * @return A formatted string representing the timestamp.
         */
        NDEVR_BASE_API Time(const String& time_string, bool is_local_time, const String& format_string);
        NDEVR_BASE_API Time(const char* time_string, bool is_local_time, const String& format_string);
        /**
         * @brief Sets the internal timestamp.
         * @param time Timestamp in nanoseconds.
         */
        NDEVR_BASE_API void setTime(const uint08& time);
        /**
         * @brief Converts the timestamp to a string representation.
         * https://ndevr.org/time-patterns/
         * @param get_local_time Whether to convert to local time.
         * @param format_string The format for the string representation.
         * @return A formatted string representing the timestamp.
         */
        NDEVR_BASE_API String toString(bool get_local_time, const String& format_string) const;
        /**
         * @brief Converts the timestamp from a string representation. 
         * https://ndevr.org/time-patterns/
         * @param get_local_time Whether to convert to local time.
         * @param format_string The format for the string representation.
         * @return A formatted string representing the timestamp.
         */
        NDEVR_BASE_API void setTimeFromString(const String& time_string, bool is_local_time, const String& format_string);
        NDEVR_BASE_API void setHour(const uint01& hour, bool is_local_time);
        NDEVR_BASE_API void setMinute(const uint01& minute, bool is_local_time);
        NDEVR_BASE_API void setSecond(const uint01& second, bool is_local_time);
        NDEVR_BASE_API void setMillisecond(const uint02& millisecond);
        NDEVR_BASE_API void setYear(const uint02& year, bool is_local_time);
        NDEVR_BASE_API void setMonth(const uint01& month, bool is_local_time);
        NDEVR_BASE_API void setMonthDay(const uint01& day, bool is_local_time);
        NDEVR_BASE_API void setDayOfYear(const uint02& day, bool is_local_time);
        NDEVR_BASE_API fltp08 julianDay(bool is_local_time) const;
        /**
         * @brief Retrieves the year component of the timestamp.
         * @param is_local_time Indicates whether the time is local or UTC.
         * @return Year as a 2-byte unsigned integer.
         */
        NDEVR_BASE_API uint02 year(bool is_local_time) const;
        /**
         * @brief Retrieves the month component of the timestamp.
         * @param is_local_time Indicates whether the time is local or UTC.
         * @return Month as a 2-byte unsigned integer.
         */
        NDEVR_BASE_API uint02 month(bool is_local_time) const;
        NDEVR_BASE_API uint02 monthDay(bool is_local_time) const;
        NDEVR_BASE_API uint02 yearDay(bool is_local_time) const;
 
        /**
         * @brief Retrieves the hour component of the timestamp.
         * @param is_local_time Indicates whether the time is local or UTC.
         * @return Hour as a 1-byte unsigned integer.
         */
        NDEVR_BASE_API uint01 hour(bool is_local_time) const;
        NDEVR_BASE_API uint01 minute(bool is_local_time) const;
        NDEVR_BASE_API uint01 second(bool is_local_time) const;
        NDEVR_BASE_API uint02 millisecond() const;
        /**
         * @brief Gets the timestamp in nanoseconds.
         * @return Timestamp in nanoseconds.
         */
        [[nodiscard]] constexpr uint08 getNanoSeconds() const
        {
            return m_time;
        }
        /**
         * @brief Gets the timestamp in milliseconds.
         * @return Timestamp in milliseconds.
         */
        [[nodiscard]] uint08 getMilliseconds() const
        {
            return m_time / MILLISECOND;
        }
        /**
         * @brief Converts the timestamp to a UNIX time representation.
         * @return UNIX timestamp in nanoseconds.
         */
        NDEVR_BASE_API uint08 unixTime() const;
 
        //Used for TimeSpan calculations
        [[nodiscard]] NDEVR_BASE_API uint08 leapYearConstant() const;
        [[nodiscard]] NDEVR_BASE_API uint08 daysConstant() const;
        [[nodiscard]] NDEVR_BASE_API uint08 monthsConstant() const;
        
        inline bool operator==(const Time& time) const
        {
            return m_time == time.m_time;
        }
        inline bool operator!=(const Time& time) const
        {
            return m_time != time.m_time;
        }
        inline bool operator<(const Time& time) const
        {
            return m_time < time.m_time;
        }
        inline bool operator<=(const Time& time) const
        {
            return m_time <= time.m_time;
        }
        inline bool operator>(const Time& time) const
        {
            return m_time > time.m_time;
        }
        inline bool operator>=(const Time& time) const
        {
            return m_time >= time.m_time;
        }
    private:
        uint08 m_time;///< Internal representation of the timestamp in nanoseconds.
    public:
        /**
         * @brief Retrieves the current system time.
         * @return The current system time as a `Time` object.
         */
        NDEVR_BASE_API static Time SystemTime();
        /**
         * @brief Sets the application's system clock to a specified `Time`.
         * Note: Does not affect OS Time
         * @param time The `Time` object to set as the system time.
         */
        static NDEVR_BASE_API void SetSystemTime(const Time& time);
        NDEVR_BASE_API static void SetMakeUTCFromLocalFunction(const std::function<uint08(const tm& tm)>& function);
        NDEVR_BASE_API static void SetMakeLocalFromUTCFunction(const std::function<uint08(const tm& tm)>& function);
        NDEVR_BASE_API static void SetClockErrorCallback(const std::function<void(const Exception& error)>& function);
    private:
        static tm getTime(sint08 time, bool use_local_time);
        static uint08 MakeGMTFromLocal(const tm& time);
        static uint08 MakeLocalFromGMT(const tm& time);
    private:
        static constexpr uint02 s_epoch_year = 1970;
        static constexpr uint02 s_tm_year_base = 1900;
        static std::function<uint08(const tm& tm)> s_make_utc_from_local;
        static std::function<uint08(const tm& tm)> s_make_local_from_utc;
        static std::function<void(const Exception& error)> s_clock_error_callback;
        static sint08 s_nano_second_offset;
    };
 
 
    /**--------------------------------------------------------------------------------------------------
    Struct: ObjectInfo<Time>
 
    Information about the object.
 
    Author: Tyler Parke
 
    Date: 2020-09-13
     *-----------------------------------------------------------------------------------------------**/
    template<>
    struct ObjectInfo<Time, false, false>
    {
        static const uint01 Dimensions = 0;
        static const bool Vector = false;
        static const bool Primitive = true;
        static const bool Pointer = false;
        static const bool Unsigned = false;
        static const bool Float = true;
        static const bool Integer = false;
        static const bool Number = true;
        static const bool String = false;
        static const bool Color = false;
        static const bool Buffer = false;
        static const bool Boolean = false;
        static constexpr ObjectInfo<Time, false, false> VectorSub() { return ObjectInfo<Time, false, false>(); }
    };
 
    static_assert(sizeof(Time(0)) == 8, "Bad time allocation size");
 
    template<> constexpr const Time Constant<Time>::NaN = Time(18446744073709551615ULL);
    template<> constexpr const Time Constant<Time>::Max = Time(18446744073709551614ULL);
    template<> constexpr const Time Constant<Time>::Min = Time(0);
}