DateTimeOffset.h

Go to the documentation of this file.

/*
 * MIT License
 *
 * Copyright (c) 2025 nfx
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * 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.
 */

 
#pragma once
 
#include <compare>
#include <cstdint>
#include <string>
#include <format>
#include <optional>
#include <string>
#include <string_view>
 
#include "DateTime.h"
#include "TimeSpan.h"
 
namespace nfx::time
{
    //=====================================================================
    // DateTimeOffset class
    //=====================================================================

    class DateTimeOffset final
    {
    public:
        //----------------------------------------------
        // Construction
        //----------------------------------------------

        inline constexpr DateTimeOffset() noexcept;

        inline constexpr DateTimeOffset( const DateTime& dateTime, const TimeSpan& offset ) noexcept;

        explicit DateTimeOffset( const DateTime& dateTime ) noexcept;

        inline constexpr DateTimeOffset( std::int64_t ticks, const TimeSpan& offset ) noexcept;

        inline DateTimeOffset(
            std::int32_t year, std::int32_t month, std::int32_t day, const TimeSpan& offset ) noexcept;

        inline DateTimeOffset(
            std::int32_t year,
            std::int32_t month,
            std::int32_t day,
            std::int32_t hour,
            std::int32_t minute,
            std::int32_t second,
            const TimeSpan& offset ) noexcept;

        inline DateTimeOffset(
            std::int32_t year,
            std::int32_t month,
            std::int32_t day,
            std::int32_t hour,
            std::int32_t minute,
            std::int32_t second,
            std::int32_t millisecond,
            const TimeSpan& offset ) noexcept;

        inline DateTimeOffset(
            std::int32_t year,
            std::int32_t month,
            std::int32_t day,
            std::int32_t hour,
            std::int32_t minute,
            std::int32_t second,
            std::int32_t millisecond,
            std::int32_t microsecond,
            const TimeSpan& offset ) noexcept;

        inline explicit DateTimeOffset( std::string_view iso8601String );

        inline explicit DateTimeOffset( const char* iso8601String );

        inline explicit DateTimeOffset( std::initializer_list<const char*> list );

        DateTimeOffset( const DateTimeOffset& ) = default;

        DateTimeOffset( DateTimeOffset&& ) noexcept = default;
 
        //----------------------------------------------
        // Destruction
        //----------------------------------------------

        ~DateTimeOffset() = default;
 
        //----------------------------------------------
        // Assignment
        //----------------------------------------------

        DateTimeOffset& operator=( const DateTimeOffset& ) = default;

        DateTimeOffset& operator=( DateTimeOffset&& ) noexcept = default;
 
        //----------------------------------------------
        // Comparison operators
        //----------------------------------------------

        inline constexpr std::strong_ordering operator<=>( const DateTimeOffset& other ) const noexcept;

        inline constexpr bool operator==( const DateTimeOffset& other ) const noexcept;
 
        //----------------------------------------------
        // Arithmetic operators
        //----------------------------------------------

        inline constexpr DateTimeOffset operator+( const TimeSpan& duration ) const noexcept;

        inline constexpr DateTimeOffset operator-( const TimeSpan& duration ) const noexcept;

        inline constexpr TimeSpan operator-( const DateTimeOffset& other ) const noexcept;

        inline constexpr DateTimeOffset& operator+=( const TimeSpan& duration ) noexcept;

        inline constexpr DateTimeOffset& operator-=( const TimeSpan& duration ) noexcept;
 
        //----------------------------------------------
        // Property accessors
        //----------------------------------------------

        [[nodiscard]] inline constexpr const DateTime& dateTime() const noexcept;

        [[nodiscard]] inline constexpr const TimeSpan& offset() const noexcept;

        [[nodiscard]] DateTime utcDateTime() const noexcept;

        [[nodiscard]] DateTime localDateTime() const noexcept;

        [[nodiscard]] inline constexpr std::int64_t ticks() const noexcept;

        [[nodiscard]] inline constexpr std::int64_t utcTicks() const noexcept;

        [[nodiscard]] inline std::int32_t year() const noexcept;

        [[nodiscard]] inline std::int32_t month() const noexcept;

        [[nodiscard]] inline std::int32_t day() const noexcept;

        [[nodiscard]] inline std::int32_t hour() const noexcept;

        [[nodiscard]] inline std::int32_t minute() const noexcept;

