Namespaces
Variants
Views
Actions

Difference between revisions of "cpp/filesystem/absolute"

From cppreference.com
(matched parenthesis)
m (→‎Exceptions: 1), 2))
 
(15 intermediate revisions by 10 users not shown)
Line 1: Line 1:
−
{{cpp/filesystem/title|absolute|system_complete}}
+
{{cpp/filesystem/title|absolute}}
 
{{cpp/filesystem/navbar}}
 
{{cpp/filesystem/navbar}}
 
{{dcl begin}}
 
{{dcl begin}}
−
{{dcl header | filesystem}}
+
{{dcl header|filesystem}}
−
{{dcl | since=c++17 |num=1|1=
+
{{dcl|num=1|since=c++17|1=
−
path absolute( const std::filesystem::path& p,
+
path absolute( const std::filesystem::path& p );
−
              const std::filesystem::path& base = std::filesystem::current_path() );
+
 
}}
 
}}
−
{{dcl | since=c++17 | num=2 |
+
{{dcl|num=2|since=c++17|1=
−
path system_complete(const std::filesystem::path& p);
+
path absolute( const std::filesystem::path& p, std::error_code& ec );
−
path system_complete(const std::filesystem::path& p, std::error_code& ec);
+
 
}}
 
}}
 
{{dcl end}}
 
{{dcl end}}
  
