Class path

boost::filesystem::path — Filesystem path class.

Synopsis

// In header: <boost/filesystem/path.hpp>


class path {
public:
  // types
  typedef unspecified                                   value_type;              // Character type used by the operating system API to represent paths. 
  typedef std::basic_string< value_type >               string_type;             // String type used by the operating system API to represent paths. 
  typedef std::codecvt< wchar_t, char, std::mbstate_t > codecvt_type;            // Character code conversion facet type used to convert path strings between character types. 
  typedef unspecified                                   iterator;                // Iterator over path elements. 
  typedef unspecified                                   const_iterator;          // Iterator over path elements. 
  typedef unspecified                                   reverse_iterator;        // Reverse iterator over path elements. 
  typedef unspecified                                   const_reverse_iterator;  // Reverse iterator over path elements. 

  // constructors
  path() noexcept;
  path(path const &);
  path(path const &, codecvt_type const &);
  path(path &&) noexcept;
  path(path &&, codecvt_type const &) noexcept;
  template<typename Source> path(Source const &);
  template<typename Source> 
    explicit path(Source const &, codecvt_type const &);
  path(string_type &&) noexcept;
  path(string_type &&, codecvt_type const &) noexcept;
  template<typename InputIterator> path(InputIterator, InputIterator);
  template<typename InputIterator> 
    path(InputIterator, InputIterator, codecvt_type const &);
  path(std::nullptr_t) = delete;

  // assignment
  path & operator=(path const &);
  path & assign(path const &);
  path & assign(path const &, codecvt_type const &);
  path & operator=(path &&) noexcept;
  path & assign(path &&) noexcept;
  path & assign(path &&, codecvt_type const &) noexcept;
  path & operator=(string_type &&) noexcept;
  path & assign(string_type &&) noexcept;
  path & assign(string_type &&, codecvt_type const &) noexcept;
  template<typename Source> path & operator=(Source const &);
  template<typename Source> path & assign(Source const &);
  template<typename Source> 
    path & assign(Source const &, codecvt_type const &);
  template<typename InputIterator> path & assign(InputIterator, InputIterator);
  template<typename InputIterator> 
    path & assign(InputIterator, InputIterator, codecvt_type const &);
  path & operator=(std::nullptr_t) = delete;

  // concatenation
  template<typename Char> path & operator+=(Char);
  path & operator+=(path const &);
  path & concat(path const &);
  path & concat(path const &, codecvt_type const &);
  template<typename Source> path & operator+=(Source const &);
  template<typename Source> path & concat(Source const &);
  template<typename Source> 
    path & concat(Source const &, codecvt_type const &);
  template<typename InputIterator> path & concat(InputIterator, InputIterator);
  template<typename InputIterator> 
    path & concat(InputIterator, InputIterator, codecvt_type const &);

  // appending
  path & operator/=(path const &);
  path & append(path const &);
  path & append(path const &, codecvt_type const &);
  template<typename Source> path & operator/=(Source const &);
  template<typename Source> path & append(Source const &);
  template<typename Source> 
    path & append(Source const &, codecvt_type const &);
  template<typename InputIterator> path & append(InputIterator, InputIterator);
  template<typename InputIterator> 
    path & append(InputIterator, InputIterator, const codecvt_type &);

  // modifiers
  void clear() noexcept;
  path & make_preferred();
  path & remove_filename();
  path & remove_filename_and_trailing_separators();
  path & remove_trailing_separator();
  path & replace_filename(path const &);
  path & replace_extension(path const & = path());
  void swap(path &) noexcept;

