Date and Time

Date and Time Types

Introduction

The time namespace provides types for working with civil dates, wall-clock times, and time spans. The calendar helper structs are small aggregate result types for APIs that return more than one calendar component. They keep call sites readable by naming the returned values.

const auto parts = date.parts();
const auto year = parts.year;
const auto month = parts.month;
const auto day = parts.day;

const auto next = el::Month::december().next(el::Year{2026});
const auto nextMonth = next.month;

Date

Date stores a civil date in the proleptic Gregorian calendar. The internal epoch is 0000-01-01 and raw day zero is that date. The supported range is 0000-01-01 through 9999-12-31. Use parts() when you need named DateParts instead of separate accessor calls.

Date arithmetic saturates at the supported range. For example, adding a negative day count to the first supported date keeps the result at 0000-01-01. Use wouldAddSaturate() to test for this condition and addedOrThrow() or addOrThrow() to reject it with OverflowError.

Date Time

DateTime represents an instant as UTC date and time plus display offset information. It converts to and from ISO text, std::time_t, exact typed ticks from the Core, POSIX, Windows, and RFC 868 epochs, fixed offsets, and supported named time zones. Tick conversion accepts nanoseconds, microseconds, milliseconds, or seconds; a conversion fails when it would lose fractional precision, precedes the selected epoch, or exceeds the selected unit’s range. Use the split seconds-and-nanoseconds conversion for external formats that need their own fractional representation, such as Windows FILETIME. The value is stored internally as a UTC instant; local accessors and parts() use the display offset or named time zone.

Date-time arithmetic is performed on the UTC instant and saturates at DateTime::first() or DateTime::last() when the result would leave the supported range. Use wouldAddSaturate() or wouldSubtractSaturate() to test for this condition, and use the ...OrThrow() variants to reject it with OverflowError.

A TimeWithZone combines a wall-clock Time with a TimeZone. It does not represent an instant until it is combined with a date. Named zones therefore render using their IANA name instead of inventing a numeric offset. Constructing a DateTime from a date and TimeWithZone resolves the exact offset for the civil date and time, converts the value to internally stored UTC, and retains the display zone.

Time

Time stores a wall-clock time of day with nanosecond precision. Arithmetic that crosses midnight returns the day wrap separately.

Use TimeParts and TimeWrapResult as named aggregate results:

const auto parts = time.parts();
const auto hour = parts.hour;

const auto wrapped = time.addedWithWrap(el::Duration{el::Hours{3}});
const auto dayCarry = wrapped.days;
const auto newTime = wrapped.time;

Time Zone

TimeZone represents UTC, a fixed offset, or a supported named IANA zone. Lookup factories return std::optional for tolerant lookup and OrThrow variants for explicit failure. Fixed offsets are normalized only by complete 24-hour rotations, so offsets such as UTC+13 and UTC+14 retain their direction.

TimeZone::local() identifies and caches the operating system’s base time zone for the process lifetime. POSIX systems use TZ and canonical zoneinfo paths; Windows names are mapped to IANA names using generated Unicode CLDR data. Resolution failures produce UTC with the local-origin marker set. Combining the zone with a civil date and time always resolves the bundled database again, retaining historical shifts, daylight-saving state, abbreviations, gaps, and folds.

The local-origin marker records that the current display zone came from the system setting. Copies, arithmetic, and UTC normalization preserve it. Explicit zone conversion replaces it with the target zone’s marker: conversion to UTC or an explicit zone clears it, while conversion to TimeZone::local() sets it. Default string formatting omits the zone for local-origin values. DateTime::toIsoString() with IsoTimeFormat::TimeShift still forces the resolved numeric offset.

Duration and Time Amounts

Introduction

Duration and time span types store signed time intervals at different resolutions.

Duration stores a signed span with second resolution. Conversions to coarser parts truncate toward zero. Conversions to nanosecond precision, such as toTimeDelta(), saturate if the represented nanoseconds exceed the target type. Use wouldConvertToTimeDeltaSaturate() or toTimeDeltaOrThrow() when saturation must be detected or rejected.