−
@1@ Returns absolute path of {{tt|p}} relative to {{tt|base}} according to the following rules:
+
Returns a path referencing the same file system location as {{c|p}}, for which {{ltt|cpp/filesystem/path/is_absrel|filesystem::path::is_absolute()}} is {{c|true}}.
−
:* If {{tt|p}} has both root name and root directory (e.g. {{c|"C:\users"}}, then the path is returned, unmodified.
+
 
−
:* If {{tt|p}} has a root name not followed by a root directory (e.g. {{c|"C:text.txt"}}), then {{tt|base}} is inserted between {{tt|p}}'s root name and the remainder of {{tt|p}}. Formally, {{c|p.root_name() / absolute(base).root_directory() / absolute(base).relative_path() / p.relative_path()}} is returned,
+
@2@ This non-throwing overload returns default-constructed path if an error occurs.
−
:* If {{tt|p}} has no root name, but has a root directory (e.g. {{c|"/var/tmp/file.txt"}} on a POSIX system or {{c|"\users\ABC\Document.doc"}} on Windows), then the root name of {{tt|base}}, if it has one, is prepended to {{tt|p}} (on a POSIX system, {{tt|p}} is not modified, on a Windows system, {{c|"\users\ABC\Document.doc"}} becomes {{c|"C:\users\ABC\Document.doc"}}. Formally, {{c|absolute(base).root_name() / p}} is returned.
+
−
:* If {{tt|p}} has no root name and no root directory (e.g. {{c|"../file.txt"}}, then the entire {{tt|base}} is prepended to {{tt|p}}. Formally, {{c|absolute(base) / p}} is returned.
+
−
@2@ Obtains the absolute path that identifies the file that the OS file opening API would access given the pathname {{tt|p}}. On POSIX systems, this is equivalent to {{v|1}} with the default {{tt|base}} ({{tt|current_path()}}). On Windows systems, each logical drive has its own current working directory, and so if {{tt|p}} is not already absolute and has a root name component (e.g. {{c|"E:filename.txt"}}, that drive's current working directory is used, which may have been set by an earlier executed program.
+
  
 
===Parameters===
 
===Parameters===
 
{{par begin}}
 
{{par begin}}
−
{{par | p | path to convert to absolute form}}
+
{{par|p|path to convert to absolute form}}
−
{{par | base | path (not necessarily absolute) to serve as the starting location }}
+
{{par|ec|out-parameter for error reporting in the non-throwing overload}}
−
{{par | ec | out-parameter for error reporting in the non-throwing overload }}
+
 
{{par end}}
 
{{par end}}
  
 
===Return value===
 
===Return value===
−
Returns an absolute (although not necessarily canonical) path formed by combining {{tt|p}} and {{tt|base}} as described above.
+
Returns an absolute (although not necessarily canonical) pathname referencing the same file as {{c|p}}.
  
 
===Exceptions===
 
===Exceptions===
−
{{cpp/filesystem/error_handling|p|base}}
+
{{cpp/filesystem/error handling|p|throw=1/2}}
  
 
===Notes===
 
===Notes===
−
On systems that support root names (e.g. Windows), the result of calling {{tt|absolute}} on a relative path that has a root name (e.g. {{c|"D:file.txt"}} when the root name of {{tt|base}} is different will usually result in a non-existent path.
+
Implementations are encouraged to not consider {{c|p}} not existing to be an error.
 +
 
 +
For POSIX-based operating systems, {{c|std::filesystem::absolute(p)}} is equivalent to {{c|std::filesystem::current_path() / p}} except for when {{c|p}} is the empty path.
 +
 
 +
For Windows, {{tt|std::filesystem::absolute}} may be implemented as a call to [https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-getfullpathnamew {{tt|GetFullPathNameW}}].
  
 
===Example===
 
===Example===
−
{{example|code=
+
{{example
−
#include <iostream>
+
|code=
 
#include <filesystem>
 
#include <filesystem>
 +
#include <iostream>
 
namespace fs = std::filesystem;
 
namespace fs = std::filesystem;
 +
 
int main()
 
int main()
 
{
 
{
−
     fs::path p = "C:cl.exe";
+
     std::filesystem::path p = "foo.c";
−
     std::cout << "Current path is " << fs::current_path() << '\n'
+
     std::cout << "Current path is " << std::filesystem::current_path() << '\n';
−
              << "Absolute path for " << p << " is " << fs::absolute(p) << '\n'
+
    std::cout << "Absolute path for " << p << " is " << fs::absolute(p) << '\n';
−
      << "System complete path for " << p << " is " << fs::system_complete(p) << '\n';
+
 
}
 
}
 
|p=true
 
|p=true
 
|output=
 
|output=
−
Current path is "D:/local/ConsoleApplication1"
+
Current path is "/tmp/1666297965.0051296"
−
Absolute path for "C:cl.exe" is "C:/local/ConsoleApplication1/cl.exe"
+
Absolute path for "foo.c" is "/tmp/1666297965.0051296/foo.c"
−
System complete path for "C:cl.exe" is "C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\bin\cl.exe"
+
 
}}
 
}}
  
 
===See also===
 
===See also===
 
{{dsc begin}}
 
{{dsc begin}}
−
{{dsc inc | cpp/filesystem/dsc canonical}}
+
{{dsc inc|cpp/filesystem/dsc canonical}}
−
{{dsc inc | cpp/filesystem/dsc relative}}
+
{{dsc inc|cpp/filesystem/dsc relative}}
 
{{dsc end}}
 
{{dsc end}}
 +
 +
{{langlinks|es|ja|ru|zh}}

Latest revision as of 08:32, 4 September 2023

 
C++
 
Filesystem library
Classes
Functions
File types
 
Defined in header <filesystem>
path absolute( const std::filesystem::path& p );
 (1) (since C++17)
path absolute( const std::filesystem::path& p, std::error_code& ec );
 (2) (since C++17)

Returns a path referencing the same file system location as p, for which filesystem::path::is_absolute() is true.

2) This non-throwing overload returns default-constructed path if an error occurs.

Contents

[edit] Parameters

p - path to convert to absolute form
ec - out-parameter for error reporting in the non-throwing overload

[edit] Return value

Returns an absolute (although not necessarily canonical) pathname referencing the same file as p.

[edit] Exceptions

Any overload not marked noexcept may throw std::bad_alloc if memory allocation fails.

1) Throws std::filesystem::filesystem_error on underlying OS API errors, constructed with p as the first path argument and the OS error code as the error code argument.
2) Sets a std::error_code& parameter to the OS API error code if an OS API call fails, and executes ec.clear() if no errors occur.

[edit] Notes

Implementations are encouraged to not consider p not existing to be an error.

For POSIX-based operating systems, std::filesystem::absolute(p) is equivalent to std::filesystem::current_path() / p except for when p is the empty path.

For Windows, std::filesystem::absolute may be implemented as a call to GetFullPathNameW.

[edit] Example

Run this code
#include <filesystem>
#include <iostream>
namespace fs = std::filesystem;
 
int main()
{
    std::filesystem::path p = "foo.c";
    std::cout << "Current path is " << std::filesystem::current_path() << '\n';
    std::cout << "Absolute path for " << p << " is " << fs::absolute(p) << '\n';
}

Possible output: 

Current path is "/tmp/1666297965.0051296"
Absolute path for "foo.c" is "/tmp/1666297965.0051296/foo.c"

[edit] See also

(C++17)
 composes a canonical path
(function) [edit]
(C++17)
 composes a relative path
(function) [edit]
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/filesystem/absolute&oldid=157936"