  // observers
  bool empty() const noexcept;
  bool filename_is_dot() const;
  bool filename_is_dot_dot() const;
  bool has_root_path() const;
  bool has_root_name() const;
  bool has_root_directory() 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_relative() const;
  bool is_absolute() const;
  string_type const & native() const noexcept;
  const value_type * c_str() const noexcept;
  string_type::size_type size() const noexcept;
  template<typename String> String string() const;
  template<typename String> String string(codecvt_type const &) const;
  std::string string() const;
  std::string string(codecvt_type const &) const;
  std::wstring wstring() const;
  std::wstring wstring(codecvt_type const &) const;
  path generic_path() const;
  template<typename String> String generic_string() const;
  template<typename String> String generic_string(codecvt_type const &) const;
  std::string generic_string() const;
  std::string generic_string(codecvt_type const &) const;
  std::wstring generic_wstring() const;
  std::wstring generic_wstring(codecvt_type const &) const;

  // comparison
  int compare(path const &) const;
  template<typename Source> int compare(Source const &) const;
  template<typename Source> 
    int compare(Source const &, codecvt_type const &) const;

  // decomposition
  path root_path() const;
  path root_name() const;
  path root_directory() const;
  path relative_path() const;
  path parent_path() const;
  path filename() const;
  path stem() const;
  path extension() const;

  // lexical operations
  path lexically_normal() const;
  path lexically_relative(path const &) const;
  path lexically_proximate(path const &) const;

  // iterators
  iterator begin() const;
  iterator end() const;
  reverse_iterator rbegin() const;
  reverse_iterator rend() const;

  // locale operations
  static std::locale imbue(std::locale const &);
  static codecvt_type const & codecvt();

  // public data members
  static value_type separator;
  static value_type preferred_separator;
  static value_type dot;
};

Description

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.

`path` constructors

```
path() noexcept;
```
Default constructor.

Effects: Constructs an empty path.

Postconditions:

this->empty() == true.

Throws:
Will not throw.
```
path(path const & p);
```
Copy constructor.
Effects: Constructs a copy of p.

Parameters:

p

Path object to copy.

Postconditions:

*this == p.

Throws:
std::bad_alloc on memory allocation failure.
```
path(path const & p, codecvt_type const & cvt);
```
Copy constructor.
Effects: As if path(p).

Note

The cvt character code conversion facet is unused and provided for historical reasons, for signature compatibility with constructors performing character code conversion.
```
path(path && p) noexcept;
```
Move constructor.
Effects: Move-constructs from p.

Parameters:

p

Path object to move from.

Postconditions:

*this is equal to p before the operation.

Throws:
Will not throw.
```
path(path && p, codecvt_type const & cvt) noexcept;
```
Move constructor.
Effects: As if path(std::move(p)).

Note

The cvt character code conversion facet is unused and provided for historical reasons, for signature compatibility with constructors performing character code conversion.
```
template<typename Source> path(Source const & source);
```
Initializing constructor.
Effects: As if path(source, path::codecvt()).

template<typename Source> 
  explicit path(Source const & source, codecvt_type const & cvt);

Initializing constructor.

Effects: Constructs a path from source. Uses cvt facet to perform character code conversion, if needed.

Parameters:

`source`	Path source to construct the path from.
`cvt`	Character code conversion facet.

Requires:

source is a valid path source.

Throws:

std::bad_alloc on memory allocation failure.

boost::system::system_error in case of character code conversion errors.

```
path(string_type && s) noexcept;
```
Initializing constructor.
Effects: Constructs a path by moving from s.

Parameters:

s

Path source to construct the path from.

Postconditions:

*this is equal to s before the operation.

Throws:
Will not throw.
```
path(string_type && s, codecvt_type const & cvt) noexcept;
```
Initializing constructor.
Effects: As if path(std::move(s)).

Note

The cvt character code conversion facet is unused and provided for historical reasons, for signature compatibility with constructors performing character code conversion.

template<typename InputIterator> path(InputIterator begin, InputIterator end);

Initializing constructor.

Effects: As if path(begin, end, path::codecvt()).

template<typename InputIterator> 
  path(InputIterator begin, InputIterator end, codecvt_type const & cvt);

Initializing constructor.

Effects:

Constructs a path from a range of characters denoted by begin and end. Uses cvt facet to perform character code conversion, if needed.