TimeDelta stores a signed span with nanosecond resolution. Conversion to Duration truncates sub-second nanoseconds toward zero. toSecondsWithFractions() and toDaysWithFractions() return approximate floating-point values and do not treat rounding as an error. The unit factories from nanoseconds() through weeks() saturate when conversion exceeds the stored nanosecond range. Use the corresponding ...OrThrow() factory, including weeksOrThrow(), when overflow must be rejected.

CalendarDelta stores nanoseconds through years as independent signed components. It deliberately does not normalize its stored parts: one month remains one month, and mixed positive and negative components remain visible through the typed accessors. Conversion to TimeDelta is available only when the month and year components are zero and the exact fixed-unit sum fits the nanosecond range.

Applying a CalendarDelta to a DateTime processes nanoseconds, microseconds, milliseconds, seconds, minutes, hours, days, weeks, months, and years in that order. Month and year steps use the same end-of-month clamping semantics as Date. Arithmetic is performed on the UTC representation; fixed display offsets are retained and named-zone metadata is refreshed for the final instant.

TimeDeltaFormat controls short or long names, separators, the smallest fixed unit, and fractional output. TimeDeltaFormat::elcl() selects the aliases and separators required for ELCL serialization. Calendar-delta formatting always emits non-zero years and months independently and uses exact signed normalization for the fixed units without first forcing the total into TimeDelta.

Interface

class CalendarDelta

A non-normalized delta composed from independent fixed and calendar amounts.

See: Date and Time

Public Types

using Parts = CalendarDeltaParts : Alias for all independently stored delta parts.

Public Functions

inline explicit CalendarDelta(const Parts &parts) noexcept: Create a calendar delta from all parts.

template<typename tAmount> inline CalendarDelta(tAmount amount) noexcept: Create a calendar delta containing one amount.

CalendarDelta operator+(CalendarDelta other) const noexcept: Add other to this delta.

CalendarDelta &operator+=(CalendarDelta other) noexcept: Add other to this delta in place.

CalendarDelta operator-(CalendarDelta other) const noexcept: Subtract other from this delta.

CalendarDelta &operator-=(CalendarDelta other) noexcept: Subtract other from this delta in place.

CalendarDelta operator-() const noexcept: Negate every part of this delta.

bool isZero() const noexcept: Test whether every part is zero.

bool isValidTimeDelta() const noexcept: Test whether this delta contains no calendar-dependent units.

inline constexpr Parts parts() const noexcept: Access all independently stored parts.

inline constexpr Nanoseconds nanoseconds() const noexcept: Access the nanosecond part.

CalendarDelta &setNanoseconds(Nanoseconds value) noexcept: Set the nanosecond part.

inline constexpr Microseconds microseconds() const noexcept: Access the microsecond part.

CalendarDelta &setMicroseconds(Microseconds value) noexcept: Set the microsecond part.

inline constexpr Milliseconds milliseconds() const noexcept: Access the millisecond part.

CalendarDelta &setMilliseconds(Milliseconds value) noexcept: Set the millisecond part.

inline constexpr Seconds seconds() const noexcept: Access the second part.

CalendarDelta &setSeconds(Seconds value) noexcept: Set the second part.

inline constexpr Minutes minutes() const noexcept: Access the minute part.

CalendarDelta &setMinutes(Minutes value) noexcept: Set the minute part.

inline constexpr Hours hours() const noexcept: Access the hour part.

CalendarDelta &setHours(Hours value) noexcept: Set the hour part.

inline constexpr Days days() const noexcept: Access the day part.

CalendarDelta &setDays(Days value) noexcept: Set the day part.

inline constexpr Weeks weeks() const noexcept: Access the week part.

CalendarDelta &setWeeks(Weeks value) noexcept: Set the week part.

inline constexpr Months months() const noexcept: Access the month part.

CalendarDelta &setMonths(Months value) noexcept: Set the month part.

inline constexpr Years years() const noexcept: Access the year part.

CalendarDelta &setYears(Years value) noexcept: Set the year part.

std::optional<TimeDelta> toTimeDelta() const noexcept: Convert to a fixed TimeDelta if all parts can be represented exactly.

TimeDelta toTimeDeltaOrThrow() const

Convert to a fixed TimeDelta.

Throws:: err::OverflowError – if calendar units are present or the fixed sum exceeds TimeDelta bounds.

