nfx-datetime 0.1.1
Cross-platform C++ DateTime library with 100-nanosecond precision and ISO 8601 support
Loading...
Searching...
No Matches
nfx::time::DateTime Class Referencefinal

Cross-platform DateTime type with 100-nanosecond precision. More...

#include <nfx/datetime/DateTime.h>

Public Types

enum class  Format : std::uint8_t {
  Iso8601Basic ,
  Iso8601Extended ,
  Iso8601WithOffset ,
  DateOnly ,
  TimeOnly ,
  UnixSeconds ,
  UnixMilliseconds
}
 DateTime string format options. More...

Public Member Functions

constexpr DateTime () noexcept
 Default constructor (minimum DateTime value).
constexpr DateTime (std::int64_t ticks) noexcept
 Construct from tick count (100-nanosecond units since year 1).
 DateTime (std::chrono::system_clock::time_point timePoint) noexcept
 Construct from system clock time point.
 DateTime (std::int32_t year, std::int32_t month, std::int32_t day) noexcept
 Construct from date components.
 DateTime (std::int32_t year, std::int32_t month, std::int32_t day, std::int32_t hour, std::int32_t minute, std::int32_t second) noexcept
 Construct from date and time components.
 DateTime (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) noexcept
 Construct from date and time components with milliseconds.
 DateTime (std::string_view iso8601String)
 Parse from ISO 8601 string.
 DateTime (const DateTime &)=default
 Copy constructor.
 DateTime (DateTime &&) noexcept=default
 Move constructor.
 ~DateTime ()=default
 Destructor.
DateTimeoperator= (const DateTime &)=default
 Copy assignment operator.
DateTimeoperator= (DateTime &&) noexcept=default
 Move assignment operator.
constexpr std::strong_ordering operator<=> (const DateTime &other) const noexcept
 Three-way comparison operator.
constexpr bool operator== (const DateTime &other) const noexcept
 Equality comparison.
constexpr DateTime operator+ (const TimeSpan &duration) const noexcept
 Add time duration.
constexpr DateTime operator- (const TimeSpan &duration) const noexcept
 Subtract time duration.
constexpr TimeSpan operator- (const DateTime &other) const noexcept
 Get time difference between DateTimes.
constexpr DateTimeoperator+= (const TimeSpan &duration) noexcept
 Add time duration (in-place).
constexpr DateTimeoperator-= (const TimeSpan &duration) noexcept
 Subtract time duration (in-place).
std::int32_t year () const noexcept
 Get year component (1-9999).
std::int32_t month () const noexcept
 Get month component (1-12).
std::int32_t day () const noexcept
 Get day component (1-31).
std::int32_t hour () const noexcept
 Get hour component (0-23).
std::int32_t minute () const noexcept
 Get minute component (0-59).
std::int32_t second () const noexcept
 Get second component (0-59).
std::int32_t millisecond () const noexcept
 Get millisecond component (0-999).
std::int32_t microsecond () const noexcept
 Get microsecond component (0-999).
std::int32_t nanosecond () const noexcept
 Get nanosecond component (0-900, in 100ns increments).
constexpr std::int64_t ticks () const noexcept
 Get tick count (100-nanosecond units since year 1).
std::int32_t dayOfWeek () const noexcept
 Get day of week (0=Sunday, 6=Saturday).
std::int32_t dayOfYear () const noexcept
 Get day of year (1-366).
constexpr std::int64_t toEpochSeconds () const noexcept
 Convert to Epoch timestamp (seconds since epoch).
constexpr std::int64_t toEpochMilliseconds () const noexcept
 Convert to Epoch timestamp (milliseconds since epoch).
DateTime date () const noexcept
 Get date component (time set to 00:00:00).
TimeSpan timeOfDay () const noexcept
 Get time of day as duration since midnight.
bool isValid () const noexcept
 Check if this DateTime is valid.
std::string toString () const
 Convert to ISO 8601 string (basic format).
std::string toString (Format format) const
 Convert to string using specified format.
std::string toIso8601Extended () const
 Convert to ISO 8601 extended format with full precision.
std::chrono::system_clock::time_point toChrono () const noexcept
 Convert to std::chrono::system_clock::time_point.

Static Public Member Functions

