cppdraft_translate/cppdraft/fs/class/path/general.md

[fs.class.path.general]

31 Input/output library [input.output]

31.12 File systems [filesystems]

31.12.6 Class path [fs.class.path]

31.12.6.1 General [fs.class.path.general]

1

#

An object of class path represents a path and contains a pathname.

Such an object is concerned only with the lexical and syntactic aspects of a path.

The path does not necessarily exist in external storage, and the pathname is not necessarily valid for the current operating system or for a particular file system.

2

#

[Note 1:

Class path is used to support the differences between the string types used by different operating systems to represent pathnames, and to perform conversions between encodings when necessary.

— end note]

3

#

A path is a sequence of elements that identify the location of a file within a filesystem.

The elements are theroot-nameopt,root-directoryopt, and an optional sequence of filenames ([fs.path.generic]).

The maximum number of elements in the sequence is operating system dependent ([fs.conform.os]).

4

#

An absolute path is a path that unambiguously identifies the location of a file without reference to an additional starting location.

The elements of a path that determine if it is absolute are operating system dependent.

A relative path is a path that is not absolute, and as such, only unambiguously identifies the location of a file when resolved relative to an implied starting location.

The elements of a path that determine if it is relative are operating system dependent.

[Note 2:

Pathnames “.” and “..” are relative paths.

— end note]

5

#

A pathname is a character string that represents the name of a path.

Pathnames are formatted according to the generic pathname format grammar ([fs.path.generic]) or according to an operating system dependentnative pathname format accepted by the host operating system.

6

#

Pathname resolution is the operating system dependent mechanism for resolving a pathname to a particular file in a file hierarchy.

There may be multiple pathnames that resolve to the same file.

[Example 1:

For POSIX-based operating systems, this mechanism is specified in POSIX, section 4.12, Pathname resolution.

— end example]

namespace std::filesystem {class path {public:using value_type = see below; using string_type = basic_string<value_type>; static constexpr value_type preferred_separator = see below; // [fs.enum.path.format], enumeration formatenum format; // [fs.path.construct], constructors and destructor path() noexcept; path(const path& p); path(path&& p) noexcept; path(string_type&& source, format fmt = auto_format); template path(const Source& source, format fmt = auto_format); template path(InputIterator first, InputIterator last, format fmt = auto_format); template path(const Source& source, const locale& loc, format fmt = auto_format); template path(InputIterator first, InputIterator last, const locale& loc, format fmt = auto_format); ~path(); // [fs.path.assign], assignments path& operator=(const path& p); path& operator=(path&& p) noexcept; path& operator=(string_type&& source); path& assign(string_type&& source); template path& operator=(const Source& source); template path& assign(const Source& source); template path& assign(InputIterator first, InputIterator last); // [fs.path.append], appends path& operator/=(const path& p); template path& operator/=(const Source& source); template path& append(const Source& source); template path& append(InputIterator first, InputIterator last); // [fs.path.concat], concatenation path& operator+=(const path& x); path& operator+=(const string_type& x); path& operator+=(basic_string_view<value_type> x); path& operator+=(const value_type* x); path& operator+=(value_type x); template path& operator+=(const Source& x); template path& operator+=(EcharT x); template path& concat(const Source& x); template path& concat(InputIterator first, InputIterator last); // [fs.path.modifiers], modifiersvoid clear() noexcept; path& make_preferred(); path& remove_filename(); path& replace_filename(const path& replacement); path& replace_extension(const path& replacement = path()); void swap(path& rhs) noexcept; // [fs.path.nonmember], non-member operatorsfriend bool operator==(const path& lhs, const path& rhs) noexcept; friend strong_ordering operator<=>(const path& lhs, const path& rhs) noexcept; friend path operator/(const path& lhs, const path& rhs); // [fs.path.native.obs], native format observersconst string_type& native() const noexcept; const value_type* c_str() const noexcept; operator string_type() const; template<class EcharT, class traits = char_traits, class Allocator = allocator> basic_string<EcharT, traits, Allocator> string(const Allocator& a = Allocator()) const; std::string display_string() const; std::string system_encoded_string() const; std::wstring wstring() const; std::u8string u8string() const; std::u16string u16string() const; std::u32string u32string() const; // [fs.path.generic.obs], generic format observerstemplate<class EcharT, class traits = char_traits, class Allocator = allocator> basic_string<EcharT, traits, Allocator> generic_string(const Allocator& a = Allocator()) const; std::string generic_display_string() const; std::string generic_system_encoded_string() const; std::wstring generic_wstring() const; std::u8string generic_u8string() const; std::u16string generic_u16string() const; std::u32string generic_u32string() const; // [fs.path.compare], compareint compare(const path& p) const noexcept; int compare(const string_type& s) const; int compare(basic_string_view<value_type> s) const; int compare(const value_type* s) const; // [fs.path.decompose], decomposition path root_name() const; path root_directory() const; path root_path() const; path relative_path() const; path parent_path() const; path filename() const; path stem() const; path extension() const; // [fs.path.query], querybool empty() const noexcept; bool has_root_name() const; bool has_root_directory() const; bool has_root_path() const; bool has_relative_path() const; bool has_parent_path() const; bool has_filename() const; bool has_stem() const; bool has_extension() const; bool is_absolute() const; bool is_relative() const; // [fs.path.gen], generation path lexically_normal() const; path lexically_relative(const path& base) const; path lexically_proximate(const path& base) const; // [fs.path.itr], iteratorsclass iterator; using const_iterator = iterator;

iterator begin() const; iterator end() const; // [fs.path.io], path inserter and extractortemplate<class charT, class traits>friend basic_ostream<charT, traits>&operator<<(basic_ostream<charT, traits>& os, const path& p); template<class charT, class traits>friend basic_istream<charT, traits>&operator>>(basic_istream<charT, traits>& is, path& p); };}

7

#

value_type is a typedef for the operating system dependent encoded character type used to represent pathnames.

8

#

The value of the preferred_separator member is the operating system dependent preferred-separator character ([fs.path.generic]).

9

#

[Example 2:

For POSIX-based operating systems,value_type is char andpreferred_separator is the slash character ('/').

For Windows-based operating systems,value_type is wchar_t andpreferred_separator is the backslash character (L'\').

— end example]