Parameters:

`begin`	Iterator pointing to the beginning of the range of characters to construct the path from.
`end`	Iterator pointing to the end of the range of characters to construct the path from.
`cvt`	Character code conversion facet.

Requires:

[begin, end) is a valid range of path characters.

Throws:

std::bad_alloc on memory allocation failure.

boost::system::system_error in case of character code conversion errors.

```
path(std::nullptr_t) = delete;
```
Constructor from null pointers is disabled.

`path` assignment

```
path & operator=(path const & p);
```
Copy assignment.

Returns:

assign(p).
```
path & assign(path const & p);
```
Copy assignment.
Effects: Copies the path p into *this.

Parameters:

p

Path to assign.

Postconditions:

*this == p.

Returns:

*this.

Throws:
std::bad_alloc on memory allocation failure.
```
path & assign(path const & p, codecvt_type const & cvt);
```
Copy assignment.

Note

The cvt character code conversion facet is unused and provided for historical reasons, for signature compatibility with overloads performing character code conversion.

Returns:

assign(p).
```
path & operator=(path && p) noexcept;
```
Move assignment.

Returns:

assign(std::move(p)).
```
path & assign(path && p) noexcept;
```
Move assignment.
Effects: Move-assigns the path p to *this.

Parameters:

p

Path to assign.

Postconditions:

*this == p.

Returns:

*this.

Throws:
Will not throw.
```
path & assign(path && p, codecvt_type const & cvt) noexcept;
```
Move assignment.

Note

The cvt character code conversion facet is unused and provided for historical reasons, for signature compatibility with overloads performing character code conversion.

Returns:

assign(std::move(p)).
```
path & operator=(string_type && s) noexcept;
```
Move-assigns characters in the string to the path.

Returns:

assign(std::move(s)).
```
path & assign(string_type && s) noexcept;
```
Move-assigns characters in the string to the path.
Effects: Move-assigns the string s to *this.

Parameters:

s

String to assign.

Postconditions:

*this == s.

Returns:

*this.

Throws:
Will not throw.
```
path & assign(string_type && s, codecvt_type const & cvt) noexcept;
```
Move-assigns characters in the string to the path.

Note

The cvt character code conversion facet is unused and provided for historical reasons, for signature compatibility with overloads performing character code conversion.

Returns:

assign(std::move(s)).

template<typename Source> path & operator=(Source const & source);

Assigns characters in source to the path.

Returns:

assign(source).

```
template<typename Source> path & assign(Source const & source);
```
Assigns characters in source to the path.

Returns:

assign(source, path::codecvt()).

template<typename Source> 
  path & assign(Source const & source, codecvt_type const & cvt);

Assigns characters in source to the path.

Effects:

Assigns source to *this. Uses cvt facet to perform character code conversion, if needed.

Parameters:

`source`	Path source to assign to the path object.
`cvt`	Character code conversion facet.

Requires:

source is a valid path source.

Returns:

*this.

Throws:

std::bad_alloc on memory allocation failure.

boost::system::system_error in case of character code conversion errors.

template<typename InputIterator> 
  path & assign(InputIterator begin, InputIterator end);

Assigns characters in the iterator range to the path.

Returns:

assign(begin, end, path::codecvt()).

template<typename InputIterator> 
  path & assign(InputIterator begin, InputIterator end, 
                codecvt_type const & cvt);

Assigns characters in the iterator range to the path.

Effects:

Assigns a range of characters denoted by begin and end to *this. Uses cvt facet to perform character code conversion, if needed.

Parameters:

`begin`	Iterator pointing to the beginning of the range of characters to assign to the path.
`end`	Iterator pointing to the end of the range of characters to assign to the path.
`cvt`	Character code conversion facet.

Requires:

[begin, end) is a valid range of path characters.

Returns:

*this.

Throws:

std::bad_alloc on memory allocation failure.

boost::system::system_error in case of character code conversion errors.

path & operator=(std::nullptr_t) = delete;

