Chapter 13: DateTime, Duration, and Timing

This chapter distinguishes local wall-clock text, elapsed intervals, and monotonic timing, and documents the exact STTNet return types.

1. Responsibilities of DateTime and Duration

Type	Responsibility	It is not
`stt::time::DateTime`	Local time text, format conversion, text arithmetic, and monotonic timing	A Unix timestamp value type
`stt::time::Duration`	A non-negative interval with comparison, arithmetic, and unit conversion	An absolute date or `std::chrono::duration`

Exact return types: checkTime(), endTiming(), and getDt() all return stt::time::Duration. An integer millisecond value is available through convertToMsec().

2. Read local wall-clock text

std::string now;
// getTime() modifies now and returns a reference to it.
stt::time::DateTime::getTime(now, ISO8086B);

std::string display = now;
// convertFormat() modifies display in place and returns false on mismatch.
if(!stt::time::DateTime::convertFormat(
       display, ISO8086B, "yyyy/mm/dd hh:mi:ss.sss"))
{
    // Handle invalid text or format.
}

ISO8086A and ISO8086B are historical STTNet macro names for local text with and without milliseconds. They carry no Z suffix or UTC offset and are not complete ISO 8601 timestamps.

3. Construct and convert Duration

// Constructor order: day, hour, minute, second, millisecond.
const stt::time::Duration retryDelay(0, 0, 1, 30, 0);

const long long milliseconds = retryDelay.convertToMsec(); // 90000
const double seconds = retryDelay.convertToSec();           // 90.0

A default-constructed Duration represents zero milliseconds.
All five fields set to -1 represent the invalid sentinel; isValid() reports that state.
Comparison and arithmetic use total milliseconds. A negative subtraction, invalid input, or overflow produces an invalid value.
recoverForm(totalMs) modifies the current object and expands milliseconds into fields.

4. Timing returns Duration

stt::time::DateTime timer;
if(!timer.startTiming())
    return 1;

const stt::time::Duration current = timer.checkTime(); // Keep running.
const stt::time::Duration total = timer.endTiming();   // Stop and save.

if(total.isValid())
    std::cout << total.convertToMsec() << " ms\n";

const stt::time::Duration saved = timer.getDt();

The timer uses std::chrono::steady_clock, so wall-clock adjustments leave elapsed time unchanged. Calling checkTime() or endTiming() before startTiming() returns an invalid Duration.

5. Subtract local time text

stt::time::Duration difference;
stt::time::DateTime::calculateTime(
    "2026-07-15T12:01:30.250",
    "2026-07-15T12:00:00.000",
    difference,
    ISO8086B,
    ISO8086B);

if(!difference.isValid())
{
    // Invalid date, format mismatch, or time1 earlier than time2.
}

This overload writes to and returns a Duration&. The current interval model is non-negative; reverse subtraction returns the invalid sentinel rather than a negative duration.

Responsibility boundary: local time text is used for human-readable logs; monotonic Duration values represent deadlines and latency; cross-machine timestamps use an explicitly zoned standard representation or Unix time at the application layer.

Complete time utility demo →