DateTime.h File Reference

Cross-platform DateTime class with ISO 8601 support. More...

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

Include dependency graph for datetime/DateTime.h:

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

Go to the source code of this file.

Classes
class	nfx::time::DateTime
	Cross-platform DateTime type with 100-nanosecond precision. More...

Detailed Description

Cross-platform DateTime class with ISO 8601 support.

Provides datetime operations with 100-nanosecond precision, ISO 8601 parsing and formatting, and cross-platform compatibility. Supports date range from January 1, 0001 to December 31, 9999.

Note

DateTime can represent both UTC and local times. For timezone-aware operations with explicit offset information, use the DateTimeOffset class instead.

ISO 8601 DateTime Format

DateTime uses ISO 8601 format with UTC timezone for string representation:

┌─────────────────────────────────────────────────────────────────────┐
│                     ISO 8601 DateTime Format                        │
├─────────────────────────────────────────────────────────────────────┤
│  YYYY-MM-DD  T  HH:MM:SS  [.fffffff]  Z                             │
│   │  │  │   │   │  │  │      │        │                             │
│   │  │  │   │   │  │  │      │        └─ Zulu (UTC indicator)       │
│   │  │  │   │   │  │  │      └────────── Fraction (optional)        │
│   │  │  │   │   │  │  └───────────────── Seconds (00-59)            │
│   │  │  │   │   │  └──────────────────── Minutes (00-59)            │
│   │  │  │   │   └─────────────────────── Hours (00-23)              │
│   │  │  │   └─────────────────────────── Time separator             │
│   │  │  └─────────────────────────────── Day (01-31)                │
│   │  └────────────────────────────────── Month (01-12)              │
│   └───────────────────────────────────── Year (0001-9999)           │
│                                                                     │
│  Note: DateTime values can represent UTC or local time. The 'Z'     │
│        suffix is used for UTC serialization, but DateTime itself    │
│        doesn't store timezone information.                          │
└─────────────────────────────────────────────────────────────────────┘

Format Examples:

┌────────────────────────────────┬───────────────────────────────────┐
│          Input String          │              Meaning              │
├────────────────────────────────┼───────────────────────────────────┤
│  2024-01-15T12:30:45Z          │  Jan 15, 2024, 12:30:45 UTC       │
│  2024-06-20T00:00:00Z          │  Jun 20, 2024, midnight UTC       │
│  2024-12-31T23:59:59Z          │  Dec 31, 2024, 23:59:59 UTC       │
│  2024-01-15T12:30:45.123Z      │  With milliseconds (123 ms)       │
│  2024-01-15T12:30:45.123456Z   │  With microseconds (123.456 ms)   │
│  2024-01-15T12:30:45.1234567Z  │  Full precision (100 ns ticks)    │
│  1970-01-01T00:00:00Z          │  Unix epoch (start of Unix time)  │
│  0001-01-01T00:00:00Z          │  Minimum DateTime value           │
│  9999-12-31T23:59:59.9999999Z  │  Maximum DateTime value           │
└────────────────────────────────┴───────────────────────────────────┘

Date-Only Format:

┌──────────────┬────────────────────────────────────────────────┐
│  YYYY-MM-DD  │  Date without time (time implicitly 00:00:00)  │
├──────────────┼────────────────────────────────────────────────┤
│  2024-01-15  │  January 15, 2024 at midnight UTC              │
│  2024-06-20  │  June 20, 2024 at midnight UTC                 │
└──────────────┴────────────────────────────────────────────────┘

Internal Representation:

┌──────────────────────────────────────────────────────────────────────┐
│        DateTime stores absolute time as 100-nanosecond ticks         │
├──────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  Tick = 100 nanoseconds (0.0000001 seconds)                          │
│                                                                      │
│   ┌─────────────────────────────────────────────────────────────┐    │
│   │                  Tick Conversion Reference                  │    │
│   ├─────────────────────────────────────────────────────────────┤    │
│   │  1 tick                = 100 nanoseconds                    │    │
│   │  10 ticks              = 1 microsecond                      │    │
│   │  10,000 ticks          = 1 millisecond                      │    │
│   │  10,000,000 ticks      = 1 second                           │    │
│   │  600,000,000 ticks     = 1 minute                           │    │
│   │  36,000,000,000 ticks  = 1 hour                             │    │
│   │  864,000,000,000 ticks = 1 day                              │    │
│   └─────────────────────────────────────────────────────────────┘    │
│                                                                      │
│  Epoch: Ticks are counted from January 1, 0001 00:00:00.0000000 UTC  │
│                                                                      │
│  Range: 0001-01-01T00:00:00.0000000Z to 9999-12-31T23:59:59.9999999Z │
│         (0 ticks to 3,155,378,975,999,999,999 ticks)                 │
│                                                                      │
│  Storage: Single int64_t (8 bytes) - compact and efficient           │
└──────────────────────────────────────────────────────────────────────┘

