std::filesystem::canonical, std::filesystem::weakly_canonical

Определено в заголовочном файле `<filesystem>`
path canonical( const std::filesystem::path& p );	(1)	(начиная с C++17)
path canonical( const std::filesystem::path& p, std::error_code& ec );	(2)	(начиная с C++17)
path weakly_canonical( const std::filesystem::path& p );	(3)	(начиная с C++17)
path weakly_canonical( const std::filesystem::path& p, std::error_code& ec );	(4)	(начиная с C++17)

1,2) Преобразует путь p в канонический абсолютный путь, то есть абсолютный путь, не содержащий элементов «.» и «..» или символических ссылок в представлении в обобщённом формате. Если p не является абсолютным путём, функция ведёт себя так, как если бы сначала он был преобразован в абсолютный с помощью std::filesystem::absolute(p). Путь p должен существовать.

3,4) Возвращает путь, составленный из operator/= по результату вызова canonical() с аргументом-путём, составленным из существующих начальных элементов p (что определяется с помощью status(p) или status(p, ec)), если таковые имеются, за которыми следуют несуществующие элементы p. Результирующий путь имеет нормальную форму.

Параметры

p	-	путь, который может быть абсолютным или относительным; для `canonical` он должен существовать
ec	-	код ошибки для сохранения статуса ошибки

Возвращаемое значение

1,2) Абсолютный путь, указывающий на тот же файл, что и std::filesystem::absolute(p).

3,4) Путь в нормальной форме вида canonical(x)/y, где x — путь, составленный из самой длинной начальной последовательности существующих элементов в p, а y — путь, составленный из оставшихся завершающих несуществующих элементов p.

Исключения

Любая перегрузка, не помеченная noexcept, может выбросить std::bad_alloc при сбое выделения памяти.

1,3) Выбрасывает std::filesystem::filesystem_error при ошибках базового API ОС; исключение создаётся с p в качестве первого аргумента-пути и с кодом ошибки ОС в качестве аргумента кода ошибки.

2,4) Устанавливает параметр std::error_code& в код ошибки API ОС, если вызов API ОС завершается неудачно, и выполняет ec.clear(), если ошибок не возникает.

Примечания

Функция canonical() моделирует функцию POSIX realpath.

Функция weakly_canonical() была введена для упрощения операционной семантики relative().

Пример

#include <filesystem>
#include <iostream>

int main()
{
    /* set up sandbox directories:
     a
     └── b
         ├── c1
         │   └── d <== current path
         └── c2
             └── e
    */
    auto old = std::filesystem::current_path();
    auto tmp = std::filesystem::temp_directory_path();
    std::filesystem::current_path(tmp);
    auto d1 = tmp / "a/b/c1/d";
    auto d2 = tmp / "a/b/c2/e";
    std::filesystem::create_directories(d1);
    std::filesystem::create_directories(d2);
    std::filesystem::current_path(d1);

    auto p1 = std::filesystem::path("../../c2/./e");
    auto p2 = std::filesystem::path("../no-such-file");
    std::cout << "Current path is "
              << std::filesystem::current_path() << '\n'
              << "Canonical path for " << p1 << " is "
              << std::filesystem::canonical(p1) << '\n'
              << "Weakly canonical path for " << p2 << " is "
              << std::filesystem::weakly_canonical(p2) << '\n';
    try
    {
        [[maybe_unused]] auto x_x = std::filesystem::canonical(p2);
        // NOT REACHED
    }
    catch (const std::exception& ex)
    {
        std::cout << "Canonical path for " << p2 << " threw exception:\n"
                  << ex.what() << '\n';
    }

    // cleanup
    std::filesystem::current_path(old);
    const auto count = std::filesystem::remove_all(tmp / "a");
    std::cout << "Deleted " << count << " files or directories.\n";
}

Возможный вывод:

Current path is "/tmp/a/b/c1/d"
Canonical path for "../../c2/./e" is "/tmp/a/b/c2/e"
Weakly canonical path for "../no-such-file" is "/tmp/a/b/c1/no-such-file"
Canonical path for "../no-such-file" threw exception:
filesystem error: in canonical: No such file or directory [../no-such-file] [/tmp/a/b/c1/d]
Deleted 6 files or directories.

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

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

DR	Применяется к	Опубликованное поведение	Исправленное поведение
LWG 2956	C++17	`canonical` имеет лишний параметр `base`	удалён

См. также

path (C++17)	представляет путь (класс)
absolute (C++17)	составляет абсолютный путь (функция)
relativeproximate (C++17)	составляет относительный путь (функция)

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