30 Input/output library [input.output]

30.10 File systems [filesystems]

30.10.27 Class path [fs.class.path]

30.10.27.4 path members [fs.path.member]

30.10.27.4.1 path constructors [fs.path.construct]

path() noexcept;

Effects: Создает объект класса path.

Postconditions: empty() == true.

path(const path& p); path(path&& p) noexcept;

Effects: Создает объект класса, path имеющий тот же путь в собственном и универсальном форматах, соответственно, что и исходное значение p. Во второй форме p остается в допустимом, но неуказанном состоянии.

path(string_type&& source, format fmt = auto_format);

Effects: Создает объект класса, path для которого имя пути в обнаруженном формате source имеет исходное значение source ([fs.path.fmt.cvt]), преобразовывая формат, если требуется ([fs.path.fmt.cvt]). source остается в допустимом, но неуказанном состоянии.

template <class Source> path(const Source& source, format fmt = auto_format); template <class InputIterator> path(InputIterator first, InputIterator last, format fmt = auto_format);

Effects: Позвольте s быть эффективным диапазоном source ([fs.path.req]) или диапазоном [first, last)с преобразованной кодировкой, если требуется ([fs.path.cvt]). Находит обнаруженный формат s ([fs.path.fmt.cvt]) и создает объект класса, path для которого задан путь в этом формате s.

template <class Source> path(const Source& source, const locale& loc, format fmt = auto_format); template <class InputIterator> path(InputIterator first, InputIterator last, const locale& loc, format fmt = auto_format);

Requires: Тип значения Source и InputIterator есть char.

Effects: Позвольте s быть эффективным диапазоном source или диапазоном [first, last)после преобразования кодировки следующим образом:

  • Если value_­type есть wchar_­t, преобразуется в стандартную широкую кодировку ([fs.def.native.encode]) с использованием codecvt<​wchar_­t, char, mbstate_­t> аспекта loc.

  • В противном случае выполняется преобразование с использованием codecvt<wchar_­t, char, mbstate_­t> фасета loc, а затем выполняется второе преобразование в текущую узкую кодировку.

Находит обнаруженный формат s ([fs.path.fmt.cvt]) и создает объект класса, path для которого задан путь в этом формате s.

[ Example: Строка должна быть прочитана из базы данных, которая закодирована в ISO / IEC 8859-1, и использована для создания каталога:

namespace fs = std::filesystem;
std::string latin1_string = read_latin1_data();
codecvt_8859_1<wchar_t> latin1_facet;
std::locale latin1_locale(std::locale(), latin1_facet);
fs::create_directory(fs::path(latin1_string, latin1_locale));

Для операционных систем на основе POSIX путь создается путем использования сначала latin1_­facet для преобразования кодировки ISO / IEC 8859-1 latin1_­string в широкую символьную строку в собственной широкой кодировке ([fs.def.native.encode]). Полученная в результате широкая строка затем преобразуется в строку узкого символьного имени пути в текущей собственной узкой кодировке. Если собственная широкая кодировка - UTF-16 или UTF-32, а текущая собственная узкая кодировка - UTF-8, все символы в наборе символов ISO / IEC 8859-1 будут преобразованы в их представление Unicode, но для других в родных узких кодировках некоторые символы могут не иметь представления.

Для операционных систем на базе Windows путь создается с использованием latin1_­facet преобразования ISO / IEC 8859-1 latin1_­string в строку имени пути с расширенными символами в кодировке UTF-16. Все символы в наборе символов ISO / IEC 8859-1 будут преобразованы в их представление Unicode. ] end example

30.10.27.4.2 path assignments [fs.path.assign]

path& operator=(const path& p);

Effects: Если *this и p являются одним и тем же объектом, не действует. В противном случае устанавливает оба соответствующих пути *this в соответствующие пути к p.

Returns: *this.

path& operator=(path&& p) noexcept;

Effects: Если *this и p являются одним и тем же объектом, не действует. В противном случае устанавливает оба соответствующих пути *this в соответствующие пути к p. p остается в допустимом, но неуказанном состоянии. [ Note: Допустимая реализация swap(p). ] end note

Returns: *this.

path& operator=(string_type&& source); path& assign(string_type&& source);

