第 13 章：时间、Duration 与计时

本章说明本地时间文本、时间间隔和单调计时的区别，以及相关接口的真实返回类型。

1. DateTime 与 Duration 的职责

类型	职责	不是什么
`stt::time::DateTime`	获取/转换本地时间文本；进行时间文本运算；使用单调时钟计时	不是 Unix 时间戳值类型
`stt::time::Duration`	表示非负时间间隔，并提供比较、加减和单位换算	不是绝对日期，也不是 `std::chrono::duration`

返回类型：checkTime()、endTiming()、getDt() 都返回 stt::time::Duration。Duration::convertToMsec() 可将结果换算为总毫秒数。

2. 获取当前本地时间文本

std::string now;
// getTime() 修改 now，并返回 now 的引用。
stt::time::DateTime::getTime(now, ISO8086B);

std::string display = now;
// convertFormat() 原地修改 display；输入与 oldFormat 不匹配时返回 false。
if(!stt::time::DateTime::convertFormat(
       display, ISO8086B, "yyyy/mm/dd hh:mi:ss.sss"))
{
    // 处理格式错误。
}

ISO8086A 和 ISO8086B 是 STTNet 保留的历史宏名，分别对应不带/带毫秒的本地时间文本。文本不包含 Z 或时区偏移，因此不属于完整的 ISO 8601 时间戳。

3. Duration 的构造与换算

// 构造参数顺序固定为：天、小时、分钟、秒、毫秒。
const stt::time::Duration retryDelay(0, 0, 1, 30, 0);

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

默认构造的 Duration 表示 0 毫秒。
五个字段全为 -1 表示无效值，可用 isValid() 判断。
比较和加减按总毫秒计算；负的减法结果、无效输入或溢出返回无效值。
recoverForm(totalMs) 会修改当前对象，把总毫秒拆成日、时、分、秒和毫秒。

4. 计时返回的是 Duration

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

// 查看当前耗时，但不停止计时。
const stt::time::Duration current = timer.checkTime();

// 停止计时并返回总耗时；返回值仍然是 Duration。
const stt::time::Duration total = timer.endTiming();

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

// getDt() 返回上一次 endTiming() 保存的 Duration。
const stt::time::Duration saved = timer.getDt();

计时内部使用 std::chrono::steady_clock，系统校时不会让耗时倒退。未调用 startTiming() 就执行 checkTime() 或 endTiming()，会返回无效 Duration。

5. 两个时间文本相减

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())
{
    // 日期非法、格式不匹配，或第一个时间早于第二个时间。
}

这个重载把结果写入 Duration& 并返回该引用。当前模型只表示非负间隔，所以反向相减不会返回负 Duration，而是返回无效值。

职责边界：日志展示使用本地时间文本；超时、延迟和重试间隔使用 Duration 与单调计时；跨机器时间使用带时区的标准格式或 Unix 时间戳，并由业务层明确时区。

完整时间工具 Demo →