30 Input/output library [input.output]

30.10 File systems [filesystems]

30.10.27 Class path [fs.class.path]

Объект класса path представляет собой path и содержит pathname. Такой объект касается только лексических и синтаксических аспектов пути. Путь не обязательно существует во внешнем хранилище, и путь не обязательно действителен для текущей операционной системы или для конкретной файловой системы.

[ Note: Класс path используется для поддержки различий между типами строк, используемых разными операционными системами для представления имен путей, и для выполнения преобразований между кодировками, когда это необходимо. ]end note

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 format
    enum 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 <class Source>
      path(const Source& source, format fmt = auto_format);
    template <class InputIterator>
      path(InputIterator first, InputIterator last, format fmt = auto_format);
    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);
    ~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 <class Source>
      path& operator=(const Source& source);
    template <class Source>
      path& assign(const Source& source)
    template <class InputIterator>
      path& assign(InputIterator first, InputIterator last);

    // [fs.path.append], appends
    path& operator/=(const path& p);
    template <class Source>
      path& operator/=(const Source& source);
    template <class Source>
      path& append(const Source& source);
    template <class InputIterator>
      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 <class Source>
      path& operator+=(const Source& x);
    template <class EcharT>
      path& operator+=(EcharT x);
    template <class Source>
      path& concat(const Source& x);
    template <class InputIterator>
      path& concat(InputIterator first, InputIterator last);

    // [fs.path.modifiers], modifiers
    void  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.native.obs], native format observers
    const string_type& native() const noexcept;
    const value_type*  c_str() const noexcept;
    operator string_type() const;

    template <class EcharT, class traits = char_traits<EcharT>,
              class Allocator = allocator<EcharT>>
      basic_string<EcharT, traits, Allocator>
        string(const Allocator& a = Allocator()) const;
    std::string    string() const;
    std::wstring   wstring() const;
    std::string    u8string() const;
    std::u16string u16string() const;
    std::u32string u32string() const;

    // [fs.path.generic.obs], generic format observers
    template <class EcharT, class traits = char_traits<EcharT>,
              class Allocator = allocator<EcharT>>
      basic_string<EcharT, traits, Allocator>
        generic_string(const Allocator& a = Allocator()) const;
    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;

    // [fs.path.compare], compare
    int  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], query
    bool 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], iterators
    class iterator;
    using const_iterator = iterator;

    iterator begin() const;
    iterator end() const;
  };
}

value_­type - это typedef тип кодированных символов, зависящий от операционной системы, используемый для представления имен путей.

Значение preferred_­separator члена - это зависимый от операционной системы preferred-separatorсимвол ([fs.path.generic]).

[ Example: Для операционных систем на базе POSIX value_­type есть char и preferred_­separator остается косая черта ('/'). В операционных системах Windows value_­type есть wchar_­t и preferred_­separator остается символ обратной косой черты (L'\\'). ]end example

30.10.27.1 Generic pathname format [fs.path.generic]

pathname:
	root-nameopt root-directoryopt relative-path
root-name:
	operating system dependent sequences of characters
	implementation-defined sequences of characters
root-directory:
	directory-separator
relative-path:
	filename
	filename directory-separator relative-path
	an empty path
filename:
	non-empty sequence of characters other than directory-separator characters
directory-separator:
	preferred-separator directory-separatoropt
	fallback-separator directory-separatoropt
preferred-separator:
	operating system dependent directory separator character
fallback-separator:
	/, if preferred-separator is not /

[ Note: Операционные системы часто накладывают ограничения на символы, которые могут использоваться в файле filename. Для широкой переносимости пользователи могут захотеть ограничить количество filename символов набором символов переносимого имени файла POSIX: ]
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
a b c d e f g h i j k l m n o p q r s t u v w x y z
0 1 2 3 4 5 6 7 8 9 . _­ - end note

За исключением a root-name, несколько следующих друг за другом directory-separatorсимволов считаются одним directory-separatorсимволом.