Assignment from null pointers is disabled.

`path` concatenation

```
template<typename Char> path & operator+=(Char c);
```
Concatenates character c to the end of the path.

Requires:

Char is a path character type.

Returns:

concat(&c, &c + 1).
```
path & operator+=(path const & p);
```
Concatenates characters from p to the end of the path.

Returns:

concat(p).
```
path & concat(path const & p);
```
Concatenates characters from p to the end of the path.
Effects: Copies the path p to the end of *this.

Parameters:

p

Path to concatenate.

Returns:

*this.

Throws:
std::bad_alloc on memory allocation failure.
```
path & concat(path const & p, codecvt_type const & cvt);
```
Concatenates characters from p to the end of the path.

Note

The cvt character code conversion facet is unused and provided for historical reasons, for signature compatibility with overloads performing character code conversion.

Returns:

concat(p).
```
template<typename Source> path & operator+=(Source const & source);
```
Concatenates characters from source to the end of the path.

Returns:

concat(source).
```
template<typename Source> path & concat(Source const & source);
```
Concatinates characters from source to the end of the path.

Returns:

concat(source, path::codecvt()).

template<typename Source> 
  path & concat(Source const & source, codecvt_type const & cvt);

Concatinates characters from source to the end of the path.

Effects:

Concatenates the characters from source to the end of *this. Uses cvt facet to perform character code conversion, if needed.

Parameters:

`source`	Path source to concatenate to the path object.
`cvt`	Character code conversion facet.

Requires:

source is a valid path source.

Returns:

*this.

Throws:

std::bad_alloc on memory allocation failure.

boost::system::system_error in case of character code conversion errors.

```
template<typename InputIterator> 
  path & concat(InputIterator begin, InputIterator end);
```
Concatinates characters from the iterator range to the end of the path.

Returns:

concat(begin, end, path::codecvt()).

template<typename InputIterator> 
  path & concat(InputIterator begin, InputIterator end, 
                codecvt_type const & cvt);

Concatinates characters from the iterator range to the end of the path.

Effects:

Concatenates a range of characters denoted by begin and end to the end of *this. Uses cvt facet to perform character code conversion, if needed.

Parameters:

`begin`	Iterator pointing to the beginning of the range of characters to concatenate to the path.
`end`	Iterator pointing to the end of the range of characters to concatenate to the path.
`cvt`	Character code conversion facet.

Requires:

[begin, end) is a valid range of path characters.

Returns:

*this.

Throws:

std::bad_alloc on memory allocation failure.

boost::system::system_error in case of character code conversion errors.

`path` appending

```
path & operator/=(path const & p);
```
Appends p to the end of the path.

Returns:

append(p).

path & append(path const & p);

Appends p to the end of the path.

Effects:

v3:

Concatenates path::preferred_separator to *this, converting format and encoding if required, unless:

an added separator would be redundant, or
would change a relative path to an absolute path, or
p.empty(), or
*p.native().cbegin() is a directory separator.

Then concatenates p.native() to *this.

v4:

If p.is_absolute() || (p.has_root_name() && p.root_name() != this->root_name()), assigns p to *this. Otherwise, modifies *this as if by these steps:

If p.has_root_directory(), removes root directory and relative path, if any.
Let x be a path with contents of p without a root name. If this->has_filename() is true and x
does not start with a directory separator, concatenates path::preferred_separator.
Concatenates x.native().

Note

Whether the path is absolute or not depends on the target OS conventions. Because of this, the result of append operation may be different for different operating systems for some paths. For example, path("//net/foo") / "/bar" will result in "/bar" on POSIX systems and "//net/foo/bar" on Windows because "/bar" is an absolute path on POSIX systems but not on Windows. For portable behavior avoid appending paths with non-empty root path.

Parameters:

`p`	Path to append.

Returns:

*this.

Throws:

std::bad_alloc on memory allocation failure.

```
path & append(path const & p, codecvt_type const &);
```
Appends p to the end of the path.