static constexpr bool isLeapYear (std::int32_t year) noexcept
 Check if given year is a leap year.
static constexpr std::int32_t daysInMonth (std::int32_t year, std::int32_t month) noexcept
 Get days in month for given year and month.
static DateTime now () noexcept
 Get current local time.
static DateTime utcNow () noexcept
 Get current UTC time.
static DateTime today () noexcept
 Get current local date (time set to 00:00:00).
static constexpr DateTime min () noexcept
 Get minimum DateTime value.
static constexpr DateTime max () noexcept
 Get maximum DateTime value.
static constexpr DateTime epoch () noexcept
 Get Unix epoch DateTime (January 1, 1970 00:00:00 UTC).
static bool fromString (std::string_view iso8601String, DateTime &result) noexcept
 Parse ISO 8601 string safely without throwing exceptions.
static std::optional< DateTimefromString (std::string_view iso8601String) noexcept
 Parse ISO 8601 string and return optional DateTime.
static constexpr DateTime fromEpochSeconds (std::int64_t seconds) noexcept
 Create from Epoch timestamp (seconds since epoch).
static constexpr DateTime fromEpochMilliseconds (std::int64_t milliseconds) noexcept
 Create from Epoch timestamp (milliseconds since epoch).
static DateTime fromChrono (const std::chrono::system_clock::time_point &timePoint) noexcept
 Create DateTime from std::chrono::system_clock::time_point.

Detailed Description

Cross-platform DateTime type with 100-nanosecond precision.

Implements datetime operations with:

  • 100-nanosecond tick precision (10 million ticks per second)
  • Range: January 1, 0001 to December 31, 9999
  • ISO 8601 string parsing and formatting
  • System clock interoperability
  • Arithmetic operations with time intervals
  • Support for both UTC and local time representations

Note: DateTime doesn't store timezone information. For explicit timezone offset tracking, use DateTimeOffset instead.

Definition at line 223 of file datetime/DateTime.h.

Member Enumeration Documentation

◆ Format

enum class nfx::time::DateTime::Format : std::uint8_t
strong

DateTime string format options.

Provides type-safe format selection with self-documenting format names

Enumerator
Iso8601Basic 

ISO 8601 basic format: "2024-01-01T12:00:00Z".

Iso8601Extended 

ISO 8601 extended format with fractional seconds: "2024-01-01T12:00:00.1234567Z".

Iso8601WithOffset 

Date and time with timezone: "2024-01-01T12:00:00+02:00".

DateOnly 

Date only format: "2024-01-01".

TimeOnly 

Time only: "12:00:00".

UnixSeconds 

Epoch timestamp format: "1704110400" (seconds since epoch).

UnixMilliseconds 

Epoch timestamp with milliseconds: "1704110400123".

Definition at line 234 of file datetime/DateTime.h.

Constructor & Destructor Documentation

◆ DateTime() [1/6]

nfx::time::DateTime::DateTime ( std::int64_t ticks)
inlineexplicitconstexprnoexcept

Construct from tick count (100-nanosecond units since year 1).

Parameters
ticksNumber of 100-nanosecond intervals since January 1, 0001 UTC
Here is the call graph for this function:

◆ DateTime() [2/6]

nfx::time::DateTime::DateTime ( std::chrono::system_clock::time_point timePoint)
inlineexplicitnoexcept

Construct from system clock time point.

Parameters
timePointSystem clock time point to convert from
Here is the call graph for this function:

◆ DateTime() [3/6]

nfx::time::DateTime::DateTime ( std::int32_t year,
std::int32_t month,
std::int32_t day )
noexcept

Construct from date components.

Parameters
yearYear component (1-9999)
monthMonth component (1-12)
dayDay component (1-31)
Here is the call graph for this function:

◆ DateTime() [4/6]

nfx::time::DateTime::DateTime ( std::int32_t year,
std::int32_t month,
std::int32_t day,
std::int32_t hour,
std::int32_t minute,
std::int32_t second )
noexcept

Construct from date and time components.

Parameters
yearYear component (1-9999)
monthMonth component (1-12)
dayDay component (1-31)
hourHour component (0-23)
minuteMinute component (0-59)
secondSecond component (0-59)
Here is the call graph for this function:

◆ DateTime() [5/6]