text::String toString(const TimeDeltaFormat &format = {}) const: Convert this value to text.

struct CalendarDeltaParts

Store all independently configurable calendar-delta parts.

Public Members

Nanoseconds nanoseconds: The nanosecond part.

Microseconds microseconds: The microsecond part.

Milliseconds milliseconds: The millisecond part.

Seconds seconds: The second part.

Minutes minutes: The minute part.

Hours hours: The hour part.

Days days: The day part.

Weeks weeks: The week part.

Months months: The month part.

Years years: The year part.

struct YearDayOfYearParts

A year and a zero-based day-of-year amount.

Used by calendar extraction helpers that split an epoch day count into the containing year and the remaining day offset within that year.

Public Members

Year year: The extracted year.

Days dayOfYear: The zero-based day offset within year.

struct YearMonthParts

A year and month pair.

Used by month navigation helpers that may cross a year boundary.

Public Members

Year year: The year of the month.

Month month: The month in year.

struct MonthDayParts

A month and day pair.

Used by calendar extraction helpers that resolve a day-of-year value into month and day components.

Public Members

Month month: The extracted month.

Day day: The day within month.

struct DateParts

A calendar date split into named parts.

Public Members

Year year: The year component.

Month month: The month component.

Day day: The day component.

class Date

A date in the proleptic Gregorian calendar using 0000-01-01 as epoch.

Supports years 0-9999. Invalid dates are represented by a special internal value and sort before all valid dates in comparisons.

See: Date and Time

Public Functions

Date() noexcept = default: Create an invalid date.

Date(Year year, Month month, Day day) noexcept

Create a date from parts, or an invalid date if the parts do not exist.

The year, month and day part types clamp their raw construction input first. The resulting combination is then checked as a real calendar date; for example, February 31st becomes an invalid date.

Parameters:

year – The year.
month – The month.
day – The day.

Date(Day day, Month month, Year year) noexcept: This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Date(Year year, Day day, Month month) noexcept: This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

std::strong_ordering operator<=>(const Date &other) const noexcept = default: Compare dates. Invalid dates sort before valid dates.

inline constexpr bool isValid() const noexcept

Test if this date is valid.

Returns:: true if the date represents a real calendar date.

bool isFirst() const noexcept

Test if this is the first valid date (epoch).

Returns:: true if this is 0000-01-01.

bool isLast() const noexcept

Test if this is the last valid date (9999-12-31).

Returns:: true if this is the maximum supported date.

bool wouldAddSaturate(Days days) const

Test if adding the given number of days would saturate the date to the first/last valid date.

The method only returns true if the date is clamped to the first or last valid date, not if it ends naturally on the first or last day of the year. Returns false for invalid dates.

Parameters:: days – The number of days to add.
Returns:: true if the date would saturate to the first or last valid date.

bool wouldAddSaturate(Months months) const

Test if adding months would saturate the date to the first/last valid date.

Returns false for invalid dates.

Parameters:: months – The number of months to add.
Returns:: true if the date would saturate to the first or last valid date.

bool wouldAddSaturate(Years years) const

Test if adding years would saturate the date to the first/last valid date.

Returns false for invalid dates.

Parameters:: years – The number of years to add.
Returns:: true if the date would saturate to the first or last valid date.

Year year() const noexcept

Get the year, or zero for invalid dates.

Returns:: The year component.

Month month() const noexcept

Get the month, or January for invalid dates.

Returns:: The month component.

Day day() const noexcept

Get the day, or one for invalid dates.

Returns:: The day component.

DayOfYear dayOfYear() const noexcept

Get the one-based day of year.

Returns:: The day of year (1-366).

DayOfWeek dayOfWeek() const noexcept

Get the day of week.

Returns:: The day of week (Monday - Sunday).

DateParts parts() const noexcept

Get all date parts.

For invalid dates, returns 0000-01-01, matching the individual accessors.

Returns:: Named year, month, and day parts.

Date added(Days amount) const noexcept

Return this date plus amount days, clamped to valid bounds.

Invalid dates stay invalid.

Parameters:: amount – The number of days to add.
Returns:: The resulting date.

Date addedOrThrow(Days amount) const