Note

The cvt character code conversion facet is unused and provided for historical reasons, for signature compatibility with overloads performing character code conversion.

Returns:

append(p).

template<typename Source> path & operator/=(Source const & source);

Appends source to the end of the path.

Returns:

append(path(source)).

template<typename Source> path & append(Source const & source);

Appends source to the end of the path.

Returns:

append(path(source)).

template<typename Source> 
  path & append(Source const & source, codecvt_type const & cvt);

Appends source to the end of the path.

Returns:

append(path(source, cvt)).

template<typename InputIterator> 
  path & append(InputIterator begin, InputIterator end);

Appends characters from the iterator range to the end of the path.

Returns:

append(path(begin, end)).

template<typename InputIterator> 
  path & append(InputIterator begin, InputIterator end, 
                const codecvt_type & cvt);

Appends characters from the iterator range to the end of the path.

Returns:

append(path(begin, end, cvt)).

`path` modifiers

```
void clear() noexcept;
```
Clears the path.

Postconditions:

this->empty() == true.

Throws:
Will not throw.
```
path & make_preferred();
```
Converts directory separators to path::preferred_separator.

Returns:

*this.
```
path & remove_filename();
```
Removes the trailing filename.
Effects:

v3:

As if *this = parent_path().

Note

This function is needed to efficiently implement directory_iterator. It is exposed to allow additional uses. The actual implementation may be much more efficient than *this = parent_path().

v4:

Removes the filename() path element.

Note

Unlike v3, the trailing directory separator(s) are not removed.

Returns:

*this.
```
path & remove_filename_and_trailing_separators();
```
Removes the trailing filename and directory separator.
Effects: As if *this = parent_path().

Note

This function is similar to path::remove_filename from v3, but is also usable in v4.

Returns:

*this.
```
path & remove_trailing_separator();
```
Removes the trailing directory separator.
Effects:

If *this ends with a directory separator, removes that separator. Otherwise, keeps *this unmodified.

Returns:

*this.
```
path & replace_filename(path const & replacement);
```
Replaces the trailing filename.
Effects: As if remove_filename().append(replacement).

See Also: remove_filename, append.

Parameters:

replacement

The replacement filename.

Returns:

*this.
```
path & replace_extension(path const & new_extension = path());
```
Replaces extension in the trailing filename.
Effects:
- Any existing extension() is removed from the stored path, then
- iff new_extension is not empty and does not begin with a dot character, a dot character is concatenated to the stored path, then
- new_extension is concatenated to the stored path.
Parameters:

new_extension

The replacement extension.

Returns:

*this.
```
void swap(path & rhs) noexcept;
```
Swaps *this and rhs path objects.

Parameters:

rhs

Path object to swap with.

Throws:
Will not throw.

`path` observers

```
bool empty() const noexcept;
```
Returns:

true if the path is empty and false otherwise.

Throws:
Will not throw.

bool filename_is_dot() const;

Example:

std::cout << path(".").filename_is_dot();     // outputs 1
std::cout << path("/.").filename_is_dot();    // outputs 1
std::cout << path("foo/.").filename_is_dot(); // outputs 1
std::cout << path("foo/").filename_is_dot();  // v3 outputs 1, v4 outputs 0
std::cout << path("/").filename_is_dot();     // outputs 0
std::cout << path("/foo").filename_is_dot();  // outputs 0
std::cout << path("/foo.").filename_is_dot(); // outputs 0
std::cout << path("..").filename_is_dot();    // outputs 0

See the last bullet item in the path iterators forward traversal order list for why path("foo/").filename() is a dot filename in v3.

Returns:

filename() == path(".").

```
bool filename_is_dot_dot() const;
```
Returns:

filename() == path("..").
```
bool has_root_path() const;
```
Returns:

!root_path().empty().
```
bool has_root_name() const;
```
Returns:

!root_name().empty().
```
bool has_root_directory() const;
```
Returns:

!root_directory().empty().
```
bool has_relative_path() const;
```
Returns:

!relative_path().empty().
```
bool has_parent_path() const;
```
Returns:

!parent_path().empty().
```
bool has_filename() const;
```
Returns:

!filename().empty().
```
bool has_stem() const;
```
Returns:

!stem().empty().
```
bool has_extension() const;
```
Returns:

!extension().empty().
```
bool is_relative() const;
```
Returns:

!is_absolute().
```
bool is_absolute() const;
```
Note

On POSIX systems, a path is considered absolute if it has a [root-directory], and on Windows - if it has both [root-name] and [root-directory].

See Also: root_path, root_name, root_directory.

Returns:

true if the elements of root_path() uniquely identify a directory, else false.

string_type const & native() const noexcept;

Returns:

The pathname in the native format.

const value_type * c_str() const noexcept;

Returns:

native().c_str().

string_type::size_type size() const noexcept;

Returns:

native().size().

template<typename String> String string() const;

Returns:

string< String >(codecvt()).

template<typename String> String string(codecvt_type const & cvt) const;

Parameters:

cvt

Character code conversion facet.

Requires:

String is a specialization of std::basic_string for one of the path character types.

Returns:

Pathname returned by native(). If string_type is different from String, performs character encoding conversion using cvt.

Throws:

std::bad_alloc on memory allocation failure.

boost::system::system_error in case of character code conversion errors.

```
std::string string() const;
```
Returns:

string< std::string >().

std::string string(codecvt_type const & cvt) const;

Returns:

string< std::string >(cvt)

```
std::wstring wstring() const;
```
Returns:

string< std::wstring >().

std::wstring wstring(codecvt_type const & cvt) const;

Returns:

string< std::wstring >(cvt).

```
path generic_path() const;
```
Returns:

The pathname in the generic format.

template<typename String> String generic_string() const;

Returns:

generic_string< String >(codecvt()).

template<typename String> 
  String generic_string(codecvt_type const & cvt) const;

Parameters:

cvt

Character code conversion facet.

Requires:

String is a specialization of std::basic_string for one of the path character types.

Returns:

Pathname returned by generic_path(). If string_type is different from String, performs character encoding conversion using cvt.

Throws:

std::bad_alloc on memory allocation failure.

boost::system::system_error in case of character code conversion errors.

```
std::string generic_string() const;
```
Returns:

generic_string< std::string >().

std::string generic_string(codecvt_type const & cvt) const;

Returns:

generic_string< std::string >(cvt).

```
std::wstring generic_wstring() const;
```
Returns:

generic_string< std::wstring >().

std::wstring generic_wstring(codecvt_type const & cvt) const;

Returns:

generic_string< std::wstring >(cvt).

`path` comparison

int compare(path const & p) const;

	Note
	The elements are determined as if by iteration over the half-open range [`begin()`, `end()`) for `*this` and `p`.

Returns:

A value less than 0 if the elements of *this are lexicographically less than the elements of p, otherwise a value greater than 0 if the elements of *this are lexicographically greater than the elements of p, otherwise 0.

template<typename Source> int compare(Source const & source) const;

Returns:

compare(path(source)).

template<typename Source> 
  int compare(Source const & source, codecvt_type const & cvt) const;

Returns:

compare(path(source, cvt)).

`path` decomposition

```
path root_path() const;
```
Returns:

root_name() / root_path().
```
path root_name() const;
```
Returns:

[root-name], if the path in the generic format includes a [root-name], otherwise path().
```
path root_directory() const;
```
Returns:

[root-directory], if the path in the generic format includes a [root-directory], otherwise path().
```
path relative_path() const;
```
Returns:

A path composed of the path elements starting with the first [filename] after root_path(). Returns path() if there are no such path elements.

path parent_path() const;

Returns the path without the last component.

Example:

