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/目录：
  1
  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平台兼容性，建议从仓库获取最新源码以避免历史版本的兼容性问题。