source : http://qa.alibaba.com/docs/boost_doc/libs/filesystem/doc/reference.html#Class-template-basic_recursive_directory_iterator
![]() | Filesystem 庫 |
Boost Home Library Home Tutorial Reference FAQ |
參考文檔
目錄
簡介 定義 要求 對程式的要求 對實作的要求 頭檔案<filesystem> 概要 Path traits 類模闆 basic_path 路徑名格式 路徑名文法 檔案名轉換 要求 | 類模闆basic_path (續) basic_path 構造函數 basic_path 指派 basic_path 修改器 basic_path操作符 basic_path 觀察器 basic_path 疊代器 basic_path非成員函數 basic_path插入器和提取器 類模闆basic_filesystem_error basic_filesystem_error構造函數 basic_filesystem_error觀察器 類模闆basic_directory_entry basic_directory_entry構造函數 basic_directory_entry修改器 basic_directory_entry觀察器 basic_directory_entry比較操作 | Filesystem 庫 (續) 類模闆basic_directory_iterator basic_directory_iterator構造函數 類模闆basic_recursive_directory_iterator 類 file_status 非成員操作函數 狀态函數 謂詞函數 屬性函數 其它操作函數 便利函數 對頭檔案<fstream> 的增加 對 實作的建議 路徑分解表 鳴謝 參考 |
本庫早期版本中的有些函數已經改名或不再使用。請見 不再使用的名稱和特性。
簡介
本庫的有些行為是通過引用 ISO/IEC 9945:2003, POSIX來規定的。這些行為如何實作則并沒有規定。
[注:這為與作業系統相關的行為的實作制定了一個"類似"規則。大概這些實作通常都會調用原生的作業系統API. --注完]
實作被鼓勵,但不要求,支援 POSIX 所定義的行為。實作應該對與 POSIX定義的行為有所不同的行為給出文檔說明。實作如果由于作業系統和檔案系統的局限,而不能支援精确的 POSIX行為,則應盡量提供接近 POSIX的合理行為。如果一個實作不能提供任何合理的行為,該實作應該以實作定義的方式報告一個錯誤。
[注:這類錯誤可能通過一個 #error 訓示, 一個, 一個
static_assert
異常, 一個特定的傳回值,或其它方式來報告。--注完]
basic_filesystem_error
特定的作業系統,如 OpenMVS,UNIX, 和 Windows僅在示範或給出實作指導時提及。不提及其它作業系統是有意的。
在本參考手冊中給出的函數的 效果 和 後置條件可能不适用于 競争條件的情形。這類診斷并不被要求。
如果可能存在競争條件,使得程式在調用函數之前測試某個前提條件變得不可靠,則不指定這樣的 Requires. 反之,這些條件被指定為 Throws 條件。
[注:作為一個設計實踐,如果要求一個程式在調用函數之前檢查前提條件是不合理的,則這些前提條件不會被規定。-- 注完]
定義
在本參考手冊中,使用了以下定義:
檔案:一個對象,可以寫入、讀出或兩者俱可。檔案具有确定的屬性,包括類型。檔案類型包括有:普通檔案、符号連結和目錄。實作還可能支援其它檔案類型。
檔案系統:一組檔案和它們的屬性。
檔案名:檔案的名字。其格式由 POSIX檔案名Filename 基本定義所指定。
路徑:一組元素序列,用以辨別檔案系統中的某個位置。這些元素是 root-name, root-directory, 以及各個連續的檔案名。請見路徑名文法。
路徑名:表示一個路徑的一個字元串。
連結:一個目錄項對象,它關聯某個檔案的檔案名。在某些檔案系統中,多個目錄項可以關聯同一個檔案名。
硬連結:到一個已有檔案的連結。有些檔案系統支援同一個檔案的多個硬連結。如果最後一個硬連結被删除,則檔案本身被删除。
[注:硬連結可以被視為一個檔案的所有權共享智能指針。-- 注完]
符号連結:一種檔案類型,在路徑名解析過程中使用,檔案中儲存的字元串被用于修改路徑名的解析。
[注:符号連結可以被視為一個檔案的原始指針。如果被指向的檔案不存在,則該符号連結被稱為 "懸空" 的符号連結。--注完]
斜線符:字元 '/', 也稱為斜線分隔符。
點符: 字元'.', 也稱為句點。
競争條件:當多個線程、程序或計算機交錯通路和修改檔案系統中的同一個對象時發生的情形。
要求
對程式的要求
在本文中名為
Path
,
Path1
,或
Path2
的模闆參數都應為類型
basic_path
,或是派生自
basic_path
一某個類,除非特别說明。
對實作的要求
在本文中,有些函數模闆具有名為
Path
,
Path1
,或
Path2
的模闆參數。當以類型為
char*
或
std::string
的參數
s
來調用這些函數時,實作應将這個參數視作為
path(s)
. 當以類型為
wchar_t*
或
std::wstring
的參數
s
來調用這些函數時,
實作應将這個參數視作為
wpath(s)
.對于帶兩個參數的函數,實作不應支援将
Path1
和
Path2
作為不同類型來處理。
[注:這個 "do-the-right-thing" 規則允許使用者寫象這樣的代碼,利用類
exists("foo")
的字元串轉換構造函數,而不需要寫又長又容易出錯的
basic_path
exists(path("foo"))
.這對于編寫簡單、類似于腳本的程式尤其重要,這也正是本庫的一個主要應用。以不同類型的兩個參數來調用函數的情況非常罕見,很可能是代碼錯誤,是以這種情形下的自動轉換是不被支援的。
實作的技術并不特别規定。以
為例,以下是一種可能的實作技術:
exists()
對于C字元串或template <class Path> typename boost::enable_if<is_basic_path<Path>,bool>::type exists(const Path& p); inline bool exists(const path& p) { return exists<path>(p); } inline bool exists(const wpath& p) { return exists<wpath>(p); }
參數,
std::basic_string
将會失敗,這樣就會通過适當的
enable_if
轉換構造函數自動轉換為
basic_path
basic_path
對象。-- 注完]
這兩個重載沒有在正式文本中給出,是因為:
- 可能會有更好的方法達到這一效果,如通過核心語言實作對 Concepts 的支援。
- 實作可能會選用其它技術,以便用于那些不支援 enable_if 的舊編譯器。
- 清楚說明這些重載會使得文本更長,更難以閱讀,而沒有增加任何好處。
- 對于 char16_t 和 char32_t 可能需要更多的重載(或者規定它們不允許調用),每一個都要講清楚就更麻煩了。
本文中的函數的實作可以調用由作業系統系統提供的API. 如果調用這些作業系統API産生了錯誤,則實作應通過抛出
basic_filesystem_error
異常來報告錯誤,除非特别說明。
[注:這些異常及其抛出條件不會在本文的每一個 Throws單元中說明。因為在檔案系統操作中,硬體錯誤、網絡失敗、競争條件和其它多種錯誤都會常常發生,使用者應該知道,除非特别說明,任何的檔案系統操作,無論看起來多麼沒有危險,都可能會抛出異常。-- 注完]
對于那些常常用在錯誤不被視為異常的環境中的函數,都有其它重載,接受一個額外的參數
error_code&ec
.這些函數重載不抛出異常。如果發生了錯誤,
ec
将被設定為作業系統所報告的錯誤碼,否則
ec
被設為 0. 如果沒有類型
error_code&ec
參數的重載是傳回 void的,則另一個重載(帶有類型
error_code&ec
參數的)将傳回一個
error_code
,值為 ec.
頭檔案 <boost/filesystem>
概要
<boost/filesystem>
namespace boost
{
namespace filesystem
{
template <class String, class Traits> class basic_path;
template<class String, class Traits>
void swap(basic_path<String, Traits> & lhs, basic_path<String, Traits> & rhs);
template<class String, class Traits> bool operator<(a a, b b);
template<class String, class Traits> bool operator==(a a, b b);
template<class String, class Traits> bool operator!=(a a, b b);
template<class String, class Traits> bool operator>(a a, b b);
template<class String, class Traits> bool operator<=(a a, b b);
template<class String, class Traits> bool operator>=(a a, b b);
template<class String, class Traits> bool operator/(a a, b b);
template<class Path>
basic_ostream<typename Path::string_type::value_type, typename Path::string_type::traits_type> &
operator<<(basic_ostream<typename Path::string_type::value_type, typename Path::string_type::traits_type>& os, const Path & ph);
template<class Path>
basic_istream<typename Path::string_type::value_type, typename Path::string_type::traits_type> &
operator>>(basic_istream<typename Path::string_type::value_type, typename Path::string_type::traits_type>& is, Path & ph);
struct path_traits;
struct wpath_traits;
typedef basic_path<std::string, path_traits> path;
typedef basic_path<std::wstring, wpath_traits> wpath;
template<class Path> struct is_basic_path;
template<class Path> struct slash { static const char value = '/'; };
template<class Path> struct dot { static const char value = '.'; };
template<class Path> struct colon { static const char value = ':'; };
class filesystem_error;
template <class Path> class basic_filesystem_error;
typedef basic_filesystem_error<path> filesystem_error;
typedef basic_filesystem_error<wpath> wfilesystem_error;
template <class Path> class basic_directory_entry;
typedef basic_directory_entry<path> directory_entry;
typedef basic_directory_entry<wpath> wdirectory_entry;
template <class Path> class basic_directory_iterator;
typedef basic_directory_iterator<path> directory_iterator;
typedef basic_directory_iterator<wpath> wdirectory_iterator;
template <class Path> class basic_recursive_directory_iterator;
typedef basic_recursive_directory_iterator<path> recursive_directory_iterator;
typedef basic_recursive_directory_iterator<wpath> wrecursive_directory_iterator;
enum file_type { status_unknown, file_not_found, regular_file, directory_file,
symlink_file, block_file, character_file, fifo_file, socket_file,
type_unknown
};
class file_status;
struct space_info // returned by space function
{
uintmax_t capacity;
uintmax_t free;
uintmax_t available;
};
// status functions
template <class Path> file_status status(const Path& p);
template <class Path> file_status status(const Path& p, error_code& ec);
template <class Path> file_status symlink_status(const Path& p);
template <class Path> file_status symlink_status(const Path& p, error_code& ec);
// predicate functions
bool status_known( file_status s );
bool exists( file_status s );
bool is_regular_file( file_status s );
bool is_directory( file_status s );
bool is_symlink( file_status s );
bool is_other( file_status s );
template <class Path> bool exists(const Path& p);
template <class Path> bool is_directory(const Path& p);
template <class Path> bool is_regular_file(const Path& p);
template <class Path> bool is_other(const Path& p);
template <class Path> bool is_symlink(const Path& p);
template <class Path> bool is_empty(const Path& p);
template <class Path1, class Path2>
bool equivalent(const Path1& p1, const Path2& p2);
// attribute functions
template <class Path> Path current_path();
template <class Path> void current_path(const Path& p);
template <class Path> const Path& initial_path();
template <class Path> uintmax_t file_size(const Path& p);
template <class Path> space_info space(const Path& p);
template <class Path> std::time_t last_write_time(const Path& p);
template <class Path>
void last_write_time(const Path& p, const std::time_t new_time);
// operations functions
template <class Path> bool create_directory(const Path& dp);
template <class Path1, class Path2>
void create_hard_link(const Path1& old_fp, const Path2& new_fp);
template <class Path1, class Path2>
error_code create_hard_link(const Path1& old_fp, const Path2& new_fp, error_code& ec);
template <class Path1, class Path2>
void create_symlink(const Path1& old_fp, const Path2& new_fp);
template <class Path1, class Path2>
error_code create_symlink(const Path1& old_fp, const Path2& new_fp, error_code& ec);
template <class Path> bool remove(const Path& p);
template <class Path1, class Path2>
void rename(const Path1& from_p, const Path2& to_p);
BOOST_SCOPED_ENUM_START(copy_option)
{ fail_if_exists, overwrite_if_exists };
BOOST_SCOPED_ENUM_END
template <class Path1, class Path2>
void copy_file(const Path1& from_fp, const Path2& to_fp,
BOOST_SCOPED_ENUM(copy_option) option=copy_option::fail_if_exists);
template <class Path> Path system_complete(const Path& p);
template <class Path> Path complete(const Path& p, const Path& base=initial_path<Path>());
// convenience functions
template <class Path> bool create_directories(const Path& p);
template <class Path> typename Path::string_type extension(const Path& p);
template <class Path> typename Path::string_type basename(const Path& p);
template <class Path>
Path change_extension(const Path& p, const typename Path::string_type& new_extension);
} // namespace filesystem
} // namespace boost
Path traits
這一節定義了對表示路徑行為的 traits 類的要求,并且定義了兩個類,分别滿足對基于 string 和wstring 的路徑的這些要求。還定義了幾個額外的 path traits 結構模闆,以及這些模闆的特化。
在本文中定義的類模闆
basic_path
要求一些其它的類型、值和行為來完成對其語義的定義。
從作用上說,Traits 的行為就象它是一個帶有一個被初始化為 false 的私有成員 boolm_locked,以及一個已初始化的成員 std::locale m_locale 的類。
路徑行為Traits 要求 | |
表達式 | 要求 |
| 一個 typedef,它是 的一個特化。其 為作業系統用于表示路徑名的字元類型。 |
| 一個 typedef,它是 的一個特化。其 為程式用于表示路徑名的字元類型。要求它與 模闆參數具有相同類型。 |
| , 被 facet 轉換為 . |
| , 被 facet 轉換為 . |
| 作用:如果 ,則抛出異常。否則 傳回: 抛出: |
| 作用: 傳回: |
類型
is_basic_path
應該是一個 UnaryTypeTrait(TR1, 4.1). 其主模闆應直接或間接派生自
std::tr1::false_type
. 類型
is_basic_path
應針對
path
,
wpath
,和任何使用者專有
basic_path
類型進行特化,而且這些特化都應直接或間接派生自
std::tr1::true_type
.
結構模闆
slash
,
dot
,和
colon
用于提供類型為
char
的值。如果某個使用者專有
basic_path
具有不可由 char 轉換而得的
value_type
類型,則模闆
slash
和
dot
應被特化,以提供某種可轉換為
basic_path::value_type
的類型的值。
類模闆 basic_path
basic_path
類模闆
basic_path
提供了一個在C++程式中表示 路徑paths 的可移植機制,它使用可移植的通用路徑名文法。當不需要可移植性時,可以使用原生檔案系統的特定格式。類模闆
basic_path
隻關心路徑的詞法和文法方面。該路徑不要求在作業系統的檔案系統中存在,也可能包含某些目前作業系統認為無效的名字。
[注:如果本庫的函數隻能使用C++或C風格的字元串,那麼它們的可移植性隻是幻想,因為雖然函數調用的文法是可移植的,但函數所操作的字元串的語義卻不可移植。-- 注完]
namespace boost
{
namespace filesystem
{
template <class String, class Traits> class basic_path
{
public:
typedef basic_path<String, Traits> path_type;
typedef String string_type;
typedef typename String::value_type value_type;
typedef Traits traits_type;
typedef typename Traits::external_string_type external_string_type;
// constructors/destructor
basic_path();
basic_path(const basic_path& p);
basic_path(const string_type& s);
basic_path(const value_type* s);
template <class InputIterator>
basic_path(InputIterator first, InputIterator last);
~basic_path();
// assignments
basic_path& operator=(const basic_path& p);
basic_path& operator=(const string_type& s);
basic_path& operator=(const value_type* s);
template <class InputIterator>
basic_path& assign(InputIterator first, InputIterator last);
// modifiers
basic_path& operator/=(const basic_path& rhs);
basic_path& operator/=(const string_type& s);
basic_path& operator/=(const value_type* s);
template <class InputIterator>
basic_path& append(InputIterator first, InputIterator last);
void clear();
void swap( basic_path & rhs );
basic_path& remove_filename();
basic_path& replace_extension(const string_type & new_extension = "");
// observers
const string_type string() const;
const string_type file_string() const;
const string_type directory_string() const;
const external_string_type external_file_string() const;
const external_string_type external_directory_string() const;
string_type root_name() const;
string_type root_directory() const;
basic_path root_path() const;
basic_path relative_path() const;
basic_path parent_path() const;
string_type filename() const;
string_type stem() const;
string_type extension() const;
bool empty() const;
bool is_complete() const;
bool has_root_name() const;
bool has_root_directory() const;
bool has_root_path() const;
bool has_relative_path() const;
bool has_filename() const;
bool has_parent_path() const;
// iterators
class iterator;
typedef iterator const_iterator;
iterator begin() const;
iterator end() const;
};
} // namespace filesystem
} // namespace boost
一個
basic_path
對象可以儲存空路徑。儲存路徑的内部形式并不指定。
在本文中描述的通路檔案及其屬性的函數要将一個
basic_path
對象解析為檔案層次中的一個特定檔案。路徑名被合适地轉換為作業系統所要求的字元串類型、格式和編碼,按 POSIXPathnameResolution 機制進行解析。結果路徑名的編碼由
Traits::to_external
轉換函數決定。
[注:并不保證儲存在 basic_path
對象中的路徑對于特定的作業系統或檔案系統是有效的。-- 注完]
本文中有些函數傳回的
basic_path
對象部分或全部由得自作業系統的路徑名組成。這些路徑名被從由作業系統提供的真實格式和字元串類型進行合适的轉換。結果路徑的編碼由
Traits::to_internal
轉換函數決定。
那些傳回 "
const string_type
" 或 "
constexternal_string_type
" 的成員函數,允許被實作為分别傳回 "
conststring_type&
" 或 "
constexternal_string_type&
"。
[注:這允許實作避免不必要的複制。指定以常量值傳回可以確定在轉換為以引用傳回的實作時不會破壞已有程式。-- 注完]
路徑名格式
有兩種格式的字元串或字元序列參數來表示一個路徑:
- 可移植的路徑名格式,在 路徑名文法中描述,由 POSIX Filename,Pathname和 Pathname Resolution 定義。
[注:POSIX格式是可移植格式的基礎,因為它已經是一個ISO标準了,它也是廣泛采用的URL格式,是類UNIX和類Windows作業系統的原生格式或其子集,為廣大程式員所熟悉。
單靠使用可移植格式并不能保證可移植性;檔案名也必須是可移植的。請見 檔案名轉換。每個作業系統都有它自己的規則。使用可移植格式并不能改變這些規則。 -- 注完]
- 由作業系統定義的原生路徑名格式。
[注:如果作業系統隻支援POSIX路徑名格式,則可移植格式和原生格式就是一樣的。
确定使用者所提供的路徑作為原生格式,是一種常見的需要,并且確定了最大的可移植性,雖然這并不是嚴格需要的,除了在那些原生格式未被公認的系統上。
使用寫死原生格式的程式很可能是不可移植的。-- end note]
所有
basic_path
的描述路徑的字元串或字元序列參數都接受可移植路徑名格式,也接受由原生格式轉義序列字首"//:"顯式辨別的原生格式。
[注: "//:"在POSIX中"//"是由實作定義的,":"
被選擇作為轉義序列,是因為
Windows檔案,而且在任何系統中如果想表示以":"開頭的檔案名,可以使用單個"/"。以上因素一起消除了這個轉義序列與某個真實檔案名發生沖突的可能。-- 注完]
則是不允許用于
如果在文字上可以區分開,實作最好可以直接接受原生的路徑名格式。每個實作應該在文檔中寫明是否可以直接接受原生路徑名格式。
[例如:
-- OpenVMS:
"SYS1::DISK1:[JANE.TYLER.HARRY]
"被視為帶有系統名、驅動器名和三個目錄檔案名的原生路徑名,而不是某個檔案名的可移植路徑名。
-- Windows:
"c:\\jane\\tyler\\harry"
被視為帶有驅動器名、根目錄和三個檔案名的原生路徑名,而不是某個檔案名的可移植路徑名。
-- 反例1:某個作業系統允許在檔案名中使用"/",它使用"."作為目錄分隔符。區分可移植格式和原生格式的字元串或字元序列是不可能的,如果沒有其它可區分的文法。是以實作不接受原生格式的路徑名,除非指定一個原生參數。
-- 反例2:某個作業系統允許在檔案名中使用"/",它使用一些不常見的字元作為目錄分隔符。這時實作不能接受不帶有額外的原生參數的原生格式路徑名,原生參數必須被用于在檔案名中含有"/"的原生格式參數。
-- 舉例完]
[注:鴨子規則duck-rule("如果某個東西看起來象鴨子,走起來象鴨子,叫進來象鴨子,那麼它就是一隻鴨子")消除了源自程式員錯誤和支援要求的格式混亂。--注完]
如果可以同時接受可移植格式和原生格式,則實作應該在文檔中說明哪些字元或字元序列被用作區分可移植格式和原生格式。
[注:Windows實作被鼓勵将":"和"\"定義為區分原生格式和可移植格式的字元。--注完]
路徑名文法
可移植路徑名格式的文法如下:
pathname:
root-nameopt root-directoryoptrelative-pathopt
root-name:
implementation-defined
root-directory:
slash
root-directory slash
implementation-defined
relative-path:
filename
relative-path slash
relative-path slash filename
filename:
name
dot
dot dot
slash:
dot:
slash<Path>::value
dot<Path>::value
該文法是參照 POSIX 的 Filename,Pathname 和PathnameResolution 定義的。該文法與 POSIX 間的任何沖突都不是故意的。本技術報告遵守 POSIX.
以上表達形式取自于 POSIX, 後者在多次使用該方式引向 C 标準。
[注:Windows 實作被鼓勵将"//name"定義為可允許的 root-name. POSIX允許但不要求相關實作也這樣做。Windows 實作被鼓勵定義另一個 root-directory元素 root_directory name. 它隻适用于 root-name的 "//name" 格式。
Windows 實作被鼓勵在 name前加一個":"作為原生格式的 root-name, 将"\"作為與"/"等價的格式元素。-- 注完]
檔案名轉換
在将檔案轉換為原生作業系統格式時,建議但不要求實作将無效字元或字元序列轉換為有效的字元或字元序列。這些轉換是由實作定義的。
[注:檔案轉換給了程式和檔案名更大的可移植能力。
建議實作基于已有标準或實踐之上進行轉換。相關例子包括URL的轉義文法,即在百分号(
)後跟兩位十六進制數字來表示字元值。在 OpenVMS, 不允許在檔案名中出現百分号,是以使用美元符(
'%'
'$'
)後跟兩位十六進制數字,還有将小寫字母轉為大寫。-- 注完]
Windows平台上的Boost實作目前不進行無效字元映射。來自LWG的未決回報是,Boost可能決定用 % hex hex作為轉義序列。如果是這樣,是否會有标準化的建議?
要求
名為
String
的模闆參數的實參應該是一個含有與類模闆
basic_string
相同名字、類型、值和語義的成員的類。
名為
Traits
的模闆參數的實參應該是一個滿足路徑行為 Traits 要求表中給出的要求的類。
名為
InputIterator
的模闆參數的實參應該滿足輸入疊代器的要求(C++标準,24.1.1,Input iterators[lib.input.iterators]),并且應該具有可以轉換為
basic_path::value_type
的值類型。
有些帶有
InputIterator
模闆參數的函數模闆還有其它非模闆的重載形式。如果
InputIterator
的類型不是
path_format_t
,則實作應該隻選擇函數模闆的重載。
[注:"do-the-right-thing"規則確定使用者期望的重載會被選中。實作的技術并未規定 - 具體實作可以使用 enable_if或者其它技術來實作這一效果。--注完]
basic_path
構造函數
basic_path
basic_path();
後置條件: empty()
.
basic_path(const string_type& s);
basic_path(const value_type * s);
template <class InputIterator>
basic_path(InputIterator s, InputIterator last);
備注: 字元串及字元序列[
s
,
first
last
) 的格式在 路徑名格式 中說明。
作用: 儲存字元串
或字元序列 [
s
,
first
)中的路徑元素。
last
basic_path
指派
basic_path
basic_path& operator=(const string_type& s);
basic_path& operator=(const value_type* s);
template <class InputIterator>
basic_path& assign(InputIterator first, InputIterator last);
備注: 字元串及字元序列[
s
,
first
last
) 的格式在 路徑名格式 中說明。
作用: 儲存字元串
或字元序列 [
s
,
first
last
)中的路徑元素。
傳回:
*this
basic_path
修改器
basic_path
basic_path& operator/=(const basic_path& rhs);
作用: 将儲存在
rhs
中的路徑增加到儲存的路徑中。
傳回:
*this
basic_path& operator/=(const string_type& s);
basic_path& operator/=(const value_type* s);
template <class InputIterator>
basic_path& append(InputIterator first, InputIterator last);
備注: 字元串及字元序列[
s
,
first
last
) 的格式在 路徑名格式 中說明。
作用: 将字元串
或字元序列 [
s
,
first
last
)中的路徑元素增加到儲存的路徑中。
傳回:
*this
void clear();
後置條件: this->empty()
為真。
作用: 交換兩個路徑的内容。
抛出: 無。
後置條件:
包含與
this->string()
相同的字元序列,
rhs.string()
則包含與
rhs.string()
this->string()
相同的字元序列。
複雜度: 常量時間。
basic_path& remove_filename();
作用: 如果
has_
parent
_path()
則從儲存的路徑中删除最後的 filename. 如果路徑中剩下的最後的一個或多個"/"不是表示根目錄,就删除它們。
傳回:
[注: 該函數對于高效實作
*this
是必須的。它被設為公有的,可用于其它用途。--注完]
basic_directory_iterator
basic_path& replace_extension( const string_type & new_extension = "" );
後置條件:,其中
extension() == replacement
為
replacement
如果
new_extension
'.',否則
new_extension.empty() || new_extension[0] ==
為'.'後跟
replacement
new_extension
。
傳回:
*this
basic_path
觀察器
basic_path
由分解函數所傳回的值的示例請見 路徑分解表。
const string_type string() const;
傳回: 所儲存的路徑,按照 路徑名文法 規則進行格式化。
const string_type file_string() const;
傳回: 所儲存的路徑,按照作業系統關于正常檔案路徑名的規則進行格式化,帶 檔案名轉換。
[注: 對于某些作業系統,包括 POSIX和 Windows, 正常檔案和目錄的路徑名的原生格式是相同的,是以
和
file_string()
傳回相同的字元串。但是在 OpenMVS上,表達式
directory_string()
傳回字元串
path("/cats/jane").file_string()
而
"[CATS]JANE"
則傳回字元串
path("/cats/jane").directory_string()
. -- 注完]
"[CATS.JANE]"
const string_type directory_string() const;
傳回: 所儲存的路徑,按照作業系統關于目錄路徑名的規則進行格式化,帶 檔案名轉換。
const external_string_type external_file_string() const;
傳回: 所儲存的路徑,按照作業系統關于正常檔案路徑名的規則進行格式化,帶 檔案名轉換,并由 Traits::to_external
轉換函數進行編碼。
const external_string_type external_directory_string() const;
傳回: 所儲存的路徑,按照作業系統關于目錄路徑名的規則進行格式化,帶 檔案名轉換,并由 Traits::to_external
轉換函數進行編碼。
string_type root_name() const;
傳回: root-name,如果所儲存的路徑中包含 root-name, 否則傳回 string_type()
.
string_type root_directory() const;
傳回: root-directory,如果所儲存的路徑中包含 root-directory, 否則傳回
string_type()
.
如果 root-directory 由"/"加 name組成,則"/"被排除在傳回字元串之外。
basic_path root_path() const;
傳回: root_name() /root_directory()
basic_path relative_path() const;
傳回: 從被儲存的路徑組成的,如果有則傳回 root-path 加上第一個 filename。否則傳回空的
basic_path
.
basic_path
string_type filename() const;
傳回: empty() ? string_type(): *--end()
basic_path parent_path() const;
傳回:,其中
(string().empty() ||begin() == --end()) ? path_type("") : br
是這樣構成的:以一個空的
br
開始,對
basic_path
,
begin()
間的每個元素相繼應用
--end()
。
operator/=
string_type stem(const Path & p) const;
傳回: 如果包含一個'.',則傳回
p.filename()
中從開頭起至最後一個'.'的子串(不包含'.')。否則,傳回
p.filename()
。
p.filename()
string_type extension(const Path & p) const;
傳回: 如果包含一個'.',則傳回
p.filename()
p.filename()
中從最右一個'.'起至末尾的子串。否則,傳回一個空串。
[注: 傳回值中是包含'.'的,是以可以區分無擴充名和空擴充名。
具體實作可以允許但不要求為那些在擴充名上增加其它元素,如資料流或分區資料集名,的檔案系統定義額外的行為。 --注完]
bool empty() const;
傳回: string().empty()
.
bool is_complete() const;
傳回:, 如果 root_path()的元素唯一地辨別了一個目錄,否則傳回
true
.
false
bool has_root_path() const;
傳回: !root_path().empty()
bool has_root_name() const;
傳回: !root_name().empty()
bool has_root_directory() const;
傳回: !root_directory().empty()
bool has_relative_path() const;
傳回: !relative_path().empty()
bool has_leaf() const;
傳回: !leaf().empty()
bool has_branch_path() const;
傳回: !branch_path().empty()
basic_path
疊代器
basic_path
basic_path::iterator
是一個常量疊代器,它滿足雙向疊代器(C++ 标準, 24.1.4 Bidirectional iterators[lib.bidirectional.iterators])的所有要求。它的
value_type
為
string_type
.
對一個
basic_path
對象的任何非常性成員函數的調用
将使得引向該對象元素的所有疊代器均失效。
前向周遊的順序如下:
- root-name 元素,如果有的話。
- root-directory 元素,如果有的話。
- 每個相繼的 filename 元素,如果有的話。
- Dot, 如果尾部有一個或多個非根的"/"字元。
後向周遊的順序與前向周遊相反。
iterator begin() const;
傳回:一個指向上述周遊清單中第一個有效元素的疊代器。如果沒有這樣的元素,傳回結束疊代器。
iterator end() const;
傳回: 結束疊代器。
basic_path非成員函數
template<class String, class Traits>
void swap( basic_path<String, Traits> & lhs, basic_path<String, Traits> & rhs )
作用: lhs.swap(rhs )
basic_path非成員操作符
basic_path有七個非成員操作符(/,
==
,
!=
,
<
,
>
,
<=
,
>=
),每個操作符有五個重載。為簡單起見,以表格形式給出規格說明。得到的35個函數簽名中的每一個都是一個模闆,其模闆參數清單為 template
<classString, class Traits>
. 這些參數的格式在 路徑名格式 中描述。
參數類型重載 |
|
|
|
|
|
在 basic_path非成員操作符 表中,
a
和
b
為 參數類型重載 表中給出的類型。如果
a
或
b
的類型為
constbasic_path<String, Traits>&
, 則 a
'
或 b' 分别為
a
或
b
. 否則 a
'
或 b' 分别表示從
a
或
b
構造的有名或無名的
basic_path<String,Traits>
臨時對象。
basic_path非成員操作符 | ||
表達式 | 傳回類型 | 語義 |
| | b' |
| | a a b' b' |
| | a b' b' a |
| | a b' |
| | b' a |
| | b' a |
| | a b' |
[注: 路徑等同性和路徑等價性是具有不同語義的。
等同性由 basic_path 的非成員
operator==
判定,它隻考慮兩個路徑的字面表示。路徑 "abc" 和 "ABC" 是不等同的。
等價性則由 equivalent()非成員函數來判定,它根據兩個路徑是否 解析resolve為同一個檔案系統實體來判定。路徑 "abc" 和 "ABC" 可能是也可能不是被解析為同一個檔案,這取決于檔案系統。
想要判斷兩個路徑是否"相同"的程式員必須決定這裡所說的"相同"是指"相同的表示法"還是"解析為同一個檔案",并據此選擇适當的函數。 --注完]
basic_path
插入器和提取器
basic_path
template<class Path>
basic_istream<typename Path::string_type::value_type, typename Path::string_type::traits_type>&
operator>>(basic_istream< typename Path::string_type::value_type, typename Path::string_type::traits_type>& is,
Path& ph );
作用:傳回:
typenamePath::string_type str; is>> str; ph = str;
is
template<class Path>
basic_ostream<typename Path::string_type::value_type, typename Path::string_type::traits_type>&
operator<<(basic_ostream< typename Path::string_type::value_type, typename Path::string_type::traits_type>& os,
const Path& ph );
作用:傳回:
os<< ph.string()
os
類模闆 basic_filesystem_error
basic_filesystem_error
namespace boost
{
namespace filesystem
{
template <class Path> class basic_filesystem_error : public system_error
{
public:
typedef Path path_type;
explicit basic_filesystem_error(const std::string& what_arg, error_code ec);
basic_filesystem_error(const std::string& what_arg, const path_type& p1, error_code ec);
basic_filesystem_error(const std::string& what_arg, const path_type& p1, const path_type& p2, error_code ec);
const path_type& path1() const;
const path_type& path2() const;
const char * what() const;
};
} // namespace filesystem
} // namespace boost
類模闆
basic_filesystem_error
定義了一個被抛出的異常對象類型,它用于報告由本文中所列函數産生的檔案系統錯誤。
basic_filesystem_error
構造函數
basic_filesystem_error
explicit basic_filesystem_error(const std::string& what_arg, error_code ec);
後置條件:
表達式 值
runtime_error::what()
what_arg.c_str()
code()
ec
path1().empty()
true
path2().empty()
true
basic_filesystem_error(const std::string& what_arg, const path_type& p1, error_code ec);
後置條件:
表達式 值
runtime_error::what()
what_arg.c_str()
code()
ec
path1()
一個指向所儲存的
p1 拷貝的引用
path2().empty()
true
basic_filesystem_error(const std::string& what_arg, const path_type& p1, const path_type& p2, error_code ec);
後置條件:
表達式 值
runtime_error::what()
w
hat_arg.c_str()
code()
ec
path1()
一個指向所儲存的
p1 拷貝的引用
path2()
一個指向所儲存的
p2 拷貝的引用
basic_filesystem_error
觀察器
basic_filesystem_error
const path_type& path1() const;
傳回: 指向由構造函數所儲存的 p1
拷貝的引用,或者如果沒有這樣的拷貝則傳回空路徑。
const path_type& path2() const;
傳回: 指向由構造函數所儲存的 p2
拷貝的引用,或者如果沒有這樣的拷貝則傳回空路徑。
const char * what() const;
傳回: 一個字元串,包含及以
runtime_error::what()
作為第一參數調用
code()
system_message()
所得的結果。精确的格式未指定。
實作應該提供一個特化的
傳回一個字元串,其中包含
template<> const char* basic_filesystem_error<path>::what() const
以
runtime_error::what(),
作為第一參數調用
code()
所得的結果,并且如果非空,則還有
system_message()
和
path1().file_string()
path2.file_string()
. 精确的格式未指定。
實作和使用者都被允許提供
成員函數的其它特化。
what
類模闆 basic_directory_entry
basic_directory_entry
namespace boost
{
namespace filesystem
{
template <class Path> class basic_directory_entry
{
public:
typedef Path path_type;
typedef typename Path::string_type string_type;
// constructors
basic_directory_entry();
explicit basic_directory_entry(const path_type& p,
file_status st=file_status(), file_status symlink_st=file_status());
// modifiers
void assign(const path_type& p, file_status st=file_status(), file_status symlink_st=file_status());
void replace_filename(const string_type& s, file_status st=file_status(), file_status symlink_st=file_status());
// observers
const Path& path() const;
operator const Path&() const;
file_status status() const;
file_status status(error_code& ec) const;
file_status symlink_status() const;
file_status symlink_status(error_code& ec) const;
// comparisons
bool operator<(const basic_directory_entry<Path>& rhs);
bool operator==(const basic_directory_entry<Path>& rhs);
bool operator!=(const basic_directory_entry<Path>& rhs);
bool operator>(const basic_directory_entry<Path>& rhs);
bool operator<=(const basic_directory_entry<Path>& rhs);
bool operator>=(const basic_directory_entry<Path>& rhs);
private:
path_type m_path; // for exposition only
mutable file_status m_status; // for exposition only; stat()-like
mutable file_status m_symlink_status; // for exposition only; lstat()-like
};
} // namespace filesystem
} // namespace boost
basic_directory_entry
對象儲存了一個
basic_path對象,一個
用于非符号連結狀态的
file_status
對象,以及一個用于符号連結狀态的
file_status
對象。
file_status
對象擔當值緩存的角色。
[注: 因為一個路徑名的
status()
可能是一個非常昂貴的操作,有些作業系統以目錄疊代副産品的方式提供狀态資訊。緩存這些狀态資訊可以顯著地節約時間。在有競争條件的情況下,緩存與不緩存的結果可能會有所不同。-- 注完]
對一個有15,047項的目錄進行疊代,冷啟動狀态下以非緩存方式查詢狀态耗費6秒鐘,而采用緩存方式查詢狀态則隻要1秒鐘。測試環境為:WindowsXP, 3.0 GHz 處理器,帶一個較快的硬碟。在 Linux 和 BSD-系Unix 上進行目錄疊代的狀态查詢,也有類似的加速。
basic_directory_entry構造函數
basic_directory_entry構造函數
basic_directory_entry();
後置條件:
表達式 值
path().empty()
true
status()
file_status()
symlink_status()
file_status()
explicit basic_directory_entry(const path_type& p, file_status st=file_status(), file_status symlink_st=file_status());
後置條件:
表達式 值
path()
p
status()
st
symlink_status()
symlink_st
basic_directory_entry
修改器
basic_directory_entry
void assign(const path_type& p, file_status st=file_status(), file_status symlink_st=file_status());
後置條件:
表達式 值
path()
p
status()
st
symlink_status()
symlink_st
void replace_leaf(const string_type& s, file_status st=file_status(), file_status symlink_st=file_status());
後置條件:
表達式 值
path()
path().branch() / s
status()
st
symlink_status()
symlink_st
basic_directory_entry
觀察器
basic_directory_entry
const Path& path() const;
operator const Path&() const;
傳回: m_path
file_status status() const;
作用:就象:抛出: 參見if ( !status_known( m_status ) ) { if ( status_known(m_symlink_status) && !is_symlink(m_symlink_status) ) { m_status = m_symlink_status; } else { m_status = status(m_path); } }
status
函數。
傳回:
m_status
file_status status(error_code& ec) const;
作用:就象:傳回:if ( !status_known( m_status ) ) { if ( status_known(m_symlink_status) && !is_symlink(m_symlink_status) ) { m_status = m_symlink_status; } else { m_status = status(m_path, ec); } } else ec = 0;
m_status
file_status symlink_status() const;
作用:就旬:抛出: 參見if ( !status_known( m_symlink_status ) ) { m_symlink_status = symlink_status(m_path); }
symlink_status
函數。
傳回:
m_symlink_status
file_status symlink_status(error_code& ec) const;
作用:就象:傳回:if ( !status_known( m_symlink_status ) ) { m_symlink_status = symlink_status(m_path, ec); } else ec = 0;
m_symlink_status
類模闆 basic_directory_iterator
basic_directory_iterator
namespace boost
{
namespace filesystem
{
template <class Path>
class basic_directory_iterator :
public iterator<input_iterator_tag, basic_directory_entry<Path> >
{
public:
typedef Path path_type;
// constructors
basic_directory_iterator();
explicit basic_directory_iterator(const Path& dp);
basic_directory_iterator(const Path& dp, error_code& ec);
basic_directory_iterator(const basic_directory_iterator& bdi);
basic_directory_iterator& operator=(const basic_directory_iterator& bdi);
~basic_directory_iterator();
// other members as required by
// C++ Std, 24.1.1 Input iterators [lib.input.iterators]
};
} // namespace filesystem
} // namespace boost
basic_directory_iterator
符合輸入疊代器的要求(C++ 标準, 24.1.1, Input iterators [lib.input.iterators])。
basic_directory_iterator
從其構造的目錄中持續讀入元素,類似于調用 POSIX
readdir_r()
.當一個
basic_directory_iterator
被構造後,每一次調用
operator++
,它讀入并儲存一個
basic_directory_entry<Path>
值及其可能帶有的相關狀态值。
operator++
不保持等同性,即:
i== j
并不意味着
++i == ++j
.
[注: 不保持等同性的後果是,目錄疊代器隻能被用于單次周遊的算法。--注完]
如果到達目錄元素的末尾,疊代器将變為等同于 end 疊代器值。不帶參數的構造函數
basic_directory_iterator()
總是構造一個 end 疊代器對象,它是唯一一個用于結束條件的合法疊代器。一個 end 疊代器的
operator*
結果是未定義的。對于其它疊代器值,則傳回一個
constbasic_directory_entry<Path>&
. 一個 end疊代器的
operator->
結果也是未定義的。對于其它疊代器,則傳回一個
constbasic_directory_entry<Path>*
.
兩個 end 疊代器永遠都是相等的。一個 end 疊代器則不會等于一個非-end疊代器。
以上措詞基于标準庫的istream_iterator 措詞。注釋被縮短并移至注解。
對一個
basic_directory_iterator
進行提領所得的
basic_directory_entry
對象,調用其
path()
成員,将得到一個
basic_path
對象的引用,該對象由構造該疊代器的目錄參數,通過
operator/=
加上目錄項檔案名所組成。
[示例:該程式接受一個可選的指令行參數,如果該參數為目錄路徑名,則對該目錄的内容進行周遊。對于每個目錄項,輸出名字,如果某項為正常檔案則輸出檔案的大小。-- 示例完]#include <iostream> #include <filesystem> using std::tr2::sys; using std::cout; int main(int argc, char* argv[]) { std::string p(argc <= 1 ? "." : argv[1]); if (is_directory(p)) { for (directory_iterator itr(p); itr!=directory_iterator(); ++itr) { cout << itr->path().leaf() << ' '; // 隻顯示檔案名 if (is_regular(itr->status())) cout << " [" << file_size(itr->path()) << ']'; cout << '\n'; } } else cout << (exists(p) ? "Found: " : "Not found: ") << p << '\n'; return 0; }
目錄的周遊不會産生目前目錄(dot)和父目錄(dot dot)的目錄項。
一個
basic_directory_iterator
持續遞增及提領所得到的目錄項的順序未指定。
[注:執行目錄周遊的程式可能想要測試從目錄疊代器提領所得的路徑是否真的存在。它可能是一個指向某個并不存在的檔案的符号連結。對目錄樹進行遞歸周遊并進行删除或改名操作的程式則可能希望避免進入符号連結。
如果在一個目錄的
構造完成後,才在目錄中删除或加入一個檔案,則後續的疊代器遞增過程中是否會得到指向被删或被加入項的疊代器,是未指定的。參見 POSIX
basic_directory_iterator
.--注完]
readdir_r()
basic_directory_iterator
構造函數
basic_directory_iterator
basic_directory_iterator();
作用: 構造 end 疊代器。
explicit basic_directory_iterator(constPath& dp);
作用: 構造一個疊代器,表示由
dp
所解析得到的目錄中的第一項,否則為 end 疊代器。
[注: 要周遊目前目錄,要寫
而不是
directory_iterator(".")
.-- 注完]
directory_iterator("")
basic_directory_iterator(const Path& dp, error_code& ec );
作用: 構造一個疊代器,表示由所解析得到的目錄中的第一項,否則為 end 疊代器。如果在得到結果時發生錯誤,則所得疊代器為 end 疊代器且
dp
被設定為作業系統所報告的錯誤代碼,否則為 0.
ec
類模闆 basic_recursive_directory_iterator
basic_recursive_directory_iterator
namespace boost
{
namespace filesystem
{
template <class Path>
class basic_recursive_directory_iterator :
public iterator<input_iterator_tag, basic_directory_entry<Path> >
{
public:
typedef Path path_type;
// constructors
basic_recursive_directory_iterator();
explicit basic_recursive_directory_iterator(const Path& dp);
basic_recursive_directory_iterator(const basic_recursive_directory_iterator& brdi);
basic_recursive_directory_iterator& operator=(const basic_recursive_directory_iterator& brdi);
~basic_recursive_directory_iterator();
// observers
int level() const;
// modifiers
void pop();
void no_push();
// other members as required by
// C++ Std, 24.1.1 Input iterators [lib.input.iterators]
private:
int m_level; // for exposition only
};
} // namespace filesystem
} // namespace boost
basic_recursive_directory_iterator
的行為與
basic_directory_iterator
相同,除了特别說明。
- 一個疊代器被構造後,
設為 0;m_level
- 遞增一個疊代器時,如果
為 true 且it->is_directory()
沒有緊接着最後一個遞增操作(或構造時)調用,則no_push()
被遞增,并進入該目錄且遞歸周遊其内容。m_level
- 當一個疊代器到達其目前周遊的目錄末尾時,或者
被調用時,pop()
被遞減,且後續将對父目錄進行周遊,直至到達構造函數的參數所指定的目錄。m_level
-
傳回level()
.m_level
-
,level()
,和pop()
都要求該疊代器不是 end 疊代器。no_push()
[注: no_push()
的一個用法是防止遞歸進入符号連結的目錄。為防止某些作業系統上的循環通路,這是必須的。--注完]
類 file_status
namespace boost
{
namespace filesystem
{
class file_status
{
public:
explicit file_status( file_type v = status_unknown );
file_type type() const;
void type( file_type v );
};
} // namespace filesystem
} // namespace boost
file_status
對象儲存了關于一個檔案的狀态的資訊。所儲存的資訊的内部形式未指定。
[注: 未來該類可能會被擴充,以儲存更多的資訊。--注完]
成員
explicit file_status( file_type v = status_unknown );
作用: 儲存 v
.
file_type type() const;
傳回: 所儲存的 file_type
.
void type( file_type v );
作用: 儲存 v
,替換原先儲存的值。
非成員操作函數
狀态函數
template <class Path> file_status status(const Path& p, error_code& ec);
template <class Path> file_status symlink_status(const Path& p, error_code& ec);
傳回:對于[注:确定
status,
的屬性就象 POSIX
p
,而對于
stat()
确定的屬性則象 POSIX
symlink_status
.
lstat()
[注: 對于符号連結,如果在屬性确定過程中,作業系統報告了錯誤,則:會用符号連結的内容繼續進行路徑名解析,而
stat()
則不會。--注完]
lstat()
- 如果錯誤說明
不能被解析,象 POSIX 的錯誤代碼ENOENT 或 ENOTDIR 那樣,則設定 ec 為 0 并傳回
p
.
file_status(not_found_flag)
否則:
- 否則,設定 ec 為作業系統報告的錯誤代碼并傳回
.
file_status(status_unknown)
- 如果屬性顯示是一個正常檔案,如 POSIX S_ISREG(),則傳回
.
file_status(regular_file)
- 否則如果屬性顯示是一個目錄,如 POSIX S_ISDIR(),則傳回
.
file_status(directory_file)
- 否則如果屬性顯示是一個符号連結,如 POSIX S_ISLNK(),則傳回
. [注:隻能用于
file_status(symlink_file)
. --注完]
symlink_status
- 否則如果屬性顯示是一個塊裝置檔案,如 POSIX S_ISBLK(),則傳回
.
file_status(block_file)
- 否則如果屬性顯示是一個字元裝置檔案,如 POSIX S_ISCHR(),則傳回
.
file_status(character_file)
- 否則如果屬性顯示是一個 fifo 或管道檔案,如 POSIX S_ISFIFO(),則傳回
.
file_status(fifo_file)
- 否則如果屬性顯示是一個 socket, 如 POSIX S_ISSOCK(),則傳回
.
file_status(socket_file)
- 否則傳回
.
file_status(type_unknown)
表示在這個檔案上可以使用
directory_file
,而
basic_directory_iterator
則表示可以使用适當的
regular_file
操作,假如沒有硬體、權限、通路和競争條件的錯誤。對于
<fstream>
反之則不一定為真;不是
regular_file,
并不一定就表示
regular_file
操作不能用于目錄。-- 注完]
<fstream>
template <class Path> file_status status(const Path& p);
作用:
system_error_code ec;
抛出:
file_status stat(status(p, ec));
如果
basic_filesystem_error<Path>
傳回:
ec != 0
stat
template <class Path> file_status symlink_status(const Path& p);
作用:
system_error_code ec;
抛出:
file_status stat(symlink_status(p, ec));
如果
basic_filesystem_error<Path>
傳回:
ec != 0
stat
謂詞函數
bool status_known(file_status s);
傳回: s.type()!= status_unknown
bool exists(file_status s);
傳回: status_known(s)&& s.type() != file_not_found
template <class Path> bool exists(const Path& p);
傳回: exists( status(p) )
bool is_regular (file_status s);
傳回: s.type()== regular_file
template <class Path> bool is_regular(const Path& p);
傳回: is_regular( status(p) )
bool is_directory (file_status s);
傳回: s.type()== directory_file
template <class Path> bool is_directory(const Path& p);
傳回: is_directory( status(p) )
bool is_symlink(file_status s);
傳回: s.type()== symlink_file
template <class Path> bool is_symlink(const Path& p);
傳回: is_symlink( symlink_status(p) )
bool is_other(file_status s);
傳回:[注:
returnexists(s) && !is_regular(s) &&!is_directory(s) && !is_symlink(s)
的規格保持不變,即使以後會加入
is_other()
函數。-- 注完]
is_xxx()
template <class Path> bool is_other(const Path& p);
傳回: is_other( status(p) )
template <class Path> bool is_empty(const Path& p);
作用: 确定,如
file_status s
status(p)
.
抛出:
如果
basic_filesystem_error<Path>
!exist(s) || is_other(s)
.
傳回:
is_directory(s) ? basic_directory_iterator<Path>(p) ==basic_directory_iterator<Path>() : file_size(p) == 0;
template <class Path1, class Path2> bool equivalent(const Path1& p1, const Path2& p2);
要求:和
Path1::external_string_type
Path2::external_string_type
為相同類型。
作用: 确定
和
file_status s1
, 就如
s2
和
status(p1)
status(p2)
.
抛出:
如果
basic_filesystem_error<Path1>
(!exists(s1) && !exists(s2)) ||(is_other(s1) && is_other(s2))
.
傳回:
, 如果
true
且
sf1 == sf2
和
p1
解析為同一個檔案系統實體,否則傳回
p2
false
.
兩個路徑被認為是解析為同一個檔案系統實體,如果這兩個候選實體位于同一裝置的同一位置。這就象 POSIX
結構的值所确定的那樣,對兩個路徑調用
stat
所得到的值,具有相等的
stat()
值和相等的
st_dev
st_ino
值。
[注: POSIX 要求"st_dev在一個LAN中必須是唯一的"。舊的 POSIX 實作可能還會檢查
和
st_size
值是否相等。Windows實作可能用
st_mtime
代替
GetFileInformationByHandle()
, 并認為"同一檔案"是指
stat()
,
dwVolumeSerialNumber
,
nFileIndexHigh
,
nFileIndexLow
,
nFileSizeHigh
,
nFileSizeLow
, 和
ftLastWriteTime.dwLowDateTime
值的相等。-- 注完]
ftLastWriteTime.dwHighDateTime
屬性函數
[注:可提供的屬性函數數量是嚴格受限的,因為隻有少量檔案系統屬性是可移植的。即使提供了這些函數,在某些檔案系統上也不可能實作。--注完]
template <class Path> const Path& initial_path();
傳回: 進入時的
main()
current_path()
.
[注: 該語義将一個危險的全局變量變為一個安全的全局常量。--注完]
[注:完整的實作需要運作期庫的支援。不能提供運作期庫支援的實作被建議儲存第一次調用
initial_path
時所得的
()
值 ,并在後續調用時傳回該值。使用
current_path()
initial_path
的程式建議在進入
()
後立即調用它,這樣在這些實作中才可以正确工作。--注完]
main()
template <class Path> Path current_path();
傳回: 目前路徑,如 POSIX
getcwd()
.
後置條件:
[注:許多作業系統傳回的目前路徑都是一個危險的全局變量。它可能會被某個第三方庫或系統庫的函數所修改,或者被其它線程修改。雖然危險,但是該函數在處理其它庫函數時非常有用。作為一個安全的選擇,請見
current_path().is_complete()
.選擇
initial_path()
這個名字,是為了強調傳回的是一個完整的路徑,而不是單個目錄名。-- 注完]
current_path()
template <class Path> void current_path(const Path& p);
後置條件: equivalent( p, current_path() );
template <class Path> uintmax_t file_size(const Path& p);
傳回: 由所解析得到的檔案的位元組大小,類似于由 POSIX
p
所得到的 POSIX
stat()
結構的成員
stat
中所确定的。
st_size
template <class Path> space_info space(const Path& p);
傳回: 一個對象。該
space_info
對象的值按以下方法确定,用 POSIX
space_info
得到一個 POSIX 構造
statvfs()
,然後以用其
statvfs
成員與
f_frsize
,
f_blocks
, 和
f_bfree
成員相乘,将結果分别指派給
f_bavail
,
capacity
,和
free
成員。無法确定值的成員将被設為 -1.
available
template <class Path> std::time_t last_write_time(const Path& p);
傳回:的最後修改時間,即通過 POSIX
p
獲得的 POSIX
stat()
結構的成員
stat
的值。
st_mtime
template <class Path> void last_write_time(const Path& p, const std::time_t new_time);
作用: 将所解析得到的檔案的最後修改時間設定為
p
, 就象 POSIX
new_time
後跟 POSIX
stat()
utime()
.
[注: 後置條件
未被指定,因為對于多數檔案系統,由于時間機制的粒度較粗而未能保證該條件。--注完]
last_write_time(p)== new_time
其它操作函數
template <class Path> bool create_directory(const Path& dp);
作用: 嘗試建立一個由解析得到的目錄,如 POSIX
dp
mkdir()
,以 S_IRWXU|S_IRWXG|S_IRWXO 為第二參數。
抛出:
basic_filesystem_error<Path>
如果上述作用因除目錄已存在以外的原因而失敗。
傳回: True 如果建立了新目錄,否則傳回 false.
後置條件:
is_directory(dp)
template <class Path1, class Path2>
error_code create_hard_link(const Path1& to_p, const Path2& from_p, error_code& ec);
要求:和
Path1::external_string_type
Path2::external_string_type
為相同類型。
作用: 建立後置條件,如 POSIX
link()
.
傳回:如果後置條件不能建立,傳回一個表示失敗原因的系統錯誤代碼,否則傳回 0.
後置條件:
[注:有些作業系統不支援硬連結或隻對正常檔案支援硬連結。有些作業系統則限制每個檔案的連結數量。有些檔案系統不支援硬連結 -如用于軟碟、存儲卡和閃存盤的 FAT 系統。是以如果代碼的移植性是關鍵,則應避免硬連結。 -- 注完]
exists(to_p)&& exists(from_p) && equivalent(to_p,from_p)
所解析的檔案或目錄的内容不變。
to_p
template <class Path1, class Path2>
void create_hard_link(const Path1& to_p, const Path2& from_p);
要求:和
Path1::external_string_type
Path2::external_string_type
為相同類型。
作用: 如
抛出:
system_error_codeec( create_hard_link( to_p, from_p ) );
如果
basic_filesystem_error<Path1,Path2>
不為零。
ec
template <class Path1, class Path2>
error_code create_symlink(const Path1& to_p, const Path2& from_p, error_code& ec);
要求:和
Path1::external_string_type
Path2::external_string_type
為相同類型。
作用: 建立後置條件,如 POSIX
symlink()
.
傳回:如果後置條件不能建立,則傳回表示失敗原因的系統錯誤代碼,否則傳回 0.
後置條件:
解析為一個符号連結檔案,包含一個對
from_p
to_p
的未指定表示。
[注:有些作業系統不支援符号連結或隻對正常檔案支援。是以如果代碼的可移植性是關鍵,則應避免符号連結。-- 注完]
template <class Path1, class Path2>
void create_symlink(const Path1& to_p, const Path2& from_p);
要求:和
Path1::external_string_type
Path2::external_string_type
為相同類型。
作用: 如
抛出:
system_error_codeec( create_symlink( to_p, from_p ) );
如果
basic_filesystem_error<Path1,Path2>
不為零。
ec
template <class Path> void remove(const Path& p, system::error_code & ec = singular );
作用: 删除檔案,如 POSIX
p
.如果底層實作沒有錯誤報告或如果
remove()
, 則:
status(p).type() == file_not_found
否則,
- 如果
ec !=
,則
singular
.
ec.clear()
後置條件:
- 如果
ec !=
,則設定
singular
以表示該錯誤。
ec
- 否則,抛出
以表示該錯誤。如果
basic_filesystem_error<Path>
ec !=
,則
singular
ec.clear()
!exists(p)
抛出: 參見 作用。
[注: 對于符号連結,其本身被删除,而不是其所解析的檔案被删除。--注完]
template <class Path> unsigned long remove_all(const Path& p);
作用: 遞歸删除 p中的内容如果它存在,則删除檔案本身,如 POSIX
p
remove()
.
傳回: 删除檔案的數量。
後置條件:
[注: 對于符号連結,其本身被删除,而不是其所解析的檔案被删除。--注完]
!exists(p)
template <class Path1, class Path2> void rename(const Path1& from_p, const Path2& to_p);
要求:和
Path1::external_string_type
Path2::external_string_type
為相同類型。
作用: 将
改名為
from_p
, 如 POSIX
to_p
rename()
.
後置條件:
, 且原來名為
!exists(from_p)&& exists(to_p)
from_p
的檔案的内容和屬性不變。
[注: 如果
和
from_p
為同一檔案,則無操作。否則,如果
to_p
為已有檔案,則被删除。對于符号連結,其本身被改名,而不是其所指檔案被改名。-- 注完]
to_p
template <class Path1, class Path2>
void copy_file(const Path1& from_fp, const Path2& to_fp,
BOOST_SCOPED_ENUM(copy_option) option=copy_option::fail_if_exists);
要求:和
Path1::external_string_type
Path2::external_string_type
為相同類型。
作用:
所代表檔案的内容和屬性被複制至
from_fp
to_fp
所代表的檔案。
抛出:
if
basic_filesystem_error<Path>
from_fp.empty() || to_fp.empty() ||!exists(from_fp) || !is_regular_file(from_fp) || (option==copy_option::fail_if_exists && exists(to_fp))
template <class Path> Path complete(const Path& p, const Path& base=initial_path<Path>());
作用: 從和
p
組合一個完整的路徑,使用以下規則:
base
p.has_root_directory()
!p.has_root_directory()
p.has_root_name()
p
前提條件不滿足
!p.has_root_name()
base.root_name() / p
base / p
傳回: 組成的路徑。
後置條件: 對于傳回的路徑
rp,
rp.is_complete()
為 true.
抛出: 如果
!(base.is_complete()&& (p.is_complete() || !p.has_root_name()))
[注:如果需要可移植的行為,請使用 complete(). 如果需要與作業系統相關的行為,則使用 system_complete().
如果要處理程式内部建立的路徑,則應使用可移植行為,特别是如果程式要在所有作業系統上表現出相同的行為。
如果要處理由使用者輸入的路徑,或向使用者輸出,或使用者期望的類似行為,則應使用與作業系統相關的行為。-- 注完]
template <class Path> Path system_complete(const Path& p);
作用: 從
p
組成一個完整路徑,使用與作業系統解析一個傳給标準庫 open 函數的路徑的相同規則。
傳回: 組成的路徑。
後置條件: 對于傳回的路徑
rp,
rp.is_complete()
為 true.
抛出: 如果
p.empty()
.
[注: 對于 POSIX,
具有與
system_complete(p)
complete(p, current_path())
相同的語義。
對于 Windows,如果
或
p.is_complete() || !p.has_root_name()
和
p
具有相同的
base
root_name(),則
具有與
system_complete(p)
相同的語義。否則類似于
complete(ph, current_path())
, 其中
complete(p,kinky)
為
kinky
p.root_name()
驅動器的目前目錄。它是該驅動器最後一次被設定的目前目錄,是以可能是指令處理器所運作的上一個程式所遺留下來的!雖然這些語義常常被用到,但也是非常容易出錯的。
有關用法的建議,請見 complete()注解。-- 注完]
便利函數
template <class Path> bool create_directories(const Path & p);
要求:傳回: 達成後置條件之前的
p.empty() || 對于所有 px: px == p || is_parent(px, p): is_directory(px) || !exists( px )
!exists(p)
值。
後置條件:
抛出:
is_directory(p)
如果
basic_filesystem_error<Path>
exists(p) && !is_directory(p)
不贊成使用的便利函數以下函數已被 的成員函數 , , 及 所替代。 傳回: 如果 傳回: 如果 後置條件: |
對頭檔案 <fstream>的增加
<fstream>的增加
以下新增的規格是經過仔細考慮,以避免破壞在常用操作環境,如 POSIX, Windows,和 OpenVMS中的已有代碼。有關避免在其它環境中破壞已有代碼,請參見 對
<fstream>
實作的建議,尤其是在那些允許斜杠号出現在檔案名中的作業系統。
[注:來自 對實作的要求 中的"do-the-right-thing"規則被應用于頭檔案
<fstream>
.
以下給出的重載是新增的,而不是替換已有函數。這樣保護了那些依賴于到
的自動轉換的已有代碼(可能使用了自已的路徑類)。--注完]
constchar*
在27.8.1.1 Class template basic_filebuf [lib.filebuf] 概要的第1段,增加函數:
template <class Path> basic_filebuf<charT,traits>* open(const Path& p, ios_base::openmode mode);
在27.8.1.3 Member functions [lib.filebuf.members], 将上述增加到第2段的簽名中,并替換句子:
Itthen opens a file, if possible, whose name is the NTBS s (“as if” bycalling std::fopen(s ,modstr ))
.
為:
Itthen opens, if possible, the file thator
p
resolves to, “as if” by calling
path(s)
with a second argument of modstr.
std::fopen()
在 27.8.1.5Class template basic_ifstream [lib.ifstream] 概要的第1段,增加函數:
template <class Path> explicit basic_ifstream(const Path& p, ios_base::openmode mode = ios_base::in); template <class Path> void open(const Path& p, ios_base::openmode mode = ios_base::in);
在 27.8.1.6basic_ifstream constructors [lib.ifstream.cons] 中增加上述構造函數到第2段的簽名中,并替換
rdbuf()->open(s,mode | ios_base::in)
為
or
rdbuf()->open(path(s),mode | ios_base::in)
as appropriate
rdbuf()->open(p,mode | ios_base::in)
在 27.8.1.7Member functions [lib.ifstream.members]中增加上述open 函數到第3段的簽名中,并替換
rdbuf()->open(s,mode | ios_base::in)
為
or
rdbuf()->open(path(s),mode | ios_base::in)
as appropriate
rdbuf()->open(p,mode | ios_base::in)
在 27.8.1.8Class template basic_ofstream [lib.ofstream] 概要的第1段,增加函數:
template <class Path> explicit basic_ofstream(const Path& p, ios_base::openmode mode = ios_base::out); template <class Path> void open(const Path& p, ios_base::openmode mode = ios_base::out);
在 27.8.1.9basic_ofstream constructors [lib.ofstream.cons] 中增加上述構造函數到第2段的簽名中,并替換
rdbuf()->open(s,mode | ios_base::out)
為
or
rdbuf()->open(path(s),mode | ios_base::out)
as appropriate
rdbuf()->open(p,mode | ios_base::out)
在 27.8.1.10Member functions [lib.ofstream.members]中增加上述open 函數到第3段的簽名中,并替換
rdbuf()->open(s,mode | ios_base::out)
為
or
rdbuf()->open(path(s),mode | ios_base::out)
as appropriate
rdbuf()->open(p,mode | ios_base::out)
在 27.8.1.11Class template basic_fstream [lib.fstream] 概要第1段,增加函數:
template <class Path> explicit basic_fstream(const Path& p, ios_base::openmode mode = ios_base::in|ios_base::out); template <class Path> void open(const Path& p, ios_base::openmode mode = ios_base::in|ios_base::out);
在 27.8.1.12basic_fstream constructors [lib.fstream.cons] 中增加上述構造函數到第2段的簽名中,并替換
rdbuf()->open(s,mode)
為
or
rdbuf()->open(path(s),mode)
as appropriate
rdbuf()->open(p, mode)
在 27.8.1.13Member functions [lib.fstream.members]中增加上述open 函數到第3段的簽名中,并替換
rdbuf()->open(s,mode)
為
or
rdbuf()->open(path(s),mode)
as appropriate
rdbuf()->open(p, mode)
建議文本結束。
路徑分解表
該表由以 Boost 實作編譯的程式生成。
有底色的項表示 POSIX 和 Windows實作會産生不同結果。上方的值為POSIX 結果而下方的值為 Windows 結果。
構造函數參數 | 周遊所找到的元素 | | | | | | | | |
| | | | | | | | | |
| | | | | | | | | |
| | | | | | | | | |
| | | | | | | | | |
| | | | | | | | | |
| | | | | | | | | |
| | | | | | | | | |
| | | | | | | | | |
| | | | | | | | | |
| | | | | | | | | |
| | | | | | | | | |
| | | | | | | | | |
| | | | | | | | | |
| | | | | | | | | |
| | | | | | | | | |
| | | | | | | | | |
| | | | | | | | | |
| | | | | | | | | |
| | | | | | | | | |
| | | | | | | | | |
| | | | | | | | | |
| | | | | | | | | |
| | | | | | | | | |
| | | | | | | | | |
| | | | | | | | | |
| | | | | | | | | |
| | | | | | | | | |
| | | | | | | | | |
| | | | | | | | | |
| | | | | | | | | |
| | | | | | | | | |
| | | | | | | | | |
| | | | | | | | | |
| | | | | | | | | |
| | | | | | | | | |
| | | | | | | | | |
| | | | | | | | | |
| | | | | | | | | |
對 <fstream>
實作的建議
<fstream>
對于接受
const char*
參數的函數的語義的改動會破壞已有代碼,但是僅會發生在那些不支援 隐式接受原生格式路徑名 或允許斜杠号用于檔案名的作業系統中。是以在 POSIX, Windows,和 OpenVMS 上,如果實作遵守推薦行為就不會有問題。
對于多數 Filesystem 庫,并沒有已有代碼,是以在檔案名中使用斜杠号的問題并不會發生。新代碼隻須使用帶有
path_format_t
參數的basic_path 構造函數。為保護那些在檔案名中使用了斜杠号的已有 fstream代碼,實作可能要提供一個機制,如某個宏,來控制選用舊的行為。
TR的前頁已要求具體實作要提供一個機制,如某個宏,來控制頭檔案選用舊的行為(為了保護已有代碼)或新的行為(用于新代碼以及從其它系統移植來的代碼)。因為 Filesystem 庫的其餘部分的使用與
<fstream>
新增内容無關,是以建議受到影響的實作可以與其它TR特性分開,單獨禁用
<fstream>
新增内容。
另一種被拒絕的選擇是,在名字空間
filesystem
中提供新的 fstream類,它們派生自目前的類,覆寫各個構造函數和 open 函數,接受路徑名參數,并提供其它重載。在 Lillehammer LWG members中說明了這一方法的缺點,感覺上它的開銷高于所獲得的好處。
鳴謝
This Filesystem Library is dedicated to my wife, Sonda, whoprovided the support necessary to see both a trial implementation andthe proposal itself through to completion. She gave me the strength tocontinue after a difficult year of cancer treatment in the middle of itall.
Many people contributed technical comments, ideas, andsuggestions to the Boost Filesystem Library. Seehttp://www.boost.org/libs/filesystem/doc/index.htm#Acknowledgements.
Dietmar Kühl contributed the original Boost Filesystem Librarydirectory_iterator design. Peter Dimov, Walter Landry, Rob Stewart, andThomas Witt were particularly helpful in refining the library.
The create_directories, extension, basename, andreplace_extension functions were developed by Vladimir Prus.
Howard Hinnant and John Maddock reviewed a draft of theproposal, and identified a number of mistakes or weaknesses, resultingin a more polished final document.
參考
[ISO-POSIX] | ISO/IEC 9945:2003,IEEE Std 1003.1-2001, and The Open Group BaseSpecifications, Issue 6. Also known as The Single Unix® Specification, Version 3. Availablefrom each of the organizations involved in its creation. For example,read online or download from www.unix.org/single_unix_specification/. The ISOJTC1/SC22/WG15 - POSIX homepage is www.open-std.org/jtc1/sc22/WG15/ |
[Abrahams] | Dave Abrahams, Error and ExceptionHandling, www.boost.org/more/error_handling.html |
© Copyright Beman Dawes, 2002, 2006, 2007
Distributed under the Boost Software License, Version 1.0. Seewww.boost.org/LICENSE_1_0.txt
Revised 17 May 2009