std::filesystem::path

 

C++

編譯器支援

自由（freestanding）與宿主（hosted）

語言

標準庫

標準庫標頭檔案

具名要求

特性測試宏 (C++20)

語言支援庫

概念庫 (C++20)

診斷庫

記憶體管理庫

超程式設計庫 (C++11)

通用工具庫

容器庫

迭代器庫

範圍庫 (C++20)

演算法庫

字串庫

文字處理庫

數值庫

日期和時間庫

輸入/輸出庫

檔案系統庫 (C++17)

併發支援庫 (C++11)

執行控制庫 (C++26)

技術規範

符號索引

外部庫

 

檔案系統庫

類
filesystem::path filesystem::filesystem_error filesystem::directory_entry filesystem::directory_iterator filesystem::recursive_directory_iterator    filesystem::file_status filesystem::space_info	filesystem::file_type filesystem::file_time_type filesystem::perms filesystem::perm_options filesystem::copy_options filesystem::directory_options
函式
filesystem::absolute filesystem::canonicalfilesystem::weakly_canonical filesystem::relativefilesystem::proximate filesystem::copy filesystem::copy_file filesystem::copy_symlink filesystem::create_directory filesystem::create_directories filesystem::create_hard_link filesystem::create_symlink filesystem::create_directory_symlink filesystem::current_path filesystem::temp_directory_path	filesystem::exists filesystem::equivalent filesystem::file_size filesystem::hard_link_count filesystem::last_write_time filesystem::permissions filesystem::read_symlink filesystem::remove filesystem::remove_all filesystem::rename filesystem::resize_file filesystem::space filesystem::status filesystem::symlink_status
檔案型別
filesystem::is_block_file filesystem::is_character_file filesystem::is_directory filesystem::is_empty filesystem::status_known	filesystem::is_fifo filesystem::is_other filesystem::is_regular_file filesystem::is_socket filesystem::is_symlink

 

std::filesystem::path

成員型別
成員常量
path::native_formatpath::generic_formatpath::auto_format
成員函式
path::path path::~path path::operator= path::assign path::appendpath::operator/= path::concatpath::operator+= path::clear path::make_preferred path::remove_filename path::replace_filename path::replace_extension    path::swap path::compare path::beginpath::end	path::c_strpath::nativepath::operator string_type path::stringpath::u8stringpath::u16stringpath::u32stringpath::wstring path::generic_stringpath::generic_u8stringpath::generic_u16stringpath::generic_u32stringpath::generic_wstring path::lexically_normalpath::lexically_relativepath::lexically_proximate
路徑分解
path::root_name path::root_directory path::root_path path::relative_path path::parent_path path::filename path::stem path::extension path::empty	path::has_root_pathpath::has_root_namepath::has_root_directorypath::has_relative_pathpath::has_parent_pathpath::has_filenamepath::has_stempath::has_extension path::is_absolutepath::is_relative
非成員函式
operator==operator!=operator<operator<=operator>operator>=operator<=> (C++20前)(C++20前)(C++20前)(C++20前)(C++20前)(C++20起)	operator/ operator<<operator>> swap(std::filesystem::path) hash_value u8path
輔助類
hash<std::filesystem::path>	formatter<std::filesystem::path> (C++26)

 

定義於標頭檔案 <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
format	確定如何解釋路徑名的字串表示。 還定義了以下列舉器 名稱 解釋 native_format 原生路徑名格式 generic_format 通用路徑名格式 auto_format 實現定義的格式，可能時自動檢測 (公共成員列舉)

成員常量

constexpr value_type preferred_separator [靜態]

除可移植的 / 之外，可能使用的替代目錄分隔符。在 Windows 上，這是反斜槓字元 \。在 POSIX 上，這與可移植分隔符相同，都是正斜槓 / (公共靜態成員常量)

成員函式

(建構函式)	構造一個 path (公共成員函式)
(解構函式)	銷燬一個 path 物件 (公共成員函式)
operator=	賦值另一個路徑 (公共成員函式)
assign	賦值內容 (公共成員函式)
連線
appendoperator/=	用目錄分隔符向路徑追加元素 (公共成員函式)
concatoperator+=	連線兩個路徑而不引入目錄分隔符 (公共成員函式)
修改器
clear	擦除內容 (公共成員函式)
make_preferred	將目錄分隔符轉換為首選目錄分隔符 (公共成員函式)
remove_filename	刪除檔名路徑元件 (公共成員函式)
replace_filename	用另一個路徑替換最後一個路徑元件 (公共成員函式)
replace_extension	替換副檔名 (公共成員函式)
swap	交換兩個路徑 (公共成員函式)
格式觀察器
c_strnativeoperator string_type	返回路徑的原生版本 (公共成員函式)
stringwstringu8stringu16stringu32string	返回轉換為字串的原生路徑名格式的路徑 (公共成員函式)
generic_stringgeneric_wstringgeneric_u8stringgeneric_u16stringgeneric_u32string	返回轉換為字串的通用路徑名格式的路徑 (公共成員函式)
比較
compare	按字典順序比較兩個路徑的詞法表示 (公共成員函式)
生成
lexically_normallexically_relativelexically_proximate	將路徑轉換為規範形式 將路徑轉換為相對形式 將路徑轉換為近似形式 (公共成員函式)
分解
root_name	返回路徑的根名（如果存在） (公共成員函式)
root_directory	返回路徑的根目錄（如果存在） (公共成員函式)
root_path	返回路徑的根路徑（如果存在） (公共成員函式)
relative_path	返回相對於根路徑的路徑 (公共成員函式)
parent_path	返回父路徑的路徑 (公共成員函式)
filename	返回檔名路徑元件 (公共成員函式)
stem	返回主檔名路徑元件（不帶最終副檔名的檔名） (公共成員函式)
extension	返回副檔名路徑元件 (公共成員函式)
查詢
empty	檢查路徑是否為空 (公共成員函式)
has_root_pathhas_root_namehas_root_directoryhas_relative_pathhas_parent_pathhas_filenamehas_stemhas_extension	檢查相應路徑元素是否不為空 (公共成員函式)
is_absoluteis_relative	檢查 root_path() 是否唯一標識檔案系統位置 (公共成員函式)
迭代器
beginend	以元素序列的形式迭代訪問路徑 (公共成員函式)

非成員函式

定義於名稱空間 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起)(C++20前)(C++17起)(C++20前)(C++17起)(C++20前)(C++17起)(C++20前)(C++17起)(C++20前)(C++20起)	按字典順序比較兩個路徑 (函式)
operator/ (C++17)	用目錄分隔符連線兩個路徑 (函式)
operator<<operator>> (C++17)	對帶引號的路徑執行流輸入和輸出 (函式)
u8path (C++17)(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++ 標準。

缺陷報告	應用於	釋出時的行為	正確的行為
LWG 3657	C++17	path 的 hash 已停用	已啟用