TimeSpan.h File Reference

High-precision time interval representation with 100-nanosecond tick precision. More...

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

Include dependency graph for TimeSpan.h:

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

Go to the source code of this file.

Classes
class	nfx::time::TimeSpan
	Represents a time interval in 100-nanosecond ticks. More...

Detailed Description

High-precision time interval representation with 100-nanosecond tick precision.

Provides time duration operations with ISO 8601 duration format support, arithmetic operations, and conversions between various time units. Supports durations ranging from ±10,675,199 days (approximately ±29,247 years).

Note

This class represents time intervals/durations, not absolute points in time. For absolute time values, use DateTime or DateTimeOffset classes.

ISO 8601 Duration Format

TimeSpan uses a subset of ISO 8601 duration format for string representation:

┌──────────────────────────────────────────────────────────────────────┐
│              ISO 8601 Duration Format (TimeSpan Subset)              │
├──────────────────────────────────────────────────────────────────────┤
│  [−]  P  [n]D  T  [n]H  [n]M  [n]S                                   │
│   │   │   │    │   │     │     │                                     │
│   │   │   │    │   │     │     └─ Seconds (with optional decimal)    │
│   │   │   │    │   │     └─────── Minutes                            │
│   │   │   │    │   └───────────── Hours                              │
│   │   │   │    └───────────────── Time designator (REQUIRED)         │
│   │   │   └────────────────────── Days                               │
│   │   └────────────────────────── Period designator (REQUIRED)       │
│   └────────────────────────────── Optional negative sign             │
│                                                                      │
│                                                                      │
│  Note: Years and months have variable durations (leap years,         │
│          different month lengths) and cannot be converted to fixed   │
│          tick values. Only fixed-duration components are supported.  │
└──────────────────────────────────────────────────────────────────────┘

Format Examples:

┌──────────────────┬───────────────────────────────────────────────┐
│   Input String   │                    Meaning                    │
├──────────────────┼───────────────────────────────────────────────┤
│  PT1H            │  1 hour (compact format)                      │
│  PT1H0M0S        │  1 hour (verbose format - equivalent to PT1H) │
│  PT1H30M45S      │  1 hour, 30 minutes, 45 seconds               │
│  PT1.5S          │  1.5 seconds (fractional seconds allowed)     │
│  -PT2H           │  Negative 2 hours (duration in reverse)       │
│  P1D             │  1 day (date component only)                  │
│  P1DT12H30M      │  1 day, 12 hours, 30 minutes                  │
│  PT0S            │  Zero duration (minimum valid format)         │
└──────────────────┴───────────────────────────────────────────────┘

Key Rules:

• P (Period) is REQUIRED as the first character (after optional '-')
• T (Time) is REQUIRED if any time components (H/M/S) are present
• Components are optional but at least ONE must be present (D, H, M, or S)
• Compact format omits zero components (PT1H instead of PT1H0M0S)
• Fractional values allowed for seconds (PT1.5S = 1.5 seconds)
• Negative sign goes BEFORE the P (e.g., -PT1H for negative durations)

Internal Representation:

┌───────────────────────────────────────────────────────────┐
│     TimeSpan stores durations as 100-nanosecond ticks     │
├───────────────────────────────────────────────────────────┤
│  1 tick                = 100 nanoseconds                  │
│  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                            │
│                                                           │
│  Range: ±10,675,199 days (≈ ±29,247 years)                │
└───────────────────────────────────────────────────────────┘

Definition in file TimeSpan.h.