跳到主要内容

Turbo 文件系统库（turbo::files）— 使用指南与函数详情

Turbo 文件系统库 (turbo/files) 基于 C++17 std::filesystem 接口设计，并适配 Turbo 生态规范（不抛异常，统一返回 turbo::Status/turbo::Result<T>，类名使用 CamelCase，函数名使用 snake_case）。库提供跨平台的文件系统操作能力，涵盖路径处理、目录遍历、文件属性管理以及文件/目录操作等核心场景。

I. 核心类与枚举概览​

类/枚举核心功能
turbo::FilePath路径语法处理（构造、拼接、解析、规范化），不验证路径存在性
turbo::DirectoryEntry封装目录条目（文件/目录）的路径与状态，用于迭代器
turbo::DirectoryIterator非递归遍历目录下的所有条目
turbo::RecursiveDirectoryIterator递归遍历目录及子目录下的所有条目
turbo::FileStatus封装文件/目录状态（类型、权限、大小、修改时间等）
turbo::SpaceInfo磁盘空间信息（总容量、可用空间、已用空间）
turbo::FileType文件类型枚举（目录、普通文件、符号链接、块设备、字符设备等）
turbo::Perms文件权限枚举（读/写/执行，用户/组/其他）
turbo::CopyOptions文件/目录复制选项（覆盖、递归、保留权限等）
turbo::DirectoryOptions目录操作选项（是否跟随符号链接、跳过空目录等）
turbo::FileTimeType文件时间类型枚举（创建时间、最后访问时间、最后修改时间）

II. 核心功能与示例​

1. 路径操作 (turbo::FilePath)​

  • FilePath 仅处理路径语法，不验证路径是否存在。
  • 支持绝对路径、相对路径和规范路径。

核心函数​

函数名功能描述
FilePath(std::string_view path)构造路径对象（支持 Windows/Linux 本地格式）
append(std::string_view component)拼接子路径，自动处理分隔符
parent_path()获取父目录路径
filename()获取文件名（含扩展名）
stem()获取文件名（不含扩展名）
extension()获取文件扩展名
is_absolute()判断是否为绝对路径
is_relative()判断是否为相对路径
lexically_normal()规范化路径（去掉.、..）
lexically_absolute()转换为绝对路径（基于当前工作目录）

示例​

turbo::FilePath base("/home/user/docs");
turbo::FilePath file(base);
file.append("report.pdf");

std::cout << "Full path: " << file.string() << std::endl;
std::cout << "Parent: " << file.parent_path().string() << std::endl;
std::cout << "Filename: " << file.filename().string() << std::endl;
std::cout << "Stem: " << file.stem().string() << std::endl;
std::cout << "Extension: " << file.extension().string() << std::endl;

turbo::FilePath messy("/home/user/./docs/../downloads/photo.jpg");
turbo::FilePath normal = messy.lexically_normal();
std::cout << "Normalized: " << normal.string() << std::endl;

2. 目录遍历 (DirectoryIterator / RecursiveDirectoryIterator)​

  • DirectoryIterator：非递归遍历目录条目。
  • RecursiveDirectoryIterator：递归遍历目录及子目录条目。
  • 遍历结果为 DirectoryEntry，可获取路径和状态。

核心函数​

函数/接口功能描述
DirectoryIterator::open(path, opts)打开目录迭代器
RecursiveDirectoryIterator::open(path, opts)打开递归目录迭代器
DirectoryEntry::path()获取条目路径
DirectoryEntry::status()获取条目状态（Result<FileStatus>）
begin()/end()支持 range-based for 循环

示例​

// 非递归遍历
turbo::DirectoryIterator iter = turbo::DirectoryIterator::open(dir_path).value();
for (const auto& entry : iter) {
    if (!entry.ok()) continue;
    turbo::DirectoryEntry de = entry.value();
    std::cout << "Entry: " << de.path().string() << std::endl;
}

