Dates and Time Overview

A calendar date, a time interval, and a timestamp describe different kinds of values. The time domain gives each of them its own type so that your code can retain the meaning of a value as it moves between calculations, display, and storage.

Choosing a Type

The types are available in erbsland::time and through the flattened el namespace used in the demos. Individual headers live under <erbsland/time/>; <erbsland/time/all.hpp> includes the domain.

Value	What it expresses	Typical task
Calendar and time parts	A position such as `Day{15}` or `Hour{9}`	Constructing or inspecting fields
Typed time amounts	A quantity such as `Days{15}` or `Hours{9}`	Making a unit explicit in an API
`Date` and `Time`	A calendar day or a reading within a clock day	Calendars and daily timetables
`Duration`	A signed fixed interval in whole seconds	Whole-second delays and long intervals
`TimeDelta`	A signed fixed interval in nanoseconds	Precise latency and interval calculations
`CalendarDelta`	Independent changes from nanoseconds through years	Combining fixed and calendar changes
`TimePoint`	A point on a monotonic clock with an unspecified epoch	Checkpoints and deadlines
`Timestamp`	A civil instant without display-zone information	Recording and exchanging event instants
`DateTime`	A UTC instant with a display zone or offset	Viewing an instant in a chosen zone
`TimeZone`	UTC, a fixed offset, or named rules, with optional local origin	Interpreting local input and choosing a display zone
`TimeWithZone`	An intended daily clock reading with its zone	Resolving local appointments on a chosen date

Constructing Dates and Times

Working with Dates starts with calendar dates, including typed construction, validation of supplied fields, calendar extraction, and text or day-count conversion. It also explains why default construction is invalid and how dates compare.

Working with Times covers daily clock readings, fractional seconds, and conversion to counts or intervals since midnight. It also explains how to retain the date change when a calculation wraps across midnight.

Working with UTC Timestamps explains recording and exchanging UTC instants, including canonical text, portable bytes, signed epoch counts, and precise distances. Working with DateTime Values covers resolving local input, choosing a display zone, comparing instants, and applying elapsed or calendar changes. Keeping a Wall-Clock Time with Its Zone explains retaining an undated local reading, resolving each occurrence, choosing fold occurrences, and checking skipped readings.

Choosing and Resolving Time Zones

Working with Time Zones covers UTC, fixed offsets, named zones and aliases, and the cached system-local setting. It explains interpreting local input versus converting an existing instant, daylight-saving gaps and folds, resolved offsets and labels, transient identifiers, and the bundled rule version. For recurring local readings, Keeping a Wall-Clock Time with Its Zone separates the stored wall-clock intention from the UTC instant selected on each date.

Expressing Amounts and Intervals

Working with Calendar and Time Parts explains typed positions, contextual validation, calendar navigation, weekday selection, ordinal conversion, and named result structures. A calendar part names a position, while an amount names a quantity: Day{15} selects a day of the month, and Days{15} represents fifteen days. Working with Typed Time Amounts explains the units from nanoseconds through years, signed quantities, compatible conversions, precision loss, and saturating arithmetic. Writing Time Values with Literals shows how the suffixes _ns, _us, _ms, _s, _m, and _h make common amounts readable and how to choose a shared representation for an expression; _m means minutes.

Working with Whole-Second Durations covers whole-second fixed spans, including construction from typed amounts or chrono values, signed arithmetic, splitting totals into components, and checked conversion to nanosecond precision. Working with Precise Time Intervals covers nanosecond intervals, typed and checked construction, signed calculations, integer ratios, saturation, and conversion of precise totals. Its TimeDelta preserves nanoseconds over a smaller range. Choose the required precision before converting: dropping fractional seconds can be intentional for a timeout, but misleading for a measurement. Fixed days and weeks have lengths of 86,400 seconds and seven such days; months and years need calendar context.

Calendar Calculations

