Timestamp时间戳

Timestamp是一款专注于时间戳高效处理的轻量级C++工具库，支持微秒级精度时间获取与多格式输出，适用于日志系统、文件命名、时间戳记录等场景，可跨Windows与Linux平台使用。

核心功能特点

高精度时间获取：支持获取当前微秒级时间戳，满足对时间精度要求较高的场景（如高频日志、性能统计）。
多格式格式化输出：
标准可读格式：YYYY/MM/DD HH:MM:SS.微秒（例： 2025/11/23 17:45:09.812002 ），适合人类阅读与日志记录；
文件友好格式：YYYYMMDD-HHMMSS.微秒（例： 20251123-174509.812002 ），无特殊字符，可直接作为文件名避免系统兼容问题。
时间戳有效性校验：通过vaild()方法判断时间戳是否有效（微秒数>0 即为有效），规避无效时间数据。
多粒度数值获取：支持直接获取微秒级（getMicroSec()）与秒级（getSeconds()）时间数值，便于时间差计算、时间戳存储等场景。
跨平台兼容： Linux 系统依赖gettimeofday实现， Windows 系统基于std::chrono开发，无需额外依赖即可在双平台运行。

项目文件结构

项目结构清晰，核心代码与配置文件分层存放，便于集成与二次开发：

Timestamp/                  # 项目根目录
├── logsys/                 # 核心功能目录（封装时间戳处理逻辑）
│   ├── include/            # 头文件目录（对外提供接口）
│   │   └── Timestamp.hpp   # 类声明：包含Timestamp类的方法、成员变量定义
│   └── src/                # 实现文件目录
│       └── Timestamp.cpp   # 类实现：所有方法的具体逻辑代码
├── Timestamp.cpp           # 测试程序：演示时间戳获取、格式化输出的完整用法
├── CMakeLists.txt          # 构建配置文件：支持CMake≥3.10，自动适配双平台编译
├── LICENSE.txt             # 开源协议：MIT协议，允许商用与二次修改
└── README.md               # 项目说明：包含快速上手、功能介绍等文档

编译与运行指南

前置环境要求

编译工具： CMake （版本≥3.10 ）、 C++编译器（ Linux/macOS 用 g++/clang ， Windows 用 MSVC （ Visual Studio 内置））；
系统支持： Linux （任意发行版）、 Windows （ Windows 10 及以上）、 macOS （可选，兼容 Linux 编译逻辑）。

编译步骤（通用流程）

克隆项目（或下载源码压缩包解压）：

1 2	git clone https://github.com/shanchuann/Timestamp.git cd Timestamp

创建并进入构建目录（推荐_out-of-source_构建，避免污染源码目录）：

1	mkdir build && cd build

CMake 配置：根据当前系统自动生成编译配置文件（ Makefile 或 Visual Studio 工程）：

1	cmake .. # ".." 表示指向项目根目录的CMakeLists.txt

执行编译：

Linux/macOS：使用make编译，编译完成后可执行文件生成在bin/目录：

make

Windows：通过 CMake 调用 MSVC 编译，可执行文件生成在bin/Debug/目录（ Debug 模式）：

1	cmake --build . # "." 表示当前构建目录

运行测试程序

编译完成后，通过以下命令运行测试程序，验证功能是否正常：

Linux/macOS：

1	./bin/Timestamp

Windows：

1	.\bin\Debug\Timestamp.exe

预期输出结果

运行后将打印两行时间字符串（具体时间随系统时间变化），分别对应标准格式与文件友好格式：

1 2	2025/11/23 17:45:09.812002 # 标准可读格式 20251123-174509.812002 # 文件友好格式

快速使用示例

以下是Timestamp.cpp中的核心示例代码，展示如何在项目中集成并使用 Timestamp 类：

// 1. 引入头文件（需确保项目能找到logsys/include目录）
#include "Timestamp.hpp"
// 2. 引入标准输入输出库（用于打印结果）
#include <iostream>

int main()
{
    // 3. 获取当前微秒级时间戳：通过静态方法Now()创建Timestamp对象
    logsys::Timestamp currentTime = logsys::Timestamp::Now();

    // 4. 校验时间戳有效性：避免使用无效时间（如未初始化的对象）
    if (currentTime.vaild()) {
        // 5. 输出标准格式时间字符串（适合日志）
        std::cout << "标准格式时间：" << currentTime.toFormattedString() << std::endl;
        // 6. 输出文件友好格式字符串（适合作为文件名）
        std::cout << "文件友好格式：" << currentTime.toFileString() << std::endl;
        
        // 7. 获取时间数值（可选：用于时间计算或存储）
        std::cout << "微秒级时间戳：" << currentTime.getMicroSec() << std::endl;
        std::cout << "秒级时间戳：" << currentTime.getSeconds() << std::endl;
    } else {
        std::cout << "时间戳无效！" << std::endl;
    }

    return 0;
}

类方法详细说明

Timestamp 类的所有公开方法均封装在logsys命名空间下，功能与使用场景如下表所示：

方法名	方法类型	功能描述	使用场景示例
`Timestamp::Now()`	静态方法	返回当前时间的 Timestamp 对象，精度为微秒级	获取当前时间：`auto t = Timestamp::Now();`
`Timestamp::invalid()`	静态方法	返回一个无效的 Timestamp 对象（微秒数=0 ），用于初始化或判断基准	初始化变量：`Timestamp t = Timestamp::invalid();`
`vaild()`	成员方法	判断当前时间戳是否有效（返回`true`表示有效，即微秒数>0 ）	校验时间：`if (t.vaild()) { ... }`
`toFormattedString()`	成员方法	返回标准可读格式字符串，格式为`YYYY/MM/DD HH:MM:SS.微秒`	日志记录、控制台打印
`toFileString()`	成员方法	返回文件友好格式字符串，格式为`YYYYMMDD-HHMMSS.微秒`	生成唯一文件名（如日志文件）
`getMicroSec()`	成员方法	返回微秒级时间数值（从 1970-01-01 00:00:00 UTC 到当前的微秒数）	时间差计算、高精度时间存储
`getSeconds()`	成员方法	返回秒级时间数值（向下取整，从 1970-01-01 00:00:00 UTC 到当前的秒数）	粗略时间比较、 Unix 时间戳兼容
`swap()`	成员方法	交换当前对象与另一个 Timestamp 对象的时间戳数据（参数为引用）	高效交换时间数据：`t1.swap(t2);`

注意事项

时间戳基准：所有时间计算基于Unix 时间戳（起始时间为 1970 年 1 月 1 日 00:00:00 UTC ），不支持 1970 年之前的时间。
时区设置：默认使用本地时间（ Linux 通过localtime_r、 Windows 通过localtime_s获取），若需 UTC 时间，可修改源码中“本地时间转换”相关代码，将localtime_r/localtime_s替换为gmtime_r（跨平台通用）。
微秒精度差异：不同系统的时间精度可能略有差异，微秒部分输出通常为 6 位数字（不足补 0 ），但极端情况下可能少于 6 位，不影响时间准确性。
Linux 依赖说明： Linux 系统下依赖gettimeofday函数（属于 POSIX 标准），若需在嵌入式 Linux 等特殊环境使用，需确保系统支持该函数。
版本更新：项目最新版本（ Timestamp for Windows ）已优化 Windows 平台兼容性，建议从仓库获取最新源码以避免历史版本的兼容性问题。