Return this date plus amount days.

Invalid dates stay invalid.

Parameters:: amount – The number of days to add.
Throws:: err::OverflowError – if the result would be outside the supported date range.
Returns:: The resulting date.

Date added(Months amount) const noexcept

Return this date plus amount months, clamped to valid bounds.

Invalid dates stay invalid. A day is clamped to the largest possible day of the resulting month.

Parameters:: amount – The number of months to add.
Returns:: The resulting date.

Date addedOrThrow(Months amount) const

Return this date plus amount months.

Invalid dates stay invalid. A day is clamped to the largest possible day of the resulting month.

Parameters:: amount – The number of months to add.
Throws:: err::OverflowError – if the result would be outside the supported date range.
Returns:: The resulting date.

Date added(Years amount) const noexcept

Return this date plus amount years, clamped to valid bounds.

Invalid dates stay invalid.

Parameters:: amount – The number of years to add.
Returns:: The resulting date.

Date addedOrThrow(Years amount) const

Return this date plus amount years.

Invalid dates stay invalid.

Parameters:: amount – The number of years to add.
Throws:: err::OverflowError – if the result would be outside the supported date range.
Returns:: The resulting date.

void add(Days amount) noexcept

Add days in place.

Parameters:: amount – The number of days to add.

void addOrThrow(Days amount)

Add days in place.

Parameters:: amount – The number of days to add.
Throws:: err::OverflowError – if the result would be outside the supported date range.

void add(Months amount) noexcept

Add months in place.

A day is clamped to the largest possible day of the resulting month.

Parameters:: amount – The number of months to add.

void addOrThrow(Months amount)

Add months in place.

A day is clamped to the largest possible day of the resulting month.

Parameters:: amount – The number of months to add.
Throws:: err::OverflowError – if the result would be outside the supported date range.

void add(Years amount) noexcept

Add years in place.

Parameters:: amount – The number of years to add.

void addOrThrow(Years amount)

Add years in place.

Parameters:: amount – The number of years to add.
Throws:: err::OverflowError – if the result would be outside the supported date range.

Date next() const noexcept

Return the following date, or invalid past the supported range.

Returns:: The next calendar day.

Date previous() const noexcept

Return the previous date, or invalid before the supported range.

Returns:: The previous calendar day.

Date next(DayOfWeek dayOfWeek) const noexcept: Return the next requested day of week, or an invalid date if this date is invalid.

Date previous(DayOfWeek dayOfWeek) const noexcept: Return the previous requested day of week, or an invalid date if this date is invalid.

text::String toString() const

Convert this date to its canonical human-readable representation.

Invalid dates return an empty string.

Returns:: The date formatted as YYYY-MM-DD.

inline Days toDaysSinceEpoch() const noexcept: Convert to days since epoch, or -1 for invalid dates.

Days daysTo(Date other) const noexcept

Calculate the number of days to another date.

Returns zero if either date is invalid.

auto toIsoString(IsoTimeFormatFlags flags = cDefaultDateFormat, DateTimePrecision precision = DateTimePrecision::Day) const -> text::String 

Convert this date to an ISO 8601 string.

Invalid dates return an empty string.

Parameters:

flags – Formatting flags for the output.
precision – The largest precision to include.

Returns:

The ISO-formatted date string.

Public Static Functions

static Date fromYearMonthDay(int year, int month, int day) noexcept

Create a date from raw integer parts.

Parameters:

year – The year (0-9999).
month – The month (1-12).
day – The day (1-31).

Returns:

A valid date if the parts form a real calendar date, otherwise invalid.

static Date fromYearMonthDayOrThrow(int year, int month, int day)

Create a date from raw integer parts or throw.

Parameters:

year – The year (0-9999).
month – The month (1-12).
day – The day (1-31).

Throws:

err::OutOfRangeError – if the parts do not form a valid date.

Returns:

A valid date.

static Date fromParts(Year year, Month month = Month{}, Day day = Day{}) noexcept

Create a date from typed parts.

Parameters:

year – The year.
month – The month, defaults to January.
day – The day, defaults to the first.

Returns:

A valid date if the parts form a real calendar date, otherwise invalid.

