std::filesystem::relative, std::filesystem::proximate

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

1) Возвращает relative(p, current_path(), ec).

2,3) Возвращает p, заданный относительно base. Перед дальнейшей обработкой разрешает символические ссылки и нормализует p и base. По сути возвращает std::filesystem::weakly_canonical(p).lexically_relative(std::filesystem::weakly_canonical(base)) или std::filesystem::weakly_canonical(p, ec).lexically_relative(std::filesystem::weakly_canonical(base, ec)), за исключением того, что вариант с кодом ошибки возвращает path() при первом возникновении ошибки, если таковая имеется.

4) Возвращает proximate(p, current_path(), ec).

5,6) По сути возвращает std::filesystem::weakly_canonical(p).lexically_proximate(std::filesystem::weakly_canonical(base)) или std::filesystem::weakly_canonical(p, ec).lexically_proximate(std::filesystem::weakly_canonical(base, ec)), за исключением того, что вариант с кодом ошибки возвращает path() при первом возникновении ошибки, если таковая имеется.

Параметры

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

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

1) p, преобразованный в относительную форму относительно current_path().

2,3) p, преобразованный в относительную форму относительно base.

4) p, преобразованный в приближенную форму относительно current_path().

5,6) p, преобразованный в приближенную форму относительно base.

Исключения

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

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

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

Пример

#include <filesystem>
#include <iostream>

void show(std::filesystem::path x, std::filesystem::path y)
{
    std::cout << "x:\t\t " << x << "\ny:\t\t " << y << '\n'
              << "relative(x, y):  "
              << std::filesystem::relative(x, y) << '\n'
              << "proximate(x, y): "
              << std::filesystem::proximate(x, y) << "\n\n";
}

int main()
{
    show("/a/b/c", "/a/b");
    show("/a/c", "/a/b");
    show("c", "/a/b");
    show("/a/b", "c");
}

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

x:               "/a/b/c"
y:               "/a/b"
relative(x, y):  "c"
proximate(x, y): "c"

x:               "/a/c"
y:               "/a/b"
relative(x, y):  "../c"
proximate(x, y): "../c"

x:               "c"
y:               "/a/b"
relative(x, y):  ""
proximate(x, y): "c"

x:               "/a/b"
y:               "c"
relative(x, y):  ""
proximate(x, y): "/a/b"

См. также

path (C++17)	представляет путь (класс)
absolute (C++17)	создаёт абсолютный путь (функция)
canonicalweakly_canonical (C++17)	создаёт канонический путь (функция)
lexically_normallexically_relativelexically_proximate	преобразует путь в нормальную форму преобразует путь в относительную форму преобразует путь в приближенную форму (открытая функция-член класса `std::filesystem::path`)

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