nfx::time::DateTime::DateTime ( 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 )
noexcept

Construct from date and time components with milliseconds.

Parameters
yearYear component (1-9999)
monthMonth component (1-12)
dayDay component (1-31)
hourHour component (0-23)
minuteMinute component (0-59)
secondSecond component (0-59)
millisecondMillisecond component (0-999)
Here is the call graph for this function:

◆ DateTime() [6/6]

nfx::time::DateTime::DateTime ( std::string_view iso8601String)
inlineexplicit

Parse from ISO 8601 string.

Parameters
iso8601StringISO 8601 formatted string to parse
Here is the call graph for this function:

Member Function Documentation

◆ date()

DateTime nfx::time::DateTime::date ( ) const
nodiscardnoexcept

Get date component (time set to 00:00:00).

Returns
New DateTime with the same date but time set to 00:00:00
Note
This function is marked [[nodiscard]] - the return value should not be ignored
Here is the call graph for this function:
Here is the caller graph for this function:

◆ day()

std::int32_t nfx::time::DateTime::day ( ) const
nodiscardnoexcept

Get day component (1-31).

Returns
The day component of this DateTime (1-31)
Note
This function is marked [[nodiscard]] - the return value should not be ignored
Here is the call graph for this function:
Here is the caller graph for this function:

◆ dayOfWeek()

std::int32_t nfx::time::DateTime::dayOfWeek ( ) const
nodiscardnoexcept

Get day of week (0=Sunday, 6=Saturday).

Returns
The day of week as an integer (0=Sunday, 1=Monday, ..., 6=Saturday)
Note
This function is marked [[nodiscard]] - the return value should not be ignored
Here is the call graph for this function:
Here is the caller graph for this function:

◆ dayOfYear()

std::int32_t nfx::time::DateTime::dayOfYear ( ) const
nodiscardnoexcept

Get day of year (1-366).

Returns
The day of year as an integer (1-366, where 366 occurs in leap years)
Note
This function is marked [[nodiscard]] - the return value should not be ignored
Here is the call graph for this function:
Here is the caller graph for this function:

◆ daysInMonth()

constexpr std::int32_t nfx::time::DateTime::daysInMonth ( std::int32_t year,
std::int32_t month )
inlinestaticnodiscardconstexprnoexcept

Get days in month for given year and month.

Parameters
yearThe year to check (1-9999)
monthThe month to check (1-12)
Returns
Number of days in the specified month (28-31)
Note
This function is marked [[nodiscard]] - the return value should not be ignored
Here is the call graph for this function:
Here is the caller graph for this function:

◆ epoch()

constexpr DateTime nfx::time::DateTime::epoch ( )
inlinestaticnodiscardconstexprnoexcept

Get Unix epoch DateTime (January 1, 1970 00:00:00 UTC).

Returns
DateTime representing the Unix epoch (January 1, 1970 00:00:00 UTC)
Note
This function is marked [[nodiscard]] - the return value should not be ignored
Here is the call graph for this function:
Here is the caller graph for this function:

◆ fromChrono()

DateTime nfx::time::DateTime::fromChrono ( const std::chrono::system_clock::time_point & timePoint)
staticnodiscardnoexcept

Create DateTime from std::chrono::system_clock::time_point.

Values outside the representable range of DateTime will be clamped to the nearest valid DateTime value.

Parameters
timePointThe system_clock time point to convert
Returns
A DateTime representing the same instant in time
Note
This function is marked [[nodiscard]] - the return value should not be ignored
Here is the call graph for this function:
Here is the caller graph for this function:

◆ fromEpochMilliseconds()

constexpr DateTime nfx::time::DateTime::fromEpochMilliseconds ( std::int64_t milliseconds)
inlinestaticnodiscardconstexprnoexcept

Create from Epoch timestamp (milliseconds since epoch).

Parameters
millisecondsThe number of milliseconds since Unix epoch (January 1, 1970 00:00:00 UTC)
Returns
DateTime representing the specified Epoch timestamp in milliseconds
Note
This function is marked [[nodiscard]] - the return value should not be ignored
Here is the call graph for this function:
Here is the caller graph for this function:

◆ fromEpochSeconds()