static Date fromPartsOrThrow(Year year, Month month = Month{}, Day day = Day{})

Create a date from typed parts or throw.

Parameters:

year – The year.
month – The month, defaults to January.
day – The day, defaults to the first.

Throws:

err::OutOfRangeError – if the parts do not form a valid date.

Returns:

A valid date.

static Date fromDaysSinceEpoch(Days days) noexcept

Create a date from days since epoch.

Parameters:: days – The number of days since epoch.
Returns:: A valid date if within range, otherwise invalid.

static bool exists(Year year, Month month, Day day) noexcept

Test if date parts form an existing date.

Parameters:

year – The year.
month – The month.
day – The day.

Returns:

true if the parts form a valid calendar date.

static Date firstDay(Year year) noexcept

Return first day in a year.

Parameters:: year – The year.
Returns:: January 1st of the given year.

static Date firstDay(Year year, Month month) noexcept

Return first day in a month.

Parameters:

year – The year.
month – The month.

Returns:

The first day of the given month.

static Date lastDay(Year year) noexcept

Return last day in a year.

Parameters:: year – The year.
Returns:: December 31st of the given year.

static Date lastDay(Year year, Month month) noexcept

Return last day in a month.

Parameters:

year – The year.
month – The month.

Returns:

The last day of the given month.

static Date epoch() noexcept

Return the epoch date.

Returns:: 0000-01-01.

static Date first() noexcept: Return first supported date.

static Date last() noexcept

Return the last supported date (9999-12-31).

Returns:: The maximum date.

class DateTime

A point in time represented as UTC date/time plus display offset information.

See: Date and Time

Public Functions

DateTime() noexcept = default: Create an invalid date/time.

inline DateTime(const Date utcDate, const Time utcTime) noexcept

Create a UTC date/time.

If utcDate is invalid, the resulting date/time is invalid and its time and offset are reset.

Parameters:

utcDate – The date.
utcTime – The time in the UTC timezone.

DateTime(Date localDate, Time localTime, Seconds offset) noexcept

Create a fixed-offset local date/time.

Invalid local dates result in an invalid date/time. Offsets are normalized into the supported UTC offset range.

Parameters:

localDate – The local date.
localTime – The local time.
offset – The UTC offset.

inline DateTime(const Date localDate, const Time localTime, const Duration offset) noexcept

Create a fixed-offset local date/time.

Parameters:

localDate – The local date.
localTime – The local time.
offset – The UTC offset.

DateTime(Date localDate, TimeWithZone localTime, TimeOccurrenceInFold occurrence = TimeOccurrenceInFold::First) noexcept

Create a local date/time from a time with a time zone.

Invalid local dates result in an invalid date/time.

Parameters:

localDate – The local date.
localTime – The local time and its time zone.
occurrence – Which occurrence to use during fold periods.

DateTime(Date localDate, Time localTime, TimeZone timeZone, TimeOccurrenceInFold occurrence = TimeOccurrenceInFold::First) noexcept

Create a named-zone local date/time.

Invalid local dates result in an invalid date/time. During folds, occurrence selects the first or second possible instant; local times in gaps are resolved using the zone database transition rule.

Parameters:

localDate – The local date.
localTime – The local time.
timeZone – The time zone.
occurrence – Which occurrence to use during fold periods.

std::strong_ordering operator<=>(const DateTime &other) const noexcept: Compare two date/time values by their instant and display properties.

inline DateTime operator+(const Duration duration) const noexcept: Return this date/time with a duration added.

inline DateTime &operator+=(const Duration duration) noexcept: Add a duration to this date/time.

inline DateTime operator-(const Duration duration) const noexcept: Return this date/time with a duration subtracted.

inline DateTime &operator-=(const Duration duration) noexcept: Subtract a duration from this date/time.

inline Duration operator-(const DateTime &other) const noexcept

Return the signed duration from other to this date/time.

Parameters:: other – The other date/time.
Returns:: The duration from other to this.

inline DateTime operator+(const CalendarDelta &delta) const noexcept: Return this date/time with a calendar delta added.

inline DateTime &operator+=(const CalendarDelta &delta) noexcept: Add a calendar delta to this date/time.