Имя файла dot ([fs.def.filename]) рассматривается как ссылка на текущий каталог. Имя файла dot-dot ([fs.def.filename]) рассматривается как ссылка на родительский каталог. То , что имя файл dot-dot относится к относительно root-directoryявляется реализацией. Определенные имена файлов могут иметь особое значение для конкретной операционной системы.

A root-nameопределяет начальное местоположение для разрешения имени пути ([fs.def.pathres]). Если нет зависимостей от операционной системы root-names, требуется по крайней мере одна реализация, определяемая root-name. [ Note: Многие операционные системы определяют имя, начинающееся с двух directory-separatorсимволов, как, root-nameкоторое идентифицирует расположение сети или других ресурсов. Некоторые операционные системы определяют одну букву, за которой следует двоеточие, как спецификатор диска - root-name идентифицирующий конкретное устройство, такое как диск. ]end note

Если a root-nameв остальном неоднозначно, выбирается вариант с самой длинной последовательностью символов. [ Note: В операционной системе, подобной POSIX, невозможно иметь root-nameи relative-path без промежуточных root-directoryэлементов. ]end note

30.10.27.2 path conversions [fs.path.cvt]

30.10.27.2.1 path argument format conversions [fs.path.fmt.cvt]

[ Note: Преобразования формата, описанные в этом разделе, не применяются в операционных системах на базе POSIX, потому что в этих системах:

  • Общий формат приемлем как собственный путь.

  • Нет необходимости различать собственный формат и общий формат в аргументах функции.

  • Пути к обычным файлам и пути к каталогам имеют одинаковый синтаксис.

end note]

Некоторые функции определены для приема detected-format аргументов, которые представляют собой последовательности символов. Аргумент обнаруженного формата представляет путь с использованием либо имени пути в, generic format либо имени пути в native format. Такой аргумент считается имеющимся в общем формате тогда и только тогда, когда он соответствует универсальному формату и неприемлем для операционной системы в качестве собственного пути.

[ Note: Некоторые операционные системы могут не иметь однозначного способа различить аргументы собственного формата и универсального формата. Это сделано специально, поскольку упрощает использование операционных систем, не требующих устранения неоднозначности. Реализации для операционной системы, где требуется разрешение неоднозначности, разрешено различать форматы. ]end note

При необходимости имена путей преобразуются между общим и собственным форматами в зависимости от операционной системы. Пусть G(n) и N(g) в математическом смысле будут функциями реализации, которые преобразуют родной формат в общий и общий в собственный формат соответственно. Если g=G(n) для некоторых n, то G(N(g))=g; если n=N(g) для некоторых g, то N(G(n))=n. [ Note: Ни и G не N должны быть обратимыми. ] end note

Если собственный формат требует, чтобы пути к обычным файлам были отформатированы иначе, чем пути к каталогам, путь должен рассматриваться как путь к каталогу, если его последний элемент - a directory-separator, в противном случае он должен рассматриваться как путь к обычному файлу.

[ Note: Путь хранит имя пути в собственном формате ([fs.path.native.obs]) и действует так, как если бы он также хранит имя пути общего формата, как указано ниже. Реализация может сгенерировать имя пути общего формата на основе имени пути в собственном формате (и, возможно, другой информации) по запросу. ]end note

Когда путь строится из или ему назначается одно представление, отдельное от любого пути, другое представление выбирается соответствующей функцией преобразования (G или N).

Когда (новое) значение p одного представления пути получается из представления того или иного пути, значение q выбирается для другого представления. Значение q преобразуется в p (по G или N в зависимости от обстоятельств), если это делает какое-либо такое значение; q иначе не указано. [ Note: Если q это результат преобразования любого пути, то это результат преобразования p. ]end note

30.10.27.2.2 path type and encoding conversions [fs.path.type.cvt]

