Date and Time

Date and Time Types

Introduction

The time namespace provides types for working with civil dates, wall-clock times, and time spans. Calendar and clock parts are bounded labels; the aggregate result structures name related fields. Part/amount conversion uses offsets from the part’s minimum label, and numeric range checks do not validate calendar combinations. See Working with Calendar and Time Parts for construction, numbering, contextual validation, navigation, weekday selection, ordinal conversion, and field reconstruction.

Date

Date represents a proleptic Gregorian calendar date in 0000-01-01..9999-12-31, with Core epoch 0000-01-01. Default construction is invalid; invalid dates compare equal and sort before valid dates. Construction validates calendar combinations, and day, month, and year arithmetic offers saturating and throwing forms. See Working with Dates for construction choices, validation, field extraction, conversions, month-end adjustment, navigation, and boundary handling.

Date Time

DateTime retains a UTC instant plus resolved display-offset or named-zone metadata. It shares the date range 0000-01-01..9999-12-31 and retains nanosecond fractions. Ordering compares UTC instants; equality also compares display metadata. Tick conversion accepts nonnegative seconds, milliseconds, microseconds, or nanoseconds relative to TimeEpoch and truncates smaller fractions; split seconds/fractions retain full precision. Arithmetic applies Duration or CalendarDelta in UTC, with saturating, throwing, and overflow-test variants. The distance APIs use whole-second epoch readings; convert to Timestamp for precise checked distances. See Working with DateTime Values for construction, field extraction, zone resolution, conversion, and calculations, including folds, gaps, and local recurrences.

TimeWithZone retains a daily wall-clock reading with its intended zone. Default construction is midnight UTC; equality compares the stored reading and zone. It identifies an instant only after DateTime resolves it with a local date and, when needed, a fold occurrence. See Keeping a Wall-Clock Time with Its Zone for construction, accessors, compact output, transition handling, and local recurrences.

Time

Time represents a daily clock reading in 00:00:00..23:59:59.999999999. Default construction is midnight; there is no invalid sentinel, date, or zone. TimeParts names its component fields. Wrapping addition accepts Duration or TimeDelta and either returns a signed day carry or a TimeWrapResult containing the new time and carry. See Working with Times for construction, comparisons, precision-preserving conversions, and calculations across midnight.

Time Zone

TimeZone represents UTC, a normalized fixed offset, or a supported named IANA zone. Name lookup returns std::optional or throws err::ParseError; aliases resolve to the primary zone. Component construction clamps each signed component; total-duration construction removes complete 24-hour rotations. staticOffset() returns zero for named zones; DateTime::timeOffset() supplies an instant’s resolved shift. Equality includes zone identity and local origin.

local() caches the system’s base zone for the process lifetime, falling back to local-marked UTC. Named-zone offsets still resolve per date using the bundled IANA rules identified by databaseVersion(). Local origin is preserved by copies/arithmetic and replaced by the target marker on conversion. Default local-origin display omits the zone; explicit ISO TimeShift output includes the resolved shift.

TimeOccurrenceInFold selects the earlier (default First) or later (Second) UTC match for repeated local readings. Gap construction follows the database’s transition rule and can retain display metadata that differs from the selected instant’s refreshed zone metadata; isValid() does not detect skipped readings.

TimeZoneId and tz::TimeOffset::abbreviationId() are transient database indexes. tz::TimeOffset holds offset seconds, zone/DST/abbreviation metadata, and local origin; its constructors do not resolve named-zone rules. See Working with Time Zones for zone selection, lookup, conversion, transition resolution, system-local behavior, persistence choices, detail values, and rule-version queries.

ISO Date and Time Output

IsoTimeFormatFlags combines IsoTimeFormat flags for Date, Time, and DateTime ISO output. DateTimePrecision controls the last emitted field or fractional digit. Defaults use extended fields, whole seconds for time output, and a space without an offset for combined output. See Customizing ISO Date and Time Output for every flag, precision level, and option interaction. Timestamp uses its own fixed canonical UTC output; see UTC Timestamps.

Duration and Time Amounts

Introduction

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

<erbsland/time/TimeUnitTags.hpp> declares SecondsUnitTag, MonthsUnitTag, and YearsUnitTag for the dimensions of time amount types.

Time amounts from Nanoseconds through Years are signed 64-bit IntegerAmount aliases. Fixed units through weeks share a seconds dimension; months and years each have their own unit tag. Compatible conversions truncate toward zero and offer saturating, overflow-test, and throwing forms. See Working with Typed Time Amounts for unit selection, construction, conversion, arithmetic, and calendar application.

The integer suffixes in <erbsland/time/Literals.hpp> produce typed amounts in erbsland::time::literals and saturate oversized unsigned literal inputs to the signed maximum. See Writing Time Values with Literals for scope, suffix types, expressions, and precision limits.

Duration stores a signed 64-bit span in whole seconds, with saturating arithmetic and signed component extraction controlled by DurationPart. Sub-second inputs truncate toward zero; conversion to TimeDelta offers saturating, overflow-test, and throwing forms. See Working with Whole-Second Durations for construction, comparisons, both split-result structures, chrono interoperability, and precision/range tradeoffs.

TimeDelta stores a signed nanosecond interval with saturating arithmetic. Whole-unit conversions truncate toward zero; division by zero terminates. See Working with Precise Time Intervals for construction, checked factories, ratios, endpoint behavior, chrono interoperability, and exact versus approximate conversions.

CalendarDelta stores nanoseconds through years as independent signed components, with component equality and saturating component arithmetic. Application to DateTime runs from nanoseconds through years in UTC and retains the display zone. Fixed conversion requires zero month/year parts and representable components and intermediate sums; isValidTimeDelta() tests conversion success. See Understanding Calendar Changes for composition, application order, month-end clamping, local recurrences, boundary handling, and fixed conversion.

TimeDeltaFormat controls fixed and calendar interval presentation. It provides short, long, and ELCL presets, custom separators, a smallest fixed unit, and truncating fractional output. See Customizing Time Interval Output for every option, precision interactions, zero and sign handling, calendar normalization, and ELCL serialization.

Measuring Elapsed Time

ElapsedTimer starts a monotonic measurement on construction. elapsed() returns a cumulative TimeDelta; restart() replaces the starting point and returns no interval. Copies retain the starting point and can be restarted independently. See Measuring Elapsed Time for operation timing, phase measurements, time budgets, and interpretation of clock precision and measurement noise.

TimePoint wraps a std::chrono::steady_clock::time_point. Default construction selects the clock epoch; now() captures a reading and inFuture() offsets one from now. Subtraction returns signed intervals, comparison orders points, and toStdTimePoint() preserves the clock domain. Point offsets and differences must stay within the underlying clock’s representable range; point arithmetic does not saturate. See Working with Monotonic Time Points for checkpoints, interval direction, deadlines, clock-domain boundaries, and standard library interoperability.

Throwing epoch factories report negative ticks and invalid fractions with OutOfRangeError. Their non-throwing counterparts return no value.

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). Must form a valid calendar date with year and month.

Throws:

err::OutOfRangeError – If the parts do not form a supported calendar 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, defaulting to the first. Must form a valid calendar date with year and month.

Throws:

err::OutOfRangeError – If the parts do not form a supported calendar 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.