Timezone-aware DateTime class with UTC offset support. More...

#include <compare>
#include <cstdint>
#include <string>
#include <format>
#include <optional>
#include <string_view>
#include "DateTime.h"
#include "TimeSpan.h"
#include "nfx/detail/datetime/DateTimeOffset.inl"

Include dependency graph for DateTimeOffset.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
class	nfx::time::DateTimeOffset
	Timezone-aware DateTime with UTC offset. More...

Detailed Description

Timezone-aware DateTime class with UTC offset support.

Provides timezone-aware datetime operations with 100-nanosecond precision, ISO 8601 parsing/formatting with timezone offsets, and cross-platform compatibility. Supports date range from January 1, 0001 to December 31, 9999 with offset ±14:00:00.

Note: This implementation includes timezone offset support. For UTC-only operations, use the DateTime class instead.

ISO 8601 DateTime with Timezone Offset

DateTimeOffset uses ISO 8601 format with timezone offset for string representation:: ┌───────────────────────────────────────────────────────────────────┐

│ ISO 8601 DateTime Format with Timezone Offset │

├───────────────────────────────────────────────────────────────────┤

│ YYYY-MM-DD T HH:MM:SS [.fffffff] ±HH:MM or Z │

│ │ │ │ │ │ │ │ │ │ │ │ │

│ │ │ │ │ │ │ │ │ │ │ └── Zulu (UTC) │

│ │ │ │ │ │ │ │ │ │ └───────── Minutes │

│ │ │ │ │ │ │ │ │ └──────────── Hours │

│ │ │ │ │ │ │ │ └───────────────────── Fraction │

│ │ │ │ │ │ │ └───────────────────────────── Seconds │

│ │ │ │ │ │ └──────────────────────────────── Minutes │

│ │ │ │ │ └─────────────────────────────────── Hours │

│ │ │ │ └─────────────────────────────────────── Separator │

│ │ │ └─────────────────────────────────────────── Day │

│ │ └────────────────────────────────────────────── Month │

│ └────────────────────────────────────────────────── Year │

└───────────────────────────────────────────────────────────────────┘

Format Examples:: ┌────────────────────────────────┬─────────────────────────────────┐

│ Input String │ Meaning │

├────────────────────────────────┼─────────────────────────────────┤

│ 2024-01-15T12:30:45Z │ UTC time (Z = zero offset) │

│ 2024-01-15T12:30:45+02:00 │ Local: 12:30, UTC+2 (East) │

│ 2024-01-15T12:30:45-05:00 │ Local: 12:30, UTC-5 (West) │

│ 2024-01-15T12:30:45.123+01:00 │ With milliseconds, UTC+1 │

│ 2024-06-20T08:15:00+05:30 │ India Standard Time (UTC+5:30) │

│ 2024-12-25T00:00:00-08:00 │ Pacific Standard Time (UTC-8) │

└────────────────────────────────┴─────────────────────────────────┘

Timezone Offset Rules:

Valid range: ±14:00:00 (±840 minutes, ±50,400 seconds)
Positive offset: East of UTC (e.g., +09:00 for Japan)
Negative offset: West of UTC (e.g., -05:00 for US Eastern)
Z notation: Represents UTC (zero offset), equivalent to +00:00
Offset format: Always ±HH:MM in string representation

Internal Composition:: ┌───────────────────────────────────────────────────────────────────────┐

│ DateTimeOffset = DateTime + TimeSpan offset │

├───────────────────────────────────────────────────────────────────────┤

│ ┌─────────────────────────┐ ┌───────────────────────┐ │

│ │ DateTime (m_dateTime) │ │ TimeSpan (m_offset) │ │

│ │ │ │ │ │

│ │ Local date/time │ + │ Offset from UTC │ │

│ │ (100-ns ticks) │ │ (100-ns ticks) │ │

│ └─────────────────────────┘ └───────────────────────┘ │

│ │

│ Example: 2024-01-15T14:30:00+02:00 │

│ ↓ ↓ │

│ DateTime: 14:30 local Offset: +2 hours │

│ UTC equivalent: 14:30 - 2:00 = 12:30 UTC │

│ │

│ Comparisons: Always performed on UTC values (m_dateTime - m_offset) │

│ Arithmetic: Modifies DateTime, offset remains unchanged │

└───────────────────────────────────────────────────────────────────────┘

Key Differences from DateTime:: ┌─────────────────┬──────────────────────┬────────────────────────────┐

│ Aspect │ DateTime │ DateTimeOffset │

├─────────────────┼──────────────────────┼────────────────────────────┤

│ Timezone │ UTC only │ Offset-aware (±14:00:00) │

│ Storage │ Single tick value │ DateTime + offset │

│ String format │ ...Z (UTC only) │ ...±HH:MM or Z │

│ Comparisons │ Direct tick compare │ Convert to UTC first │

│ Use case │ System timestamps │ User-facing times │

│ Size │ 8 bytes │ 16 bytes │

└─────────────────┴──────────────────────┴────────────────────────────┘

Common Timezone Offsets:: ┌──────────────────────────┬──────────┬──────────────────────────┐

│ Timezone │ Offset │ Examples │

├──────────────────────────┼──────────┼──────────────────────────┤

│ UTC (GMT) │ +00:00 │ London (winter) │

│ Central European Time │ +01:00 │ Paris, Berlin │

│ Eastern European Time │ +02:00 │ Athens, Helsinki │

│ India Standard Time │ +05:30 │ Mumbai, Delhi │

│ China Standard Time │ +08:00 │ Beijing, Shanghai │

│ Japan Standard Time │ +09:00 │ Tokyo, Osaka │

│ Australian Eastern Time │ +10:00 │ Sydney, Melbourne │

│ Eastern Standard Time │ -05:00 │ New York, Toronto │

│ Pacific Standard Time │ -08:00 │ Los Angeles, Vancouver │

│ Hawaii-Aleutian Time │ -10:00 │ Honolulu │

└──────────────────────────┴──────────┴──────────────────────────┘

Definition in file DateTimeOffset.h.

Classes

Detailed Description

ISO 8601 DateTime with Timezone Offset