// 递归遍历
turbo::RecursiveDirectoryIterator riter = turbo::RecursiveDirectoryIterator::open(dir_path).value();
for (const auto& entry : riter) {
    if (!entry.ok()) continue;
    turbo::DirectoryEntry de = entry.value();
    std::cout << "Recursive Entry: " << de.path().string() << std::endl;
}

3. 文件状态与属性 (FileStatus / FileType / Perms)​

  • FileStatus：文件/目录核心属性（类型、权限、大小、修改时间等）。
  • FileType：文件类型枚举。
  • Perms：权限枚举。

核心函数​

函数名功能描述
turbo::status(path)获取文件状态（返回 Result<FileStatus>）
FileStatus::type()获取文件类型
FileStatus::permissions()获取文件权限
FileStatus::file_size()获取文件大小
FileStatus::last_write_time()获取最后修改时间
turbo::is_regular_file(path)判断是否普通文件
turbo::is_directory(path)判断是否目录
turbo::is_symlink(path)判断是否符号链接

示例​

turbo::FileStatus fs = turbo::status(file_path).value();
std::cout << "File type: " << (fs.type() == turbo::FileType::regular ? "Regular" : "Other") << std::endl;
std::cout << "Size: " << fs.file_size() << " bytes" << std::endl;
turbo::Perms perms = fs.permissions();
if ((perms & turbo::Perms::owner_read) != turbo::Perms::none) std::cout << "Owner readable" << std::endl;

4. 磁盘空间查询 (SpaceInfo)​

  • SpaceInfo：封装磁盘分区空间信息。
  • 使用 turbo::space(path) 获取分区空间信息。

核心函数​

函数名功能描述
turbo::space(path)获取分区空间信息（返回 Result<SpaceInfo>）
SpaceInfo::capacity总空间（字节）
SpaceInfo::free可用空间（字节，包括非特权用户不可用）
SpaceInfo::available可用空间（字节，非特权用户可用）

示例​

turbo::SpaceInfo si = turbo::space("/").value();
std::cout << "Total: " << si.capacity / (1024*1024*1024) << " GB" << std::endl;
std::cout << "Free: " << si.free / (1024*1024*1024) << " GB" << std::endl;
std::cout << "Available: " << si.available / (1024*1024*1024) << " GB" << std::endl;

5. 文件/目录操作（创建、删除、复制、移动）​

  • 所有操作返回 turbo::Status 或 turbo::Result<T>。
  • 支持 CopyOptions / DirectoryOptions 控制行为。

核心函数​

函数名功能描述
turbo::create_directory(path)创建单级目录
turbo::create_directories(path)递归创建多级目录
turbo::remove(path)删除文件或空目录
turbo::remove_all(path)递归删除目录（返回删除条目数量 Result<uint64_t>）
turbo::copy(src, dst, opts)复制文件/目录
turbo::rename(src, dst)重命名/移动文件或目录

示例​

turbo::create_directories("/home/user/test/dir1/dir2");
turbo::CopyOptions opts; opts.overwrite_existing = true;
turbo::copy("/home/user/docs/report.pdf", "/home/user/test/report_copy.pdf", opts);
turbo::rename("/home/user/test/report_copy.pdf", "/home/user/test/report_renamed.pdf");
turbo::remove("/home/user/test/report_renamed.pdf");
turbo::remove_all("/home/user/test"); // 删除整个 test 目录

III. 使用注意事项​

  1. 跨平台兼容：FilePath 自动适配 Windows/Linux/macOS 路径格式；
  2. 错误处理：所有操作返回 Status/Result<T>，通过 ok() 检查成功，避免依赖异常；
  3. 路径有效性：FilePath 仅处理语法，使用 turbo::exists(path) 验证路径存在性；
  4. 权限与特殊文件：操作符号链接或设备文件时，通过 DirectoryOptions 指定是否跟随符号链接；
  5. 性能优化：大目录递归遍历优先使用 RecursiveDirectoryIterator，避免手动递归带来的性能损耗。