Effects: Устанавливает имя пути в обнаруженном формате source в исходное значение source. source остается в допустимом, но неуказанном состоянии.

Returns: *this.

template <class Source> path& operator=(const Source& source); template <class Source> path& assign(const Source& source); template <class InputIterator> path& assign(InputIterator first, InputIterator last);

Effects: Позвольте s быть эффективным диапазоном source ([fs.path.req]) или диапазоном [first, last)с преобразованной кодировкой, если требуется ([fs.path.cvt]). Находит обнаруженный формат s ([fs.path.fmt.cvt]) и устанавливает путь в этом формате равным s.

Returns: *this.

30.10.27.4.3 path appends [fs.path.append]

Операции добавления используются operator/= для обозначения их семантического эффекта добавления preferred-separatorпри необходимости.

path& operator/=(const path& p);

Effects: Если p.is_­absolute() || (p.has_­root_­name() && p.root_­name() != root_­name()), то operator=(p).

В противном случае изменяется, *this как если бы эти шаги:

  • Если p.has_­root_­directory(), то удаляет любой корневой каталог и относительный путь из имени пути общего формата. В противном случае, если !has_­root_­directory() && is_­absolute() есть true или если has_­filename() есть true, то добавляется path​::​preferred_­separator к имени пути общего формата.

  • Затем добавляет путь в собственном формате p, исключая любые root-nameиз его имени пути общего формата, к имени пути в собственном формате.

[ Example: Даже если //host интерпретируются как root-name, оба пути path("//host")/"foo" и path("//host/")/"foo" равны "//host/foo".

Примеры выражений:

// On POSIX,
path("foo") / "";     // yields "foo/"
path("foo") / "/bar"; // yields "/bar"
// On Windows, backslashes replace slashes in the above yields

// On Windows,
path("foo") / "c:/bar";  // yields "c:/bar"
path("foo") / "c:";      // yields "c:"
path("c:") / "";         // yields "c:"
path("c:foo") / "/bar";  // yields "c:/bar"
path("c:foo") / "c:bar"; // yields "c:foo/bar"

end example]

Returns: *this.

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

Effects: Эквивалентен: return operator/=(path(source));

template <class InputIterator> path& append(InputIterator first, InputIterator last);

Effects: Эквивалентен: return operator/=(path(first, last));

30.10.27.4.4 path concatenation [fs.path.concat]

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 <class Source> path& operator+=(const Source& x); template <class EcharT> path& operator+=(EcharT x); template <class Source> path& concat(const Source& x);

Effects: Добавляется path(x).native() к имени пути в собственном формате. [ Note: Это напрямую влияет на значение native() и может не переноситься между операционными системами. ]end note

Returns: *this.

template <class InputIterator> path& concat(InputIterator first, InputIterator last);

Effects: Эквивалентно return *this += path(first, last).

30.10.27.4.5 path modifiers [fs.path.modifiers]

void clear() noexcept;

Postconditions: empty() == true.

path& make_preferred();

Effects: Каждый directory-separator путь в общем формате преобразуется в preferred-separator.

Returns: *this.

[Example:

path p("foo/bar");
std::cout << p << '\n';
p.make_preferred();
std::cout << p << '\n';

В операционной системе, где preferred-separatorстоит косая черта, вывод будет следующим:

"foo/bar"
"foo/bar"

В операционной системе, где preferred-separatorиспользуется обратная косая черта, вывод будет следующим:

"foo/bar"
"foo\bar"

end example]

path& remove_filename();

Postconditions: !has_­filename().

Effects: Удалите путь filename() к общему формату из пути к общему формату.

Returns: *this.

[Example:

path("foo/bar").remove_filename(); // yields "foo/"
path("foo/").remove_filename();    // yields "foo/"
path("/foo").remove_filename();    // yields "/"
path("/").remove_filename();       // yields "/"

end example]

path& replace_filename(const path& replacement);

Effects: Эквивалентен:

remove_filename();
operator/=(replacement);

Returns: *this.

[Example:

path("/foo").replace_filename("bar");  // yields "/bar" on POSIX
path("/").replace_filename("bar");     // yields "/bar" on POSIX

end example]

path& replace_extension(const path& replacement = path());