        [[nodiscard]] inline std::int32_t second() const noexcept;

        [[nodiscard]] inline std::int32_t millisecond() const noexcept;

        [[nodiscard]] inline std::int32_t microsecond() const noexcept;

        [[nodiscard]] inline std::int32_t nanosecond() const noexcept;

        [[nodiscard]] inline std::int32_t dayOfWeek() const noexcept;

        [[nodiscard]] inline std::int32_t dayOfYear() const noexcept;

        [[nodiscard]] inline std::int32_t totalOffsetMinutes() const noexcept;
 
        //----------------------------------------------
        // Conversion methods
        //----------------------------------------------

        [[nodiscard]] inline std::int64_t toEpochSeconds() const noexcept;

        [[nodiscard]] inline std::int64_t toEpochMilliseconds() const noexcept;

        [[nodiscard]] DateTimeOffset date() const noexcept;

        [[nodiscard]] inline TimeSpan timeOfDay() const noexcept;

        [[nodiscard]] DateTimeOffset toOffset( const TimeSpan& newOffset ) const noexcept;

        [[nodiscard]] DateTimeOffset toUniversalTime() const noexcept;

        [[nodiscard]] DateTimeOffset toLocalTime() const noexcept;

        [[nodiscard]] std::int64_t toFILETIME() const noexcept;
 
        //----------------------------------------------
        // Arithmetic methods
        //----------------------------------------------

        [[nodiscard]] inline DateTimeOffset add( const TimeSpan& value ) const noexcept;

        [[nodiscard]] DateTimeOffset addDays( double days ) const noexcept;

        [[nodiscard]] DateTimeOffset addHours( double hours ) const noexcept;

        [[nodiscard]] DateTimeOffset addMilliseconds( double milliseconds ) const noexcept;

        [[nodiscard]] DateTimeOffset addMinutes( double minutes ) const noexcept;

        [[nodiscard]] DateTimeOffset addMonths( std::int32_t months ) const noexcept;

        [[nodiscard]] DateTimeOffset addSeconds( double seconds ) const noexcept;

        [[nodiscard]] inline DateTimeOffset addTicks( std::int64_t ticks ) const noexcept;

        [[nodiscard]] DateTimeOffset addYears( std::int32_t years ) const noexcept;

        [[nodiscard]] inline TimeSpan subtract( const DateTimeOffset& value ) const noexcept;

        [[nodiscard]] inline DateTimeOffset subtract( const TimeSpan& value ) const noexcept;
 
        //----------------------------------------------
        // String formatting
        //----------------------------------------------

        [[nodiscard]] std::string toString( DateTime::Format format = DateTime::Format::Iso8601 ) const;
 
        //----------------------------------------------
        // Comparison methods
        //----------------------------------------------

        [[nodiscard]] inline bool equals( const DateTimeOffset& other ) const noexcept;

        [[nodiscard]] inline bool equalsExact( const DateTimeOffset& other ) const noexcept;
 
        //----------------------------------------------
        // Validation methods
        //----------------------------------------------

        [[nodiscard]] bool isValid() const noexcept;
 
        //----------------------------------------------
        // Static factory methods
        //----------------------------------------------

        [[nodiscard]] static DateTimeOffset now() noexcept;

        [[nodiscard]] static DateTimeOffset utcNow() noexcept;

        [[nodiscard]] static DateTimeOffset today() noexcept;

        [[nodiscard]] static DateTimeOffset min() noexcept;

        [[nodiscard]] static DateTimeOffset max() noexcept;

        [[nodiscard]] static DateTimeOffset epoch() noexcept;

        [[nodiscard]] static bool fromString( std::string_view iso8601String, DateTimeOffset& result ) noexcept;

        [[nodiscard]] static std::optional<DateTimeOffset> fromString( std::string_view iso8601String ) noexcept;

        [[nodiscard]] static DateTimeOffset fromEpochSeconds( std::int64_t seconds ) noexcept;

        [[nodiscard]] static DateTimeOffset fromEpochMilliseconds( std::int64_t milliseconds ) noexcept;

        [[nodiscard]] static DateTimeOffset fromFILETIME( std::int64_t FILETIME ) noexcept;
 
    private:
        DateTime m_dateTime;

        TimeSpan m_offset;
    };
} // namespace nfx::time
 
#include "nfx/detail/datetime/DateTimeOffset.inl"