命名空间
变体
操作

std::filesystem::path

来自 cppreference.cn
 
C++
 
文件系统库
类
函数
文件类型
 
std::filesystem::path
成员类型
成员常量
成员函数
路径分解
非成员函数
(C++20前)(C++20前)(C++20前)(C++20前)(C++20前)(C++20起)
辅助类
 
定义于头文件 <filesystem>
class path;
 (C++17 起)

类型为 path 的对象表示文件系统上的路径。仅处理路径的语法方面：路径名可能表示一个不存在的路径，甚至是一个在当前文件系统或操作系统上不允许存在的路径。

路径名具有以下语法

  1. root-name(可选)：在具有多个根的文件系统（例如 "C:" 或 "//myserver"）上标识根。在有歧义的情况下，形成有效 root-name 的最长字符序列被视为 root-name。标准库除了操作系统 API 所理解的根名之外，还可以定义额外的根名。
  2. root-directory(可选)：一个目录分隔符，如果存在，则将此路径标记为绝对路径。如果它不存在（且除根名之外的第一个元素是文件名），则该路径是相对路径，需要另一个路径作为起始位置才能解析为文件名。
  3. 零个或多个以下内容
  • file-name：非目录分隔符或首选目录分隔符的字符序列（操作系统或文件系统可能会施加额外的限制）。此名称可以标识文件、硬链接、符号链接或目录。识别两个特殊的 file-name
  • dot：由一个点字符 . 组成的文件名是表示当前目录的目录名。
  • dot-dot：由两个点字符 .. 组成的文件名是表示父目录的目录名。
  • directory-separator：正斜杠字符 / 或作为 path::preferred_separator 提供的替代字符。如果此字符重复，则将其视为单个目录分隔符：/usr///////lib 与 /usr/lib 相同。

路径可以通过遵循以下算法进行规范化

  1. 如果路径为空，则停止（空路径的规范形式是空路径）。
  2. 将每个 directory-separator（可能由多个斜杠组成）替换为单个 path::preferred_separator。
  3. 将 root-name 中的每个斜杠字符替换为 path::preferred_separator。
  4. 删除每个 dot 及紧随其后的任何 directory-separator。
  5. 删除每个非 dot-dot 文件名，其后紧跟一个 directory-separator 和一个 dot-dot，以及紧随其后的任何 directory-separator。
  6. 如果存在 root-directory，则删除所有 dot-dot 和紧随其后的任何 directory-separator。
  7. 如果最后一个文件名是 dot-dot，则删除任何尾随的 directory-separator。
  8. 如果路径为空，则添加一个 dot（./ 的规范形式是 .）。

可以通过 begin() 和 end() 函数返回的迭代器逐元素遍历路径，这些迭代器以通用格式查看路径并迭代根名、根目录和后续的文件名元素（目录分隔符被跳过，除了标识根目录的那个）。如果路径中的最后一个元素是目录分隔符，则最后一个迭代器将解引用为空元素。

调用 path 的任何非 const 成员函数都会使引用该对象元素的任何迭代器失效。

如果操作系统使用与上述可移植通用语法不同的原生语法，则定义为接受“检测到的格式”的库函数接受两种格式的路径名：当且仅当检测到的格式参数与通用格式匹配但操作系统不接受其作为原生路径时，才将其视为通用格式。在原生格式在目录路径名和文件路径名之间有所不同的操作系统上，如果通用路径名以目录分隔符结尾，则将其视为目录路径，否则视为常规文件。

在任何情况下，路径类都表现为它以原生格式存储路径名，并根据需要自动转换为通用格式（每个成员函数都指定它将路径解释为哪种格式）。

在 POSIX 系统上，通用格式是原生格式，无需区分或转换它们。

路径可以隐式转换为 std::basic_string，反之亦然，这使得它们可以与其他文件 API 一起使用。

流运算符使用 std::quoted，这样在被 流输入运算符 读取时，空格不会导致截断。

分解成员函数（例如 extension）返回 filesystem::path 对象而不是其他 API 返回的字符串对象。

目录

[编辑] 成员类型

类型 定义
value_type 文件系统原生编码使用的字符类型：POSIX 上为 char，Windows 上为 wchar_t
string_type std::basic_string<value_type>
const_iterator 一个常量 LegacyInputIterator，其 value_type 为 path，满足 LegacyBidirectionalIterator 的所有要求，但对于类型为 const_iterator 的两个相等的可解引用迭代器 a 和 b，没有要求 *a 和 *b 引用相同的对象。