Effects:

  • Все существующие extension()([fs.path.decompose]) удаляются из пути в общем формате, затем

  • Если replacement не пусто и не начинается с точки, точка добавляется к имени пути в общем формате, затем

  • operator+=(replacement);.

Returns: *this.

void swap(path& rhs) noexcept;

Effects: Меняет местами содержимое (во всех форматах) двух путей.

Complexity: Постоянное время.

30.10.27.4.6 path native format observers [fs.path.native.obs]

Строка, возвращаемая всеми наблюдателями в собственном формате, находится в формате native pathname format.

const string_type& native() const noexcept;

Returns: Путь в собственном формате.

const value_type* c_str() const noexcept;

Returns: Эквивалентно native().c_­str().

operator string_type() const;

Returns: native().

[ Note: Преобразование в string_­type предусмотрено для того, чтобы объект класса path можно было передать в качестве аргумента существующим конструкторам файловых потоков стандартной библиотеки и открытым функциям. ] end note

template <class EcharT, class traits = char_traits<EcharT>, class Allocator = allocator<EcharT>> basic_string<EcharT, traits, Allocator> string(const Allocator& a = Allocator()) const;

Returns: native().

Remarks: Все выделение памяти, в том числе для возвращаемого значения, должно выполняться a. Преобразование, если оно есть, определяется [fs.path.cvt].

std::string string() const; std::wstring wstring() const; std::string u8string() const; std::u16string u16string() const; std::u32string u32string() const;

Returns: pathstring.

Remarks: Преобразование, если оно есть, выполняется в соответствии с указаниями [fs.path.cvt]. Кодировка строки, возвращаемой u8string() функцией, всегда UTF-8.

30.10.27.4.7 path generic format observers [fs.path.generic.obs]

Функции наблюдателя общего формата возвращают строки, отформатированные в соответствии с форматом generic pathname format. Одиночный'/'символ косой черты ( ) используется как directory-separator.

[ Example: В операционной системе, в которой используется обратная косая черта preferred-separator,

path("foo\\bar").generic_string()

возвращается "foo/bar". ] end example

template <class EcharT, class traits = char_traits<EcharT>, class Allocator = allocator<EcharT>> basic_string<EcharT, traits, Allocator> generic_string(const Allocator& a = Allocator()) const;

Returns: Путь в общем формате.

Remarks: Все выделение памяти, в том числе для возвращаемого значения, должно выполняться a. Преобразование, если оно есть, определяется [fs.path.cvt].

std::string generic_string() const; std::wstring generic_wstring() const; std::string generic_u8string() const; std::u16string generic_u16string() const; std::u32string generic_u32string() const;

Returns: Путь в общем формате.

Remarks: Преобразование, если оно есть, определяется [fs.path.cvt]. Кодировка строки, возвращаемой generic_­u8string() функцией, всегда UTF-8.

30.10.27.4.8 path compare [fs.path.compare]

int compare(const path& p) const noexcept;

Returns:

  • Значение меньше 0, если native() для элементов *this лексикографически меньше, чем native() для элементов p; иначе,

  • значение больше 0, если native() для элементов *this лексикографически больше, чем native() для элементов p; иначе,

  • 0.

Remarks: Элементы определяются как бы итерацией в полуоткрытом диапазоне [begin(), end()) для *this и p.

int compare(const string_type& s) const int compare(basic_string_view<value_type> s) const;

Returns: compare(path(s)).

int compare(const value_type* s) const

Returns: compare(path(s)).

30.10.27.4.9 path decomposition [fs.path.decompose]

path root_name() const;

Returns: root-name, если путь в универсальном формате включает root-name, в противном случае path().

path root_directory() const;

Returns: root-directory, если путь в универсальном формате включает root-directory, в противном случае path().

path root_path() const;

Returns: root_­name() / root_­directory().

path relative_path() const;

Returns: path Состоят из имени пути в общем формате, если !empty(), начиная с первым filenameAFTER root-path. В противном случае path().

path parent_path() const;

Returns: *this если !has_­relative_­path(), в противном случае путь, имя пути общего формата которого является самым длинным префиксом имени пути общего формата, *this который производит на один элемент меньше в своей итерации.

path filename() const;

Returns: relative_­path().empty() ? path() : *--end().