constexpr DateTime nfx::time::DateTime::fromEpochSeconds ( std::int64_t seconds)
inlinestaticnodiscardconstexprnoexcept

Create from Epoch timestamp (seconds since epoch).

Parameters
secondsThe number of seconds since Unix epoch (January 1, 1970 00:00:00 UTC)
Returns
DateTime representing the specified Epoch timestamp
Note
This function is marked [[nodiscard]] - the return value should not be ignored
Here is the call graph for this function:
Here is the caller graph for this function:

◆ fromString() [1/2]

std::optional< DateTime > nfx::time::DateTime::fromString ( std::string_view iso8601String)
staticnodiscardnoexcept

Parse ISO 8601 string and return optional DateTime.

Parameters
iso8601StringThe ISO 8601 formatted string to parse
Returns
std::optional<DateTime> containing the parsed value if successful, std::nullopt otherwise
Note
This function is marked [[nodiscard]] - the return value should not be ignored
Here is the call graph for this function:

◆ fromString() [2/2]

bool nfx::time::DateTime::fromString ( std::string_view iso8601String,
DateTime & result )
staticnodiscardnoexcept

Parse ISO 8601 string safely without throwing exceptions.

Parameters
iso8601StringThe ISO 8601 formatted string to parse
resultReference to store the parsed DateTime if successful
Returns
true if parsing succeeded, false otherwise
Note
This function is marked [[nodiscard]] - the return value should not be ignored
Here is the call graph for this function:
Here is the caller graph for this function:

◆ hour()

std::int32_t nfx::time::DateTime::hour ( ) const
nodiscardnoexcept

Get hour component (0-23).

Returns
The hour component of this DateTime (0-23)
Note
This function is marked [[nodiscard]] - the return value should not be ignored
Here is the call graph for this function:
Here is the caller graph for this function:

◆ isLeapYear()

constexpr bool nfx::time::DateTime::isLeapYear ( std::int32_t year)
inlinestaticnodiscardconstexprnoexcept

Check if given year is a leap year.

Parameters
yearThe year to check for leap year status
Returns
true if the year is a leap year, false otherwise
Note
This function is marked [[nodiscard]] - the return value should not be ignored
Here is the call graph for this function:
Here is the caller graph for this function:

◆ isValid()

bool nfx::time::DateTime::isValid ( ) const
nodiscardnoexcept

Check if this DateTime is valid.

Returns
true if this DateTime represents a valid date and time, false otherwise
Note
This function is marked [[nodiscard]] - the return value should not be ignored
Here is the call graph for this function:
Here is the caller graph for this function:

◆ max()

constexpr DateTime nfx::time::DateTime::max ( )
inlinestaticnodiscardconstexprnoexcept

Get maximum DateTime value.

Returns
DateTime representing the maximum representable date (December 31, 9999 23:59:59.9999999 UTC)
Note
This function is marked [[nodiscard]] - the return value should not be ignored
Here is the call graph for this function:
Here is the caller graph for this function:

◆ microsecond()

std::int32_t nfx::time::DateTime::microsecond ( ) const
nodiscardnoexcept

Get microsecond component (0-999).

Returns
The microsecond component of this DateTime (0-999)
Note
This function is marked [[nodiscard]] - the return value should not be ignored
Here is the call graph for this function:
Here is the caller graph for this function:

◆ millisecond()

std::int32_t nfx::time::DateTime::millisecond ( ) const
nodiscardnoexcept

Get millisecond component (0-999).

Returns
The millisecond component of this DateTime (0-999)
Note
This function is marked [[nodiscard]] - the return value should not be ignored
Here is the call graph for this function:
Here is the caller graph for this function:

◆ min()

constexpr DateTime nfx::time::DateTime::min ( )
inlinestaticnodiscardconstexprnoexcept

Get minimum DateTime value.

Returns
DateTime representing the minimum representable date (January 1, 0001 00:00:00.0000000 UTC)
Note
This function is marked [[nodiscard]] - the return value should not be ignored
Here is the call graph for this function:
Here is the caller graph for this function:

◆ minute()

std::int32_t nfx::time::DateTime::minute ( ) const
nodiscardnoexcept

Get minute component (0-59).

Returns
The minute component of this DateTime (0-59)
Note
This function is marked [[nodiscard]] - the return value should not be ignored
Here is the call graph for this function:
Here is the caller graph for this function:

◆ month()

std::int32_t nfx::time::DateTime::month ( ) const
nodiscardnoexcept

Get month component (1-12).

Returns
The month component of this DateTime (1-12)
Note
This function is marked [[nodiscard]] - the return value should not be ignored
Here is the call graph for this function:
Here is the caller graph for this function:

◆ nanosecond()

std::int32_t nfx::time::DateTime::nanosecond ( ) const
nodiscardnoexcept

Get nanosecond component (0-900, in 100ns increments).

Returns
The nanosecond component of this DateTime (0, 100, 200, ..., 900)
Note
This function is marked [[nodiscard]] - the return value should not be ignored
Due to 100-nanosecond tick precision, only values 0-900 in 100ns increments are possible
Here is the call graph for this function:
Here is the caller graph for this function:

◆ now()

DateTime nfx::time::DateTime::now ( )
staticnodiscardnoexcept

Get current local time.

Returns
DateTime representing the current local date and time (system timezone)
Note
This function is marked [[nodiscard]] - the return value should not be ignored
Here is the call graph for this function:
Here is the caller graph for this function:

◆ operator+()

DateTime nfx::time::DateTime::operator+ ( const TimeSpan & duration) const
inlineconstexprnoexcept

Add time duration.

Parameters
durationThe TimeSpan to add to this DateTime
Returns
New DateTime representing this DateTime plus the duration
Here is the call graph for this function:

◆ operator+=()

DateTime & nfx::time::DateTime::operator+= ( const TimeSpan & duration)
inlineconstexprnoexcept

Add time duration (in-place).

Parameters
durationThe TimeSpan to add to this DateTime
Returns
Reference to this DateTime after adding the duration
Here is the call graph for this function:

◆ operator-() [1/2]

TimeSpan nfx::time::DateTime::operator- ( const DateTime & other) const
inlineconstexprnoexcept

Get time difference between DateTimes.

Parameters
otherThe DateTime to subtract from this DateTime
Returns
TimeSpan representing the difference (this - other)
Here is the call graph for this function:

◆ operator-() [2/2]

DateTime nfx::time::DateTime::operator- ( const TimeSpan & duration) const
inlineconstexprnoexcept

Subtract time duration.

Parameters
durationThe TimeSpan to subtract from this DateTime
Returns
New DateTime representing this DateTime minus the duration
Here is the call graph for this function:

◆ operator-=()

DateTime & nfx::time::DateTime::operator-= ( const TimeSpan & duration)
inlineconstexprnoexcept

Subtract time duration (in-place).

Parameters
durationThe TimeSpan to subtract from this DateTime
Returns
Reference to this DateTime after subtracting the duration
Here is the call graph for this function:

◆ operator<=>()

std::strong_ordering nfx::time::DateTime::operator<=> ( const DateTime & other) const
inlineconstexprnoexcept

Three-way comparison operator.

Parameters
otherThe DateTime to compare with
Returns
std::strong_ordering indicating the relative order of the two DateTimes
Here is the call graph for this function:

◆ operator=() [1/2]

DateTime & nfx::time::DateTime::operator= ( const DateTime & )
default

Copy assignment operator.

Returns
Reference to this DateTime after assignment
Here is the call graph for this function:

◆ operator=() [2/2]

DateTime & nfx::time::DateTime::operator= ( DateTime && )
defaultnoexcept

Move assignment operator.

Returns
Reference to this DateTime after assignment
Here is the call graph for this function:

◆ operator==()

bool nfx::time::DateTime::operator== ( const DateTime & other) const
inlineconstexprnoexcept

Equality comparison.

Parameters
otherThe DateTime to compare with
Returns
true if both DateTimes represent the same instant, false otherwise
Here is the call graph for this function:

◆ second()

std::int32_t nfx::time::DateTime::second ( ) const
nodiscardnoexcept

Get second component (0-59).

Returns
The second component of this DateTime (0-59)
Note
This function is marked [[nodiscard]] - the return value should not be ignored
Here is the call graph for this function:
Here is the caller graph for this function:

◆ ticks()

std::int64_t nfx::time::DateTime::ticks ( ) const
nodiscardconstexprnoexcept