const_iterator 是否确实是一个 LegacyBidirectionalIterator 未指定

iterator const_iterator
确定如何解释路径名的字符串表示。

还定义了以下枚举器

名称 解释
native_format 原生路径名格式
generic_format 通用路径名格式
auto_format 实现定义的格式，可能时自动检测

(公共成员枚举)

[编辑] 成员常量

constexpr value_type preferred_separator
[静态]
 除可移植的 / 之外，可能使用的替代目录分隔符。在 Windows 上，这是反斜杠字符 \。在 POSIX 上，这与可移植分隔符相同，都是正斜杠 /
(公共静态成员常量) [编辑]

[编辑] 成员函数

 构造一个 path
(公共成员函数) [编辑]
 销毁一个 path 对象
(公共成员函数) [编辑]
 赋值另一个路径
(公共成员函数) [编辑]
 赋值内容
(公共成员函数) [编辑]
连接
 用目录分隔符向路径追加元素
(公共成员函数) [编辑]
 连接两个路径而不引入目录分隔符
(公共成员函数) [编辑]
修改器
 擦除内容
(公共成员函数) [编辑]
 将目录分隔符转换为首选目录分隔符
(公共成员函数) [编辑]
 删除文件名路径组件
(公共成员函数) [编辑]
 用另一个路径替换最后一个路径组件
(公共成员函数) [编辑]
 替换扩展名
(公共成员函数) [编辑]
 交换两个路径
(公共成员函数) [编辑]
格式观察器
 返回路径的原生版本
(公共成员函数) [编辑]
 返回转换为字符串的原生路径名格式的路径
(公共成员函数) [编辑]
 返回转换为字符串的通用路径名格式的路径
(公共成员函数) [编辑]
比较
 按字典顺序比较两个路径的词法表示
(公共成员函数) [编辑]
生成
 将路径转换为规范形式
将路径转换为相对形式
将路径转换为近似形式
(公共成员函数) [编辑]
分解
 返回路径的根名（如果存在）
(公共成员函数) [编辑]
 返回路径的根目录（如果存在）
(公共成员函数) [编辑]
 返回路径的根路径（如果存在）
(公共成员函数) [编辑]
 返回相对于根路径的路径
(公共成员函数) [编辑]
 返回父路径的路径
(公共成员函数) [编辑]
 返回文件名路径组件
(公共成员函数) [编辑]
 返回主文件名路径组件（不带最终扩展名的文件名）
(公共成员函数) [编辑]
 返回文件扩展名路径组件
(公共成员函数) [编辑]
查询
 检查路径是否为空
(公共成员函数) [编辑]
 检查相应路径元素是否不为空
(公共成员函数) [编辑]
 检查 root_path() 是否唯一标识文件系统位置
(公共成员函数) [编辑]
迭代器
 以元素序列的形式迭代访问路径
(公共成员函数) [编辑]

[编辑] 非成员函数

定义于命名空间 std::filesystem
(C++17)
 特化 std::swap 算法
(函数) [编辑]
(C++17)
 计算路径对象的哈希值
(函数) [编辑]
(C++17起)(C++17起)(C++20前)(C++17起)(C++20前)(C++17起)(C++20前)(C++17起)(C++20前)(C++17起)(C++20前)(C++20起)
 按字典顺序比较两个路径
(函数) [编辑]
(C++17)
 用目录分隔符连接两个路径
(函数) [编辑]
(C++17)
 对带引号的路径执行流输入和输出
(函数) [编辑]
(C++17)(C++20 中已弃用)
 从 UTF-8 编码源创建 path
(函数) [编辑]

[编辑] 辅助类

定义于命名空间 std
(C++17)
 std::filesystem::path 的哈希支持
(类模板特化) [编辑]
(C++26)
 filesystem::path 的格式化支持
(类模板特化) [编辑]

[编辑] 缺陷报告

下列更改行为的缺陷报告追溯地应用于以前出版的 C++ 标准。

缺陷报告 应用于 发布时的行为 正确的行为
LWG 3657 C++17 path 的 hash 已禁用 已启用
取自 "https://cppreference.cn/mwiki/index.php?title=cpp/filesystem/path&oldid=178501"