Spec-Zone.ru › C++

std::filesystem::path

Определено в заголовке <filesystem> 
class path;
 (с C++17)

Объекты типа path представляют пути к файлам в файловой системе. Обрабатываются только синтаксические аспекты путей: имя пути может представлять несуществующий путь или даже путь, который не разрешён к существованию в текущей файловой системе или ОС.

Имя пути имеет следующий синтаксис:

  1. имя-корня(необязательно): определяет корень в файловой системе с несколькими корнями (например, "C:" или "//myserver"). В случае неоднозначности, самая длинная последовательность символов, образующая допустимое имя-корня, рассматривается как имя-корня. Стандартная библиотека может определять дополнительные имена корней помимо тех, которые понимает API ОС.
  2. корневой-каталог(необязательно): разделитель каталогов, который, если присутствует, указывает на то, что этот путь является абсолютным. Если его нет (и первый элемент, отличный от имени корня, является именем файла), то путь является относительным и требует другого пути в качестве начальной точки для разрешения до имени файла.
  3. Ноль или более из следующих:
  • имя-файла: последовательность символов, которые не являются разделителями каталогов или предпочтительными разделителями каталогов (дополнительные ограничения могут быть наложены ОС или файловой системой). Это имя может указывать на файл, жёсткую ссылку, символическую ссылку или каталог. Распознаются два специальных имени-файла:
    • точка: имя файла, состоящее из одного символа точки ., — это имя каталога, которое ссылается на текущий каталог.
    • точка-точка: имя файла, состоящее из двух символов точки .., — это имя каталога, которое ссылается на родительский каталог.
  • разделители-каталогов: символ косой черты / или альтернативный символ, предоставленный как path::preferred_separator. Если этот символ повторяется, он обрабатывается как один разделитель каталогов: /usr///////lib равно /usr/lib.

Путь может быть нормализован следующим алгоритмом:

  1. Если путь пустой, остановиться (нормальная форма пустого пути — пустой путь).
  2. Заменить каждый разделитель-каталогов (который может состоять из нескольких косых черт) на один path::preferred_separator.
  3. Заменить каждый символ косой черты в имени-корня на path::preferred_separator.
  4. Удалить каждую точку и любой немедленно следующий разделитель-каталогов.
  5. Удалить каждое имя файла, отличное от точка-точка, сразу за которым следует разделитель-каталогов и точка-точка, а также любой немедленно следующий разделитель-каталогов.
  6. Если есть корневой-каталог, удалить все точка-точка и любые разделители-каталогов сразу за ними.
  7. Если последним именем файла является точка-точка, удалить любой конечный разделитель-каталогов.
  8. Если путь пустой, добавить точку (нормальная форма ./ — .).

Путь может быть пройден по элементам с помощью итераторов, возвращаемых функциями begin() и end(), которые отображают путь в общем формате и итерируют по имени корня, корневому каталогу и последующим элементам имени файла (разделители каталогов пропускаются, за исключением того, который идентифицирует корневой каталог). Если самый последний элемент в пути — разделитель каталогов, последний итератор будет ссылаться на пустой элемент.

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

Если ОС использует нативный синтаксис, отличающийся от переносимого общего синтаксиса, описанного выше, функции библиотеки, определённые для принятия "обнаруженного формата", принимают имена путей в обоих форматах: аргумент обнаруженного формата считается имеющим общий формат только в том случае, если он соответствует общему формату, но не является приемлемым для операционной системы в качестве нативного пути. В тех ОС, где нативный формат отличается между именами путей каталогов и именами путей файлов, общий путь рассматривается как путь к каталогу, если он заканчивается на разделителе каталогов, и как обычный файл в противном случае.

В любом случае, класс пути ведёт себя так, как если бы он хранил имя пути в нативном формате и автоматически преобразовывал его в общий формат по мере необходимости (каждый метод указывает, какой формат он интерпретирует как путь).

В системах POSIX общий формат является нативным форматом, и нет необходимости различать или преобразовывать между ними.

Пути неявно преобразуются в std::basic_string и из них, что позволяет использовать их с другими API файлов.

Операторы потоков операторы ввода-вывода используют std::quoted, чтобы пробелы не приводили к обрезанию при последующем чтении оператором ввода потока.

Функции разбиения (например, extension) возвращают объекты filesystem::path вместо строк, как это делают другие API.

Типы и константы членов

Тип Определение
value_type тип символа, используемый в кодировке, нативной для файловой системы: char в POSIX, wchar_t в Windows
string_type std::basic_string<value_type>
const_iterator постоянный LegacyInputIterator с value_type типа path, удовлетворяющий всем требованиям LegacyBidirectionalIterator, за исключением того, что для двух равных доступных итераторов a и b типа const_iterator нет требования, что *a и *b ссылаются на один и тот же объект.

