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/w/cpp/filesystem/canonical