Namespaces
Variants

std::filesystem:: path

From cppreference.net
C++
Filesystem library
Classes
Functions
File types
std::filesystem::path
Member types
Member constants
Member functions
Path decomposition
Non-member functions
(until C++20) (until C++20) (until C++20) (until C++20) (until C++20) (C++20)
Helper classes
定义于头文件 <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 s：斜杠字符 / 或作为 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 满足 LegacyBidirectionalIterator 所有要求的常量 LegacyInputIterator ，其 value_type 为 path ，但对于两个相等的可解引用迭代器 a 和 b （类型为 const_iterator ），不要求 * a 和 * b 引用同一对象。

未指定 const_iterator 是否实际为 LegacyBidirectionalIterator

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

同时定义以下枚举项：

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

(公开成员枚举)

成员常量

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

成员函数

构造 path 对象
(公开成员函数)
销毁 path 对象
(公开成员函数)
赋值另一个路径
(公开成员函数)
赋值内容
(公开成员函数)
路径拼接
使用目录分隔符向路径追加元素
(公开成员函数)
拼接两个路径而不引入目录分隔符
(公开成员函数)
路径修改
清空内容
(公开成员函数)
将目录分隔符转换为首选目录分隔符
(公开成员函数)
移除文件名路径组件
(公开成员函数)
用另一个路径替换最后一个路径组件
(公开成员函数)
替换扩展名
(公开成员函数)
交换两个路径
(公开成员函数)
格式观察器
返回路径的本地版本
(公开成员函数)
返回转换为字符串的本地路径名格式路径
(公开成员函数)
返回转换为字符串的通用路径名格式路径
(公开成员函数)
路径比较
按字典序比较两个路径的词法表示
(公开成员函数)
路径生成
将路径转换为正规形式
将路径转换为相对形式
将路径转换为近似形式
(公开成员函数)
路径分解
返回路径的根名称（如果存在）
(公开成员函数)
返回路径的根目录（如果存在）
(公开成员函数)
返回路径的根路径（如果存在）
(公开成员函数)
返回相对于根路径的路径
(公开成员函数)
返回父路径
(公开成员函数)

非成员函数

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

辅助类

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

缺陷报告

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

缺陷报告 适用范围 发布时行为 正确行为
LWG 3657 C++17 hash for path was disabled enabled