Для аргументов функций-членов, которые принимают последовательности символов, представляющих пути, и для функций-членов, возвращающих строки, преобразование типа значения и кодировки выполняется, если тип значения аргумента или возвращаемого значения отличается от path​::​value_­type. Для аргумента или возвращаемого значения метод преобразования и кодировка, в которую нужно преобразовать, определяются его типом значения:

  • char: Кодировка является собственной узкой кодировкой ([fs.def.native.encode]). Метод преобразования, если таковой имеется, зависит от операционной системы. [ Note: Для POSIX операционных систем на основе path​::​value_­type является char поэтому не преобразование из char аргументов типа значения или char значений типа возвращаемого значения не выполняется. Для операционных систем на базе Windows собственная узкая кодировка определяется путем вызова функции Windows API. ] [ Это приводит к поведению, аналогичному поведению других стандартных библиотечных функций C и C ++, которые выполняют файловые операции с использованием узких строк символов для определения путей. Изменение такого поведения может вызвать удивление и привести к ошибкам. ] end noteNote: end note

  • wchar_­t: Кодировка native wide encoding. Метод преобразования не указан. [ Note: Для операционных систем на базе Windows не path​::​value_­type выполняется wchar_­t преобразование из wchar_­t аргументов типа значения или в wchar_­t возвращаемые значения типа значения. ] end note

  • char16_­t: Кодировка - UTF-16. Метод преобразования не указан.

  • char32_­t: Кодировка - UTF-32. Метод преобразования не указан.

Если преобразуемая кодировка не имеет представления для исходных символов, результирующие преобразованные символы, если таковые имеются, не определены. Реализации не должны изменять аргументы функций-членов, если они уже имеют тип path​::​value_­type.

30.10.27.3 path requirements [fs.path.req]

В дополнение к требованиям ([fs.req]), указанные параметры шаблона функции Source должны быть одним из следующих:

  • basic_­string<EcharT, traits, Allocator>. Аргумент функции const Source& source должен иметь эффективный диапазон [source.begin(), source.end()).

  • basic_­string_­view<EcharT, traits>. Аргумент функции const Source& source должен иметь эффективный диапазон [source.begin(), source.end()).

  • Тип, отвечающий требованиям итератора ввода, который выполняет итерацию по NTCTS. Тип значения должен быть типом закодированного символа. Аргумент функции const Source& source должен иметь эффективный диапазон, [source, end) где end - первое значение итератора со значением элемента, равным iterator_­traits<Source>​::​value_­type().

  • Символьный массив, который после преобразования массива в указатель приводит к указателю на начало NTCTS. Тип значения должен быть типом закодированного символа. Аргумент функции const Source& source должен иметь эффективный диапазон, [source, end) где end - первое значение итератора со значением элемента, равным iterator_­traits<decay_­t<Source>>​::​value_­type().

Функции, принимающие указанные параметры шаблона Source , не должны участвовать в разрешении перегрузки, если либо

  • Source является специализацией basic_­string или basic_­string_­view, или

  • qualified-id iterator_­traits<decay_­t<Source>>​::​value_­type является действительным , и обозначает , возможно , const закодированный тип символов ([temp.deduct]).

[ Note: Посмотрите, path conversions как указанные выше типы значений и их кодировки преобразуются в path​::​value_­type и его кодировку. ]end note

Аргументы типа Source не должны быть нулевыми указателями.

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

30.10.27.5 path iterators [fs.path.itr]

Итераторы пути перебирают элементы имени пути в generic format.

A path​::​iterator - это постоянный итератор, удовлетворяющий всем требованиям a, bidirectional iterator за исключением того, что для разыменяемых итераторов a и b типа path​::​iterator with a == bнет требований, чтобы *a и *b были привязаны к одному и тому же объекту. Его value_­type это path.

Вызов любой неконстантной функции-члена path объекта делает недействительными все итераторы, ссылающиеся на элементы этого объекта.

Для элементов имени пути в универсальном формате порядок прямого обхода следующий:

  • root-nameЭлемент, если он присутствует.

  • root-directoryЭлемент, если он присутствует. [ Note: Общий формат необходим для правильной работы лексикографического сравнения. ] end note

  • Каждый последующий filenameэлемент, если присутствует.

  • Пустой элемент, если присутствует конечный некорневой элемент directory-separator .

Порядок обратного обхода обратен прямому обходу.