Get tick count (100-nanosecond units since year 1).

Returns
The number of 100-nanosecond intervals since January 1, 0001 UTC
Note
This function is marked [[nodiscard]] - the return value should not be ignored
Here is the call graph for this function:
Here is the caller graph for this function:

◆ timeOfDay()

TimeSpan nfx::time::DateTime::timeOfDay ( ) const
nodiscardnoexcept

Get time of day as duration since midnight.

Returns
TimeSpan representing the elapsed time since midnight (00:00:00)
Note
This function is marked [[nodiscard]] - the return value should not be ignored
Here is the call graph for this function:
Here is the caller graph for this function:

◆ toChrono()

std::chrono::system_clock::time_point nfx::time::DateTime::toChrono ( ) const
nodiscardnoexcept

Convert to std::chrono::system_clock::time_point.

Values outside the representable range of std::chrono::system_clock (approximately years 1677-2262 on 64-bit Linux systems) will be clamped to the nearest representable value. This means extreme dates (near year 1 or year 9999) cannot round-trip through chrono.

Returns
A system_clock::time_point representing this DateTime
Note
This function is marked [[nodiscard]] - the return value should not be ignored
Here is the call graph for this function:
Here is the caller graph for this function:

◆ today()

DateTime nfx::time::DateTime::today ( )
staticnodiscardnoexcept

Get current local date (time set to 00:00:00).

Returns
DateTime representing the current local date with time set to 00:00:00
Note
This function is marked [[nodiscard]] - the return value should not be ignored
Here is the call graph for this function:
Here is the caller graph for this function:

◆ toEpochMilliseconds()

std::int64_t nfx::time::DateTime::toEpochMilliseconds ( ) const
inlinenodiscardconstexprnoexcept

Convert to Epoch timestamp (milliseconds since epoch).

Returns
Number of milliseconds since Unix epoch (January 1, 1970 00:00:00 UTC)
Note
This function is marked [[nodiscard]] - the return value should not be ignored
Here is the call graph for this function:
Here is the caller graph for this function:

◆ toEpochSeconds()

std::int64_t nfx::time::DateTime::toEpochSeconds ( ) const
inlinenodiscardconstexprnoexcept

Convert to Epoch timestamp (seconds since epoch).

Returns
Number of seconds since Unix epoch (January 1, 1970 00:00:00 UTC)
Note
This function is marked [[nodiscard]] - the return value should not be ignored
Here is the call graph for this function:
Here is the caller graph for this function:

◆ toIso8601Extended()

std::string nfx::time::DateTime::toIso8601Extended ( ) const
nodiscard

Convert to ISO 8601 extended format with full precision.

Returns
String representation in ISO 8601 extended format with fractional seconds (e.g., "2024-01-01T12:00:00.1234567Z")
Note
This function is marked [[nodiscard]] - the return value should not be ignored
Here is the call graph for this function:
Here is the caller graph for this function:

◆ toString() [1/2]

std::string nfx::time::DateTime::toString ( ) const
nodiscard

Convert to ISO 8601 string (basic format).

Returns
String representation in ISO 8601 basic format (e.g., "2024-01-01T12:00:00Z")
Note
This function is marked [[nodiscard]] - the return value should not be ignored
Here is the call graph for this function:
Here is the caller graph for this function:

◆ toString() [2/2]

std::string nfx::time::DateTime::toString ( Format format) const
nodiscard

Convert to string using specified format.

Parameters
formatThe format to use for string conversion
Returns
String representation using the specified format
Note
This function is marked [[nodiscard]] - the return value should not be ignored
Here is the call graph for this function:

◆ utcNow()

DateTime nfx::time::DateTime::utcNow ( )
staticnodiscardnoexcept

Get current UTC time.

Returns
DateTime representing the current UTC date and time
Note
This function is marked [[nodiscard]] - the return value should not be ignored
Here is the call graph for this function:
Here is the caller graph for this function:

◆ year()

std::int32_t nfx::time::DateTime::year ( ) const
nodiscardnoexcept

Get year component (1-9999).

Returns
The year component of this DateTime (1-9999)
Note
This function is marked [[nodiscard]] - the return value should not be ignored
Here is the call graph for this function:
Here is the caller graph for this function:

The documentation for this class was generated from the following file: