std::filesystem:: path

定义于头文件 <filesystem>
class path ;		(C++17 起)

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

路径名称具有以下语法：

1. root-name （可选） ：用于在具有多个根目录的文件系统中标识根目录（例如 "C:" 或 "//myserver" ）。若存在歧义，则将能构成有效 root-name 的最长字符序列视为 root-name 。标准库除了操作系统API能识别的根名称外，还可定义其他根名称。
2. root-directory （可选） ：目录分隔符，若存在则标记该路径为 绝对路径 。若缺失（且除根名称外的首元素为文件名），则该路径为 相对路径 ，需以另一路径作为起始位置来解析为文件名。
3. 以下元素的零个或多个：

• 文件名 ：由非目录分隔符或首选目录分隔符组成的字符序列（操作系统或文件系统可能施加额外限制）。该名称可标识文件、硬链接、符号链接或目录。存在两种特殊 文件名 被识别：

• 点 ：由单个点字符 . 组成的文件名，是引用当前目录的目录名称。
• 点点 ：由两个点字符 .. 组成的文件名，是引用父目录的目录名称。

• 目录分隔符 ：正斜杠字符 / 或作为 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 的任何非常量成员函数会使指向该对象元素的所有迭代器失效。

如果操作系统使用的 原生 语法与前述可移植 通用 语法不同，被定义为接受"检测格式"的库函数可同时接受两种格式的路径名：当且仅当检测格式参数符合通用格式但无法被操作系统作为原生路径接受时，该参数将被视为通用格式。在目录路径名与文件路径名采用不同原生格式的操作系统中，以目录分隔符结尾的通用路径名将被视为目录路径，否则视为常规文件路径。

在任何情况下，路径类的行为都如同它以原生格式存储路径名，并在需要时自动转换为通用格式（每个成员函数都明确指定了其解释路径时使用的格式）。

在POSIX系统上，通用格式即为原生格式，无需对二者进行区分或转换。

Paths 可以隐式转换为 std::basic_string 并从中转换回来，这使得它们能够与其他文件 API 配合使用。

流操作符使用 std::quoted 以确保在后续被 流输入操作符 读取时，空格不会导致截断。

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

目录 1 成员类型 2 成员常量 3 成员函数 3.1 连接操作 3.2 修改器 3.3 格式观察器 3.4 比较操作 3.5 生成操作 3.6 分解操作 3.7 查询操作 3.8 迭代器 4 非成员函数 5 辅助类 6 缺陷报告

成员类型

类型	定义
value_type	文件系统原生编码使用的字符类型： char 在POSIX系统上， wchar_t 在Windows系统上
string_type	std:: basic_string < value_type >
const_iterator	一个常量 LegacyInputIterator ，其 value_type 为 path ，满足 LegacyBidirectionalIterator 的所有要求，但以下情况除外：对于两个相等的可解引用迭代器 a 和 b （类型为 const_iterator ），不要求 * a 和 * b 引用同一对象。 未指定 const_iterator 是否实际为 LegacyBidirectionalIterator
iterator	const_iterator
format	确定如何解释路径名的字符串表示形式。 同时定义了以下枚举值： 名称 说明 native_format 原生路径名格式 generic_format 通用路径名格式 auto_format 实现定义的格式，在可能的情况下自动检测 （公开成员枚举）

成员常量

constexpr value_type preferred_separator [static]

可替代的目录分隔符，除可移植的 / 外也可使用此分隔符。在 Windows 系统上，此为反斜杠字符 \ 。在 POSIX 系统上，此分隔符与可移植分隔符相同，均为正斜杠 / (公开静态成员常量)

成员函数

(constructor)	构造一个 path (公开成员函数)
(析构函数)	销毁 path 对象 (公开成员函数)
operator=	赋值另一个路径 （公开成员函数）
assign	赋值内容 （公开成员函数）
连接操作
append operator/=	使用目录分隔符向路径追加元素 （公开成员函数）
concat operator+=	在不引入目录分隔符的情况下连接两个路径 (公开成员函数)
修饰符
clear	清空内容 （公开成员函数）
make_preferred	将目录分隔符转换为首选目录分隔符 （公开成员函数）
remove_filename	移除文件名路径组件 （公开成员函数）
replace_filename	用另一个路径替换最后一级路径组件 (公开成员函数)
replace_extension	替换扩展名 （公开成员函数）
swap	交换两个路径 （公开成员函数）
格式观察器
c_str native operator string_type	返回路径的本地版本 （公开成员函数）
string wstring u8string u16string u32string	返回转换为字符串的本机路径名格式路径 （公开成员函数）
generic_string generic_wstring generic_u8string generic_u16string generic_u32string	返回转换为字符串的通用路径名格式路径 （公开成员函数）
比较
compare	按字典序比较两个路径的词法表示 (公开成员函数)
生成
lexically_normal lexically_relative lexically_proximate	将路径转换为规范形式 将路径转换为相对形式 将路径转换为近似形式 （公开成员函数）
分解
root_name	返回路径的根名称（如果存在） （公开成员函数）
root_directory	返回路径的根目录（如果存在） （公开成员函数）
root_path	返回路径的根路径（如果存在） （公开成员函数）
relative_path	返回相对于根路径的路径 （公开成员函数）
parent_path	返回父路径的路径 （公开成员函数）
filename	返回路径的文件名组件 （公开成员函数）
stem	返回路径的茎部组件（不含最终扩展名的文件名） （公开成员函数）
extension	返回文件扩展名路径组件 (公开成员函数)
查询
empty	检查路径是否为空 （公开成员函数）
has_root_path has_root_name has_root_directory has_relative_path has_parent_path has_filename has_stem has_extension	检查对应的路径元素是否非空 （公开成员函数）
is_absolute is_relative	检查 root_path() 是否唯一标识文件系统位置 （公开成员函数）
迭代器
begin end	以迭代器方式访问路径的元素序列 (公开成员函数)

非成员函数

定义于命名空间 std::filesystem
swap (std::filesystem::path) (C++17)	特化 std::swap 算法 (函数)
hash_value (C++17)	计算路径对象的哈希值 (函数)
operator== operator!= operator< operator<= operator> operator>= operator<=> (C++17) (C++17) (until C++20) (C++17) (until C++20) (C++17) (until C++20) (C++17) (until C++20) (C++17) (until C++20) (C++20)	按字典序比较两个路径 (函数)
operator/ (C++17)	使用目录分隔符连接两个路径 (函数)
operator<< operator>> (C++17)	对带引号的路径执行流输入和输出操作 (函数)
u8path (C++17) (deprecated in C++20)	从UTF-8编码源创建 path 对象 (函数)

辅助类

定义于 命名空间 std
std::hash <std::filesystem::path> (C++17)	std::filesystem::path 的哈希支持 (类模板特化)
std::formatter <std::filesystem::path> (C++26)	filesystem::path 的格式化支持 (类模板特化)

缺陷报告

以下行为变更缺陷报告被追溯应用于先前发布的 C++ 标准。

DR	适用版本	发布行为	正确行为
LWG 3657	C++17	hash 对于 path 被禁用	启用