命名空间
变体
操作

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

可以通过以下算法规范化路径

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

可以通过 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 一个常量 旧式输入迭代器，其 value_type 为 path，满足 旧式双向迭代器 的所有要求，除了对于类型为 const_iterator 的两个相等的可解引用迭代器 a 和 b，没有要求 *a 和 *b 引用同一个对象。

不指定 const_iterator 是否实际上是 旧式双向迭代器

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++ 标准。

DR 应用于 已发布行为 正确行为
LWG 3657 C++17 用于 path 的 hash 已禁用 已启用
已从“https://cppreference.cn/mwiki/index.php?title=cpp/filesystem/path&oldid=178501”检索