std::cout << path("/foo/bar.txt").parent_path(); // outputs "/foo"
std::cout << path("/foo/bar").parent_path();     // outputs "/foo"
std::cout << path("/foo/bar/").parent_path();    // outputs "/foo/bar"
std::cout << path("/").parent_path();            // outputs ""
std::cout << path(".").parent_path();            // outputs ""
std::cout << path("..").parent_path();           // outputs ""

See the last bullet item in the path iterators forward traversal order list for why the "/foo/bar/" example doesn't output "/foo".

Returns:

(empty() || begin() == --end()) ? path() : pp, where pp is constructed as if by starting with an empty path and successively applying operator/= for each element in the range [begin(), --end()).

path filename() const;

Returns the last filename component of the path.

Example:

std::cout << path("/foo/bar.txt").filename(); // outputs "bar.txt"
std::cout << path("/foo/bar").filename();     // outputs "bar"
std::cout << path("/foo/bar/").filename();    // v3 outputs "."
                                              // v4 outputs ""
std::cout << path("/").filename();            // v3 outputs "/"
                                              // v4 outputs ""
std::cout << path(".").filename();            // outputs "."
std::cout << path("..").filename();           // outputs ".."

See the last bullet item in the path iterators forward traversal order list for why the "/foo/bar/" example doesn't output "bar".

Returns:

v3: empty() ? path() : *--end().
v4: *this == root_path() ? path() : *--end().

path stem() const;

Returns the last filename component of the path without extension.

Example:

std::cout << path("/foo/bar.txt").stem() << '\\n'; // outputs "bar"
std::cout << path(".hidden").stem() << '\\n';      // v3 outputs ""
                                                   // v4 outputs ".hidden"
path p = "foo.bar.baz.tar";
for (; !p.extension().empty(); p = p.stem())       // outputs: .tar
  std::cout << p.extension() << '\\n';             //          .baz
                                                   //          .bar

Returns:

If p.filename() does not contain dots, consist solely of one or to two dots, [Since v4: or contains exactly one dot as the initial character,] returns p.filename(). Otherwise returns the substring of p.filename() starting at its beginning and ending at the last dot (the dot is not included).

path extension() const;

Returns extension of the last filename component of the path.

	Note
	Implementations are permitted but not required to define additional behavior for file systems which append additional elements to extensions, such as alternate data streams or partitioned dataset names.

Example:

std::cout << path("/foo/bar.txt").extension(); // outputs ".txt"

	Note
	The dot is included in the return value so that it is possible to distinguish between no extension and an empty extension. See https://lists.boost.org/Archives/boost/2010/02/162028.php for more extensive rationale.

Returns:

The substring of p.filename() that is not included in p.stem().

`path` lexical operations

path lexically_normal() const;

Overview:

Returns *this with redundant current directory ("."), parent directory (".."), and directory separator elements removed.

	Note
	Uses `path::operator/=` to compose the returned path.

Example:

std::cout << path("foo/./bar/..").lexically_normal() << std::endl;    // outputs "foo"
std::cout << path("foo/.///bar/../").lexically_normal() << std::endl; // v3: outputs "foo/."
                                                                      // v4: outputs "foo/"

On Windows, the returned path's directory-separator characters will be backslashes rather than slashes, but that does not affect path equality.

Returns:

*this in normal form.

path lexically_relative(path const & base) const;

Overview:

Returns *this made relative to base. Treats empty or identical paths as corner cases, not errors. Does not resolve symlinks. Does not first normalize *this or base.

	Note
	Uses `std::mismatch(begin(), end(), base.begin(), base.end())` to determine the first mismatched element of `*this` and `base`. Uses `operator==()` to determine if elements match.

Example:

assert(path("/a/d").lexically_relative("/a/b/c") == "../../d");
assert(path("/a/b/c").lexically_relative("/a/d") ==  "../b/c");
assert(path("a/b/c").lexically_relative("a") == "b/c");
assert(path("a/b/c").lexically_relative("a/b/c/x/y") ==  "../..");
assert(path("a/b/c").lexically_relative("a/b/c") ==  ".");
assert(path("a/b").lexically_relative("c/d") ==  "");