Key Characteristics:

┌──────────────────┬───────────────────────────────────────────────┐
│     Property     │                  Description                  │
├──────────────────┼───────────────────────────────────────────────┤
│  Timezone        │  Can represent UTC or local time              │
│  Precision       │  100 nanoseconds (10 million ticks/second)    │
│  Range           │  Year 1 to Year 9999 (Gregorian calendar)     │
│  Storage size    │  8 bytes (single int64_t)                     │
│  String format   │  ISO 8601 with 'Z' suffix (UTC)               │
│  Leap years      │  Fully supported (Feb 29 in leap years)       │
│  Leap seconds    │  Not supported (follows standard time)        │
│  Calendar        │  Proleptic Gregorian (extended before 1582)   │
│  Use case        │  System logs, timestamps, general datetime    │
└──────────────────┴───────────────────────────────────────────────┘

DateTime vs DateTimeOffset:

┌───────────────────┬─────────────────────┬─────────────────────────────┐
│      Feature      │      DateTime       │       DateTimeOffset        │
├───────────────────┼─────────────────────┼─────────────────────────────┤
│  Timezone info    │  None (implicit)    │  Explicit offset from UTC   │
│  Storage          │  8 bytes            │  16 bytes (DateTime+offset) │
│  String format    │  ...Z               │  ...±HH:MM or Z             │
│  Local time       │  Supported via now()│  Always explicit with offset│
│  Comparisons      │  Direct             │  Via UTC conversion         │
│  Use for          │  General datetime   │  Timezone-aware operations  │
│  Example          │  Log timestamps     │  Appointment scheduling     │
└───────────────────┴─────────────────────┴─────────────────────────────┘

Common DateTime Operations:

┌──────────────────────────────────────────────────────────────────────┐
│                          Operation Examples                          │
├──────────────────────────────────────────────────────────────────────┤
│  // Current local time                                               │
│  DateTime now{ DateTime::now() };                                    │
│                                                                      │
│  // Current UTC time                                                 │
│  DateTime utcNow{ DateTime::utcNow() };                              │
│                                                                      │
│  // Create specific date/time                                        │
│  DateTime dt{ 2024, 6, 15, 14, 30, 0 };  // Jun 15, 2024 14:30       │
│                                                                      │
│  // Parse from string (constructor - throws on error)                │
│  DateTime parsed1{ "2024-06-15T14:30:00Z" };                         │
│                                                                      │
│  // Parse from string (safe - returns std::optional)                 │
│  auto parsed2 = DateTime::fromString("2024-06-15T14:30:00Z");        │
│  if (parsed2)                                                        │
│  {                                                                   │
│      // use parsed2                                                  │
│  }                                                                   │
│                                                                      │
│  // Arithmetic                                                       │
│  DateTime later{ dt + TimeSpan::fromHours(2.5) };                    │
│  TimeSpan duration = later - dt;                                     │
│                                                                      │
│  // Epoch timestamp conversion                                       │
│  int64_t epochSecs = dt.toEpochSeconds();                            │
│  DateTime fromEpoch{ DateTime::fromEpochSeconds(epochSecs) };        │
│                                                                      │
│  // Format output                                                    │
│  std::string basic{ dt.toString() };             // Basic ISO 8601   │
│  std::string precise{ dt.toIso8601Extended() };  // With fractions   │
└──────────────────────────────────────────────────────────────────────┘

Important Notes:

• UTC vs Local: Use now() for local time, utcNow() for UTC
• No Timezone Info: DateTime doesn't store timezone offset (use DateTimeOffset for that)
• No Daylight Saving: DateTime doesn't track DST changes automatically
• Leap Years: Automatically handled (Feb 29 exists in 2024, 2028, etc.)
• No Leap Seconds: Follows standard civil time (ignores leap seconds)
• std::chrono Integration: Convertible to/from std::chrono::system_clock::time_point
• Thread-Safe: All operations are thread-safe (immutable value type)

Definition in file datetime/DateTime.h.