The calculations in Working with Dates apply individual day, month, or year amounts to a date. They explain month-end adjustment and the choice between saturation and an explicit overflow error.

Understanding Calendar Changes explains composing independent components, applying them in order, month-end clamping, checked conversion, and intermediate overflow. It also distinguishes UTC calendar arithmetic from preserving an intended local wall-clock time across zone transitions.

Customizing ISO Date and Time Output

Customizing ISO Date and Time Output explains every IsoTimeFormat flag and DateTimePrecision level with matching examples for dates, standalone times, and combined readings. It covers separators, numeric UTC, second-level offsets, fixed-width fractions, and truncating displayed precision. Working with UTC Timestamps uses a fixed canonical UTC format for precise exchange.

For intervals, Customizing Time Interval Output explains format presets, unit names, separators, every smallest-unit choice, and the interaction of fractional visibility with digit limits. It also covers signed calendar-component display and ELCL serialization for TimeDelta and CalendarDelta. Formatting changes the text you present, rather than the value stored in the interval.

Measuring Elapsed Time

ElapsedTimer measures an operation from its starting point and returns a TimeDelta. TimePoint exposes monotonic checkpoints and deadlines when you need to retain or compare explicit points. Both use a monotonic clock, so changing the system’s civil clock does not change the meaning of your elapsed measurement. Measuring Elapsed Time covers cumulative readings, restarting between phases, timer copies, and cooperative processing budgets. Working with Monotonic Time Points covers explicit checkpoints, signed distances, shared deadlines, clock boundaries, and steady-clock interoperability.

Running the Topic Demos

The examples on these pages use the common demo framework. Their sources live in demos/time/Date, demos/time/Time, demos/time/Timestamp, demos/time/DateTime, demos/time/IsoTimeOutput, demos/time/Duration, demos/time/TimeLiterals, demos/time/TimeAmounts, demos/time/TimeDelta, demos/time/TimeDeltaOutput, demos/time/CalendarDelta, demos/time/CalendarParts, demos/time/ElapsedTimer, demos/time/TimePoint, demos/time/TimeWithZone, and demos/time/TimeZone. The doc-process-rst maintenance command synchronizes source and output when demo processing is explicitly enabled. From the repository root, build and select an individual example:

cmake -B cmake-build-debug -G Ninja -DCMAKE_BUILD_TYPE=Debug .
cmake --build cmake-build-debug --target date time timestamp date_time iso_time_output duration
cmake --build cmake-build-debug --target time_literals time_amounts time_delta time_delta_output
cmake --build cmake-build-debug --target calendar_delta calendar_parts elapsed_timer time_point
cmake --build cmake-build-debug --target time_with_zone time_zone
cmake-build-debug/demo-apps/time/date --demo Calculate
cmake-build-debug/demo-apps/time/time --demo Wrap
cmake-build-debug/demo-apps/time/timestamp --demo Ticks
cmake-build-debug/demo-apps/time/date_time --demo Zones
cmake-build-debug/demo-apps/time/iso_time_output --demo Precision
cmake-build-debug/demo-apps/time/duration --demo Parts
cmake-build-debug/demo-apps/time/time_literals --demo Expressions
cmake-build-debug/demo-apps/time/time_amounts --demo Convert
cmake-build-debug/demo-apps/time/time_delta --demo Calculate
cmake-build-debug/demo-apps/time/time_delta_output --demo Precision
cmake-build-debug/demo-apps/time/calendar_delta --demo Apply
cmake-build-debug/demo-apps/time/calendar_parts --demo Navigate
cmake-build-debug/demo-apps/time/elapsed_timer --demo Phases
cmake-build-debug/demo-apps/time/time_point --demo Deadline
cmake-build-debug/demo-apps/time/time_with_zone --demo Recurrence
cmake-build-debug/demo-apps/time/time_zone --demo Transitions

Each executable also accepts --help and runs all its examples when no --demo is supplied.