[Example:

path("/foo/bar.txt").filename();   // yields "bar.txt"
path("/foo/bar").filename();       // yields "bar"
path("/foo/bar/").filename();      // yields ""
path("/").filename();              // yields ""
path("//host").filename();         // yields ""
path(".").filename();              // yields "."
path("..").filename();             // yields ".."

end example]

path stem() const;

Returns: Позвольте f быть общим путем в формате filename(). Возвращает путь, имя которого в общем формате:

  • f, если он не содержит периодов, кроме начального периода, или состоит только из одного или двух периодов;

  • в противном случае - префикс f окончания перед последним периодом.

[Example:

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

end example]

path extension() const;

Returns: путь, имя пути которого в общем формате является суффиксом, filename() не включенным в stem().

[Example:

path("/foo/bar.txt").extension();  // yields ".txt" and stem() is "bar"
path("/foo/bar").extension();      // yields "" and stem() is "bar"
path("/foo/.profile").extension(); // yields "" and stem() is ".profile"
path(".bar").extension();          // yields "" and stem() is ".bar"
path("..bar").extension();         // yields ".bar" and stem() is "."

end example]

[ Note: Точка включена в возвращаемое значение, чтобы можно было отличить отсутствие расширения от пустого расширения. ]end note

[ Note: В операционных системах, отличных от POSIX, для пути pэто может быть не так p.stem() + p.extension() == p.filename(), даже если имена путей общего формата совпадают. ] end note

30.10.27.4.10 path query [fs.path.query]

bool empty() const noexcept;

Returns: true если путь в общем формате пуст, иначе false.

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_absolute() const;

Returns: true если путь в собственном формате содержит absolute path, иначе false.

[ Example: path("/").is_­absolute() предназначен true для операционных систем false на базе POSIX и для операционных систем на базе Windows. ] end example

bool is_relative() const;

Returns: !is_­absolute().

30.10.27.4.11 path generation [fs.path.gen]

path lexically_normal() const;

Returns: Путь, имя которого в универсальном формате normal form совпадает с именем пути в универсальном формате *this.

[Example:

assert(path("foo/./bar/..").lexically_normal() == "foo/");
assert(path("foo/.///bar/../").lexically_normal() == "foo/");

Вышеупомянутые утверждения будут успешными. В Windows directory-separatorсимволы возвращаемого пути будут обратной косой чертой, а не косой чертой, но это не влияет на path равенство. ] end example

path lexically_relative(const path& base) const;

Returns: *this сделано относительно base. Нет resolve символических ссылок. Не первое normalize *this или base.

Effects: Если root_­name() != base.root_­name() есть true или is_­absolute() != base.is_­absolute() есть true или !has_­root_­directory() && base.has_­root_­directory() есть true, возвращается path(). Определяет первый несовпадающий элемент *this и base как будто по:

auto [a, b] = mismatch(begin(), end(), base.begin(), base.end());

Потом,

  • если a == end() и b == base.end(), возвращается path("."); иначе

  • пусть n будет количество filenameэлементов [b, base.end()) , которых нет, dot или dot-dot минус количество, которые есть dot-dot. Если n<0, возвращается path(); иначе

  • возвращает объект класса path , созданный по умолчанию, за которым следует

    • приложение operator/=(path("..")) n времен, а затем

    • применение operator/= для каждого элемента в [a, end()).

[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") == "../../a/b");

Вышеупомянутые утверждения будут успешными. В Windows directory-separatorсимволы возвращаемого пути будут обратной косой чертой, а не косой чертой, но это не влияет на path равенство. ]end example

[ Note: Если требуется символическая ссылка, следующая за семантикой, используйте операционную функцию relative(). ] end note

[ Note: Если normalization необходимо , чтобы обеспечить последовательное согласование элементов, применяются lexically_­normal() к *this, baseили обоих. ] end note

path lexically_proximate(const path& base) const;

Returns: Если значение lexically_­relative(base) не является пустым путем, верните его. В противном случае вернитесь *this.

[ Note: Если требуется символическая ссылка, следующая за семантикой, используйте операционную функцию proximate(). ] end note

[ Note: Если normalization необходимо , чтобы обеспечить последовательное согласование элементов, применяются lexically_­normal() к *this, baseили обоих. ] end note