Namespaces
Variants

std::filesystem:: path

From cppreference.net
C++
Filesystem library
Classes
Functions
File types
std::filesystem::path
Member types
Member constants
Member functions
Path decomposition
Non-member functions
(until C++20) (until C++20) (until C++20) (until C++20) (until C++20) (C++20)
Helper classes
Определено в заголовке <filesystem>
class path ;
(начиная с C++17)

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

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

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

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

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

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

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

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

В любом случае, класс path ведет себя так, как будто хранит путь в нативном формате и автоматически конвертирует в generic формат по мере необходимости (каждая функция-член указывает, в каком формате она интерпретирует путь).

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

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

Потоковые операторы stream operators используют std::quoted , чтобы пробелы не вызывали усечение при последующем чтении с помощью stream input operator .

Функции-члены декомпозиции (например, 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
определяет, как интерпретировать строковые представления путей.

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

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

(общедоступное перечисление)

Константы-члены

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

Функции-члены

конструирует path
(public member function)
уничтожает объект path
(public member function)
присваивает другой путь
(public member function)
назначает содержимое
(публичная функция-член)
Конкатенация
добавляет элементы к пути с разделителем директорий
(публичная функция-член)
объединяет два пути без введения разделителя директорий
(публичная функция-член)
Модификаторы
очищает содержимое
(публичная функция-член)
преобразует разделители директорий в предпочтительный разделитель директорий
(public member function)
удаляет компонент пути с именем файла
(публичная функция-член)
заменяет последний компонент пути другим путём
(публичная функция-член)
заменяет расширение
(публичная функция-член)
обменивает два пути
(публичная функция-член)
Наблюдатели формата
возвращает нативную версию пути
(публичная функция-член)
возвращает путь в формате родного пути, преобразованный в строку
(public member function)
возвращает путь в общем формате имени пути, преобразованный в строку
(публичная функция-член)
Сравнение
сравнивает лексические представления двух путей лексикографически
(публичная функция-член)
Генерация
преобразует путь в нормальную форму
преобразует путь в относительную форму
преобразует путь в проксимальную форму
(публичная функция-член)
Декомпозиция
возвращает корневое имя пути, если оно присутствует
(публичная функция-член)
возвращает корневую директорию пути, если она присутствует
(публичная функция-член)
возвращает корневой путь пути, если он присутствует
(публичная функция-член)
возвращает путь относительно корневого пути
(публичная функция-член)
возвращает путь родительской директории
(публичная функция-член)
возвращает компонент пути filename
(публичная функция-член)
возвращает компонент пути stem (имя файла без конечного расширения)
(публичная функция-член)
возвращает компонент пути с расширением файла
(публичная функция-член)
Запросы
проверяет, является ли путь пустым
(публичная функция-член)
проверяет, не является ли соответствующий элемент пути пустым
(публичная функция-член)
проверяет, идентифицирует ли root_path() уникальное расположение в файловой системе
(public member function)
Итераторы
итераторный доступ к пути как к последовательности элементов
(публичная функция-член)

Функции, не являющиеся членами класса

Определено в пространстве имен std::filesystem
(C++17)
специализирует алгоритм std::swap
(функция)
(C++17)
вычисляет хэш-значение для объекта пути
(функция)
(C++17) (C++17) (until C++20) (C++17) (until C++20) (C++17) (until C++20) (C++17) (until C++20) (C++17) (until C++20) (C++20)
лексикографически сравнивает два пути
(функция)
(C++17)
объединяет два пути с разделителем директории
(функция)
(C++17)
выполняет потоковый ввод и вывод для пути в кавычках
(функция)
(C++17) (deprecated in C++20)
создает path из источника в кодировке UTF-8
(функция)

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

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

Отчеты о дефектах

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

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