Неопределено, является ли const_iterator фактически LegacyBidirectionalIterator
iterator псевдоним для const_iterator
формат
(C++17)
 определяет, как интерпретировать строковые представления имён путей.

Также определены следующие перечисления:

Константа Объяснение
native_format нативный формат имён путей
generic_format общий формат имён путей
auto_format формат, определяемый реализацией, автоматически обнаруживаемый, где это возможно

(перечисление)

Члены-константы

constexpr value_type preferred_separator
[static]
 альтернативный разделитель каталогов, который может использоваться дополнительно к переносимому /. В Windows это обратная косая черта \. В POSIX это та же косая черта /, что и переносимый разделитель
(общедоступная статическая константа-член)

Члены-функции

(конструктор)
 создаёт path
(публичный член-функция)
(деструктор)
 уничтожает объект path
(публичный член-функция)
operator=
 присваивает другой путь
(публичный член-функция)
assign
 присваивает содержимое
(публичный член-функция)
Конкатенация
appendoperator/=
 добавляет элементы в путь с разделителем каталогов
(публичный член-функция)
concatoperator+=
 конкатенирует два пути без введения разделителя каталогов
(публичный член-функция)
Модификаторы
clear
 очищает содержимое
(публичный член-функция)
make_preferred
 преобразует разделители каталогов в предпочтительный разделитель каталогов
(публичный член-функция)
remove_filename
 удаляет компонент имени файла пути
(публичный член-функция)
replace_filename
 заменяет последний компонент пути другим путём
(публичный член-функция)
replace_extension
 заменяет расширение
(публичный член-функция)
swap
 меняет местами два пути
(публичный член-функция)
Наблюдатели формата
c_strnativeoperator string_type
 возвращает родную версию пути
(публичный член-функция)
stringwstringu8stringu16stringu32string
 возвращает путь в формате родного имени файла, преобразованного в строку
(публичный член-функция)
generic_stringgeneric_wstringgeneric_u8stringgeneric_u16stringgeneric_u32string
 возвращает путь в формате универсального имени файла, преобразованного в строку
(публичный член-функция)
Сравнение
compare
 сравнивает лексические представления двух путей лексикографически
(публичный член-функция)
Генерация
lexically_normallexically_relativelexically_proximate
 преобразует путь в нормальную форму
преобразует путь в относительную форму
преобразует путь в приблизительную форму
(публичный член-функция)
Декомпозиция
root_name
 возвращает имя корня пути, если оно есть
(публичный член-функция)
root_directory
 возвращает корневой каталог пути, если он есть
(публичный член-функция)
root_path
 возвращает корневой путь пути, если он есть
(публичный член-функция)
relative_path
 возвращает путь относительно корневого пути
(публичный член-функция)
parent_path
 возвращает путь родительского пути
(публичный член-функция)
filename
 возвращает компонент имени файла пути
(публичный член-функция)
stem
 возвращает компонент пути стема (имя файла без окончательного расширения)
(публичный член-функция)
extension
 возвращает компонент пути расширения файла
(публичный член-функция)
Запросы
empty
 проверяет, пуст ли путь
(публичный член-функция)
has_root_pathhas_root_namehas_root_directoryhas_relative_pathhas_parent_pathhas_filenamehas_stemhas_extension
 проверяет, соответствует ли соответствующий элемент пути непустому значению
(публичный член-функция)
is_absoluteis_relative
 проверяет, однозначно ли root_path() указывает на местоположение файловой системы
(публичный член-функция)
Итераторы
beginend
 доступ к итератору к пути как к последовательности элементов
(публичный член-функция)

Нечленные функции

Определено в пространстве имен std::filesystem
swap(std::filesystem::path)
(C++17)
 меняет местами два пути
(функция)
hash_value
(C++17)
 вычисляет значение хеша для объекта пути
(функция)
operator==operator!=operator<operator<=operator>operator>=operator<=>
(C++17)(C++17)(до C++20)(C++17)(до C++20)(C++17)(до C++20)(C++17)(до C++20)(C++17)(до C++20)(C++20)
 лексикографически сравнивает два пути
(функция)
operator/
(C++17)
 конкатенирует два пути с разделителем каталога
(функция)
operator<<operator>>
(C++17)
 выполняет потоковый ввод-вывод для пути в кавычках
(функция)
u8path
(C++17)(устарело в C++20)
 создаёт path из UTF-8 кодированного источника
(функция)

Вспомогательные классы

Определено в пространстве имен std
std::hash<std::filesystem::path>
(C++17)
 поддержка хеширования для std::filesystem::path
(специализация шаблона класса)

Отчеты об ошибках

Следующие отчеты об ошибках, изменяющие поведение, были применены ретроактивно к ранее опубликованным стандартам C++.

DR Применено к Поведение как опубликовано Корректное поведение
LWG 3657 C++17 hash для path было отключено включено

© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://en.cppreference.com/w/cpp/filesystem/path

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API