The above assertions will succeed. On Windows, the returned path's directory-separator characters will be backslashes rather than forward slashes, but that does not affect path equality.

	Note
	If symlink following semantics are desired, use the operational function `relative()`.

	Note
	If normalization is needed to ensure consistent matching of elements, apply `lexically_normal()` to `*this`, `base`, or both.

Parameters:

base

Base path, relative to which to produce the path.

Returns:

path() if the first mismatched element of *this is equal to begin() or the first mismatched element of base is equal to base.begin(), or
path(".") if the first mismatched element of *this is equal to end() and the first mismatched element of base is equal to base.end(), or
An object of class path composed via application of operator/=(path("..")) for each element in the half-open range [first mismatched element of base, base.end()), and then application of operator/= for each element in the half-open range [first mismatched element of *this, end()).

```
path lexically_proximate(path const & base) const;
```
Note

If symlink following semantics are desired, use the operational function relative().

Note

If normalization is needed to ensure consistent matching of elements, apply lexically_normal() to *this, base, or both.

See Also: lexically_relative.

Returns:

If lexically_relative(base) returns a non-empty path, returns that path. Otherwise returns *this.

`path` iterators

```
iterator begin() const;
```
Returns:

An iterator for the first element in forward traversal order. If no elements are present, the end iterator.
```
iterator end() const;
```
Returns:

The end iterator in the forward traversal order.
```
reverse_iterator rbegin() const;
```
Returns:

An iterator for the first element in backward traversal order. If no elements are present, the end iterator.
```
reverse_iterator rend() const;
```
Returns:

The end iterator in the backward traversal order.

`path` locale operations

```
static std::locale imbue(std::locale const & loc);
```
Effects:

Stores a copy of loc as the imbued path locale.

Note

The initial value of the imbued path locale is operating system dependent. It shall be a locale with a codecvt facet for a char string encoding appropriate for the operating system.

Returns:

The previous imbued path locale.
```
static codecvt_type const & codecvt();
```
Returns:

The codecvt facet for the imbued path locale.

`path` public public data members

```
static value_type separator;
```
Character used to separate path elements in generic paths.
```
static value_type preferred_separator;
```
Character used to separate path elements in native paths.

This character may be the same as separator or different and depends on the target platform conventions. It is "/" on POSIX systems and "\" on Windows.
```
static value_type dot;
```
Character used to separate file name and extension.

It is "." on POSIX systems and Windows.

Postconditions:	`this->empty() == true`.
Throws:	Will not throw.

	Note
	The `cvt` character code conversion facet is unused and provided for historical reasons, for signature compatibility with constructors performing character code conversion.

Requires:	`Char` is a path character type.
Returns:	`concat(&c, &c + 1)`.

	Note
	This function is needed to efficiently implement `directory_iterator`. It is exposed to allow additional uses. The actual implementation may be much more efficient than `*this = parent_path()`.

	Note
	Unlike v3, the trailing directory separator(s) are not removed.

	Note
	This function is similar to `path::remove_filename` from v3, but is also usable in v4.

Returns:	`true` if the path is empty and `false` otherwise.
Throws:	Will not throw.

	Note
	On POSIX systems, a path is considered absolute if it has a `[root-directory]`, and on Windows - if it has both `[root-name]` and `[root-directory]`.

	Note
	The initial value of the imbued `path` locale is operating system dependent. It shall be a locale with a `codecvt` facet for a `char` string encoding appropriate for the operating system.

Class path

Synopsis

Description

path constructors

path assignment

path concatenation

path appending

path modifiers

path observers

path comparison

path decomposition

path lexical operations

path iterators

path locale operations

path public public data members

`path` constructors

`path` assignment

`path` concatenation

`path` appending

`path` modifiers

`path` observers

`path` comparison

`path` decomposition

`path` lexical operations

`path` iterators

`path` locale operations

`path` public public data members