iterator begin() const;

Returns: Итератор для первого присутствующего элемента в списке обхода выше. Если элементы отсутствуют, конечный итератор.

iterator end() const;

Returns: Конечный итератор.

30.10.27.6 path non-member functions [fs.path.nonmember]

void swap(path& lhs, path& rhs) noexcept;

Effects: Эквивалентен: lhs.swap(rhs);

size_t hash_value (const path& p) noexcept;

Returns: Хэш-значение для пути p. Если по двум путям, p1 == p2 то hash_­value(p1) == hash_­value(p2).

bool operator< (const path& lhs, const path& rhs) noexcept;

Returns: lhs.compare(rhs) < 0.

bool operator<=(const path& lhs, const path& rhs) noexcept;

Returns: !(rhs < lhs).

bool operator> (const path& lhs, const path& rhs) noexcept;

Returns: rhs < lhs.

bool operator>=(const path& lhs, const path& rhs) noexcept;

Returns: !(lhs < rhs).

bool operator==(const path& lhs, const path& rhs) noexcept;

Returns: !(lhs < rhs) && !(rhs < lhs).

[ Note: Равенство путей и эквивалентность путей имеют разную семантику.

  • Равенство определяется тем, кто path не является членом operator==, который рассматривает только лексические представления двух путей. [ Example: path("foo") == "bar" никогда не бывает true. ] end example

  • Эквивалентность определяется equivalent() функцией, не являющейся членом, которая определяет, есть ли два пути resolve к одному и тому же объекту файловой системы. [ Example: equivalent("foo", "bar") будет, true когда оба пути разрешатся в один и тот же файл. ] end example

Программисты, желающие определить, являются ли два пути «одинаковыми», должны решить, означает ли «одинаковый» «одно и то же представление» или «разрешить один и тот же фактический файл», и выбрать соответствующую функцию соответственно. ] end note

bool operator!=(const path& lhs, const path& rhs) noexcept;

Returns: !(lhs == rhs).

path operator/ (const path& lhs, const path& rhs);

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

30.10.27.6.1 path inserter and extractor [fs.path.io]

template <class charT, class traits> basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, const path& p);

Effects: Эквивалент: os << quoted(p.string<charT, traits>()); [ функция описана в . ]Note: quoted [quoted.manip] end note

Returns: os.

template <class charT, class traits> basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>& is, path& p);

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

basic_string<charT, traits> tmp;
is >> quoted(tmp);
p = tmp;

Returns: is.

30.10.27.6.2 path factory functions [fs.path.factory]

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

Requires: Последовательности source и [first, last) кодируются в кодировке UTF-8. Тип значения Source и InputIterator есть char.

Returns:

  • Если value_­type есть, char а текущий native narrow encoding - UTF-8, вернуть path(source) или path(first, last); иначе,

  • если value_­type есть, wchar_­t а собственная широкая кодировка - UTF-16, или если value_­type есть, char16_­t или char32_­t, преобразовать source или [first, last) во временное, tmpтипа string_­type и возврата path(tmp); иначе,

  • преобразовать source или [first, last) во временное, tmpтипа u32string и возврата path(tmp).

Remarks: Argument format conversion применяется к аргументам этих функций. Как выполняется преобразование кодировки Unicode, не указано.

[ Example: Строка должна быть прочитана из базы данных, закодированной в UTF-8, и использована для создания каталога с использованием собственной кодировки для имен файлов:

namespace fs = std::filesystem;
std::string utf8_string = read_utf8_data();
fs::create_directory(fs::u8path(utf8_string));

Для операционных систем на основе POSIX с собственной узкой кодировкой, установленной на UTF-8, кодирование или преобразование типов не происходит.

Для операционных систем на основе POSIX, в которых для собственной узкой кодировки не задано значение UTF-8, происходит преобразование в UTF-32, за которым следует преобразование в текущую собственную узкую кодировку. Некоторые символы Unicode могут не иметь собственного представления набора символов.

Для операционных систем на базе Windows происходит преобразование из UTF-8 в UTF-16. ] end example