std::filesystem::path
定义在头文件 <filesystem> 中 |
||
class path; |
(自 C++17 起) | |
path
类型的对象表示文件系统上的路径。仅处理路径的语法方面:路径名可能表示不存在的路径,甚至可能表示在当前文件系统或操作系统上不允许存在的路径。
路径名具有以下语法
- 根名称(可选): 标识具有多个根的文件系统上的根 (例如 "C:" 或 "//myserver")。如果存在歧义,则形成有效 根名称 的最长字符序列将被视为 根名称。标准库可能会定义除了操作系统 API 理解的根名称以外的附加根名称。
- 根目录(可选): 一个目录分隔符,如果存在,则将此路径标记为绝对路径。如果缺少 (并且根名称以外的第一个元素是文件名),则路径为相对路径,需要另一个路径作为起始位置才能解析为文件名。
- 以下内容的零个或多个
- 文件名: 不包含目录分隔符或首选目录分隔符的字符序列 (操作系统或文件系统可能会施加其他限制)。此名称可能标识文件、硬链接、符号链接或目录。识别两个特殊的 文件名
- 点: 由单个点字符 . 组成的文件名是一个目录名称,它引用当前目录。
- 点点: 由两个点字符 .. 组成的文件名是一个目录名称,它引用父目录。
- 目录分隔符: 正斜杠字符 / 或作为
path::preferred_separator
提供的备用字符。如果此字符重复,则将其视为单个目录分隔符:/usr///////lib 与 /usr/lib 相同。
可以按照以下算法规范化路径
- 如果路径为空,则停止 (空路径的规范形式是空路径)。
- 将每个 目录分隔符 (可能由多个斜杠组成) 替换为单个
path::preferred_separator
。 - 将 根名称 中的每个斜杠字符替换为
path::preferred_separator
。 - 删除每个 点 和其后的任何 目录分隔符。
- 删除每个紧随其后是 目录分隔符 和 点点 的非 点点 文件名,以及紧随其后的任何 目录分隔符。
- 如果有 根目录,则删除所有 点点 以及紧随其后的任何 目录分隔符。
- 如果最后一个文件名是 点点,则删除任何尾随的 目录分隔符。
- 如果路径为空,则添加一个 点 (./ 的规范形式是 .)。
可以通过 begin() 和 end() 函数返回的迭代器逐个元素遍历路径,这些函数以通用格式查看路径并迭代根名称、根目录以及随后的文件名元素 (除标识根目录的目录分隔符外,其他目录分隔符将被跳过)。如果路径中的最后一个元素是目录分隔符,则最后一个迭代器将解除引用为空元素。
调用 path
的任何非 const 成员函数都会使所有引用该对象元素的迭代器失效。
如果操作系统使用与上面描述的便携式通用语法不同的本机语法,则定义为接受“检测到的格式”的库函数接受两种格式的路径名:当且仅当检测到的格式参数与通用格式匹配但操作系统无法接受为本机路径时,它被认为处于通用格式。在那些本机格式在目录路径名和文件路径名之间不同的操作系统上,如果通用路径名以目录分隔符结尾,则将其视为目录路径,否则将其视为常规文件。
无论如何,path 类都表现得好像它以本机格式存储路径名,并在需要时自动转换为通用格式 (每个成员函数都指定它将路径解释为哪种格式)。
在 POSIX 系统上,通用格式是本机格式,无需在两者之间进行区分或转换。
路径可以隐式转换为 std::basic_string,反之亦然,这使得可以使用其他文件 API。
流运算符 使用 std::quoted,以便空格在稍后由 流输入运算符 读取时不会导致截断。
分解成员函数 (例如 extension) 返回 filesystem::path
对象而不是字符串对象,就像其他 API 一样。
内容 |
[edit] 成员类型
类型 | 定义 | ||||||||
value_type
|
文件系统原生编码使用的字符类型:在 POSIX 上为 char,在 Windows 上为 wchar_t | ||||||||
string_type
|
std::basic_string<value_type> | ||||||||
const_iterator
|
一个常量 LegacyInputIterator,其 value_type 为 path ,满足 LegacyBidirectionalIterator 的所有要求,但对于两个相等的可以解引用的迭代器 a 和 b (类型为 const_iterator ),*a 和 *b 不需要引用同一个对象。
| ||||||||
iterator
|
const_iterator 的别名 | ||||||||
(C++17) |
确定如何解释路径名的字符串表示形式。 还定义了以下枚举量
(公共成员枚举) |
[edit] 成员常量
constexpr value_type preferred_separator [静态] |
除可移植的 / 之外,可能使用的备用目录分隔符。在 Windows 上,这是反斜杠字符 \。在 POSIX 上,这与可移植的分隔符相同,即正斜杠 / (公共静态成员常量) |
[edit] 成员函数
构造 path (公共成员函数) | |
销毁 path 对象(公共成员函数) | |
赋值另一个路径 (公共成员函数) | |
赋值内容 (公共成员函数) | |
串联 | |
使用目录分隔符将元素追加到路径中 (公共成员函数) | |
串联两个路径,不引入目录分隔符 (公共成员函数) | |
修改器 | |
擦除内容 (公共成员函数) | |
将目录分隔符转换为首选目录分隔符 (公共成员函数) | |
删除文件名路径组件 (公共成员函数) | |
用另一个路径替换最后一个路径组件 (公共成员函数) | |
替换扩展名 (公共成员函数) | |
交换两个路径 (公共成员函数) | |
格式观察器 | |
返回路径的原生版本 (公共成员函数) | |
返回以原生路径名格式转换为字符串的路径 (公共成员函数) | |
返回以通用路径名格式转换为字符串的路径 (公共成员函数) | |
比较 | |
按字典序比较两个路径的词法表示形式 (公共成员函数) | |
生成 | |
将路径转换为规范形式 将路径转换为相对形式 将路径转换为邻近形式 (公共成员函数) | |
分解 | |
返回路径的根名称(如果存在) (公共成员函数) | |
返回路径的根目录(如果存在) (公共成员函数) | |
返回路径的根路径(如果存在) (公共成员函数) | |
返回相对于根路径的路径 (公共成员函数) | |
返回父路径的路径 (公共成员函数) | |
返回文件名路径组件 (公共成员函数) | |
返回词干路径组件(文件名不含最终扩展名) (公共成员函数) | |
返回文件扩展名路径组件 (公共成员函数) | |
查询 | |
检查路径是否为空 (公共成员函数) | |
检查相应的路径元素是否为空 (公共成员函数) | |
检查 root_path() 是否唯一标识文件系统位置 (公共成员函数) | |
迭代器 | |
以元素序列的形式访问路径的迭代器 (公共成员函数) |
[edit] 非成员函数
在
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 中定义 | |
对 std::filesystem::path 的哈希支持 (类模板特化) | |
对 filesystem::path 的格式化支持(类模板特化) |
[编辑] 缺陷报告
以下行为更改缺陷报告已追溯应用于以前发布的 C++ 标准。
DR | 应用于 | 已发布的行为 | 正确行为 |
---|---|---|---|
LWG 3657 | C++17 | path 的 hash 被禁用 |
已启用 |