inline DateTime operator-(const CalendarDelta &delta) const noexcept: Return this date/time with a calendar delta subtracted.

inline DateTime &operator-=(const CalendarDelta &delta) noexcept: Subtract a calendar delta from this date/time.

inline constexpr bool isValid() const noexcept: Test if this date/time represents a valid instant.

inline constexpr bool isUtc() const noexcept: Test if this date/time is displayed in UTC.

inline constexpr bool isLocalTime() const noexcept: Test if the display zone originated from the system-local setting.

inline constexpr Date utcDate() const noexcept: Return the stored UTC date, or an invalid date for invalid date/times.

inline constexpr Time utcTime() const noexcept: Return the stored UTC time, or midnight for invalid date/times.

inline Date date() const noexcept: Return the local display date, or an invalid date for invalid date/times.

inline Time time() const noexcept: Return the local display time, or midnight for invalid date/times.

inline Year year() const noexcept: Return the local year, or zero for invalid date/times.

inline Month month() const noexcept: Return the local month, or January for invalid date/times.

inline Day day() const noexcept: Return the local day, or one for invalid date/times.

inline DayOfYear dayOfYear() const noexcept: Return the local day of year, or one for invalid date/times.

inline DayOfWeek dayOfWeek() const noexcept: Return the local day of week, or the epoch weekday for invalid date/times.

inline Hour hour() const noexcept: Return the local hour.

inline Minute minute() const noexcept: Return the local minute.

inline Second second() const noexcept: Return the local second.

inline Milliseconds millisecondFraction() const noexcept: Return the local millisecond fraction.

inline Nanoseconds nanosecondFraction() const noexcept: Return the local nanosecond fraction.

DateTimeParts parts() const noexcept

Return all local date/time parts.

For invalid date/times, returns the same fallback parts as the individual accessors.

inline Duration timeOffset() const noexcept: Return the display offset from UTC.

TimeZone timeZone() const noexcept: Return the display time zone, or UTC for invalid date/times and fixed offsets.

text::String timeZoneAbbreviation() const: Return the display time-zone abbreviation, or an empty string when none is available.

bool wouldAddSaturate(const CalendarDelta &delta) const noexcept: Test if applying a calendar delta would saturate the supported range.

bool wouldSubtractSaturate(const CalendarDelta &delta) const noexcept: Test if subtracting a calendar delta would saturate the supported range.

DateTime added(const CalendarDelta &delta) const noexcept: Apply a calendar delta in ascending unit order and clamp at supported bounds.

DateTime addedOrThrow(const CalendarDelta &delta) const

Apply a calendar delta in ascending unit order.

Throws:: err::OverflowError – if an intermediate result exceeds supported bounds.

inline void add(const CalendarDelta &delta) noexcept: Apply a calendar delta in place and clamp at supported bounds.

inline void addOrThrow(const CalendarDelta &delta)

Apply a calendar delta in place.

Throws:: err::OverflowError – if an intermediate result exceeds supported bounds.

inline DateTime subtracted(const CalendarDelta &delta) const noexcept: Subtract a calendar delta in ascending unit order and clamp at supported bounds.

inline DateTime subtractedOrThrow(const CalendarDelta &delta) const

Subtract a calendar delta in ascending unit order.

Throws:: err::OverflowError – if an intermediate result exceeds supported bounds.

inline void subtract(const CalendarDelta &delta) noexcept: Subtract a calendar delta in place and clamp at supported bounds.

inline void subtractOrThrow(const CalendarDelta &delta)

Subtract a calendar delta in place.

Throws:: err::OverflowError – if an intermediate result exceeds supported bounds.

bool wouldAddSaturate(Duration duration) const noexcept

Test if adding a duration would saturate to the first or last supported date/time.

Returns false for invalid date/times.

Parameters:: duration – The duration to add.
Returns:: true if the result would be clamped to the supported date/time range.

bool wouldSubtractSaturate(Duration duration) const noexcept

Test if subtracting a duration would saturate to the first or last supported date/time.

Returns false for invalid date/times.

Parameters:: duration – The duration to subtract.
Returns:: true if the result would be clamped to the supported date/time range.

DateTime added(Duration duration) const noexcept

Return this date/time plus a duration, clamped to the supported date/time range.