Namespaces
Variants
Views
Actions

Difference between revisions of "cpp/filesystem/absolute"

From cppreference.com
(matched parenthesis)
(p0492r2's rewrite of absolute(). RIP, system_complete)
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 | since=c++17 |num=1|1=
−
path absolute( const std::filesystem::path& p,
+
path absolute(const std::filesystem::path& p);
−
              const std::filesystem::path& base = std::filesystem::current_path() );
+
path absolute(const std::filesystem::path& p, std::error_code& ec);
−
}}
+
−
{{dcl | since=c++17 | num=2 |
+
−
path system_complete(const std::filesystem::path& p);
+
−
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:
+
@1@ Returns a path referencing the same file system location as {{c|p}}, for which {{ltt|cpp/filesystem/path/is_absrel|is_absolute()}} is {{c|true}}. The non-throwing overload returns default-constructed path if an error occurs.
−
:* 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,
+
−
:* 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 {{tt|p}}
  
 
===Exceptions===
 
===Exceptions===
−
{{cpp/filesystem/error_handling|p|base}}
+
{{cpp/filesystem/error_handling|p}}
  
 
===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.
+
It is not an error if {{tt|absolute}} results in a path that refers to a non-existent file. In particular, 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 current working directory is on a different root name, will usually result in a non-existent path.
 +
 
 +
For POSIX-based operating systems, {{c|std::filesystem::absolute(p)}} is equivalent to {{c|std::filesystem::current_path() / p}}
 +
 
 +
For Windows, {{tt|absolute}} may be implemented as a call to [https://msdn.microsoft.com/en-us/library/windows/desktop/aa364963(v=vs.85).aspx GetFullPathNameW].
  
 
===Example===
 
===Example===
Line 45: Line 39:
 
     fs::path p = "C:cl.exe";
 
     fs::path p = "C:cl.exe";
 
     std::cout << "Current path is " << fs::current_path() << '\n'
 
     std::cout << "Current path is " << fs::current_path() << '\n'
−
               << "Absolute path for " << p << " is " << fs::absolute(p) << '\n'
+
               << "Absolute path for " << p << " is " << fs::absolute(p) << '\n';
−
      << "System complete path for " << p << " is " << fs::system_complete(p) << '\n';
+
// actual location: "C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\bin\cl.exe"
 
}
 
}
 
|p=true
 
|p=true
Line 52: Line 46:
 
Current path is "D:/local/ConsoleApplication1"
 
Current path is "D:/local/ConsoleApplication1"
 
Absolute path for "C:cl.exe" is "C:/local/ConsoleApplication1/cl.exe"
 
Absolute path for "C:cl.exe" is "C:/local/ConsoleApplication1/cl.exe"
−
System complete path for "C:cl.exe" is "C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\bin\cl.exe"
 
 
}}
 
}}
  

Revision as of 13:52, 20 April 2017

 
C++
 
Filesystem library
Classes
Functions
File types
 
Defined in header <filesystem>
path absolute(const std::filesystem::path& p);
path absolute(const std::filesystem::path& p, std::error_code& ec);
 (1) (since C++17)
1) Returns a path referencing the same file system location as p, for which is_absolute() is true. The non-throwing overload returns default-constructed path if an error occurs.

Contents

Parameters

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

Return value

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

Exceptions

Any overload not marked noexcept may throw std::bad_alloc if memory allocation fails.
The overload that does not take a std::error_code& parameter 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. The overload taking a std::error_code& parameter sets it to the OS API error code if an OS API call fails, and executes ec.clear() if no errors occur.

Notes

It is not an error if absolute results in a path that refers to a non-existent file. In particular, on systems that support root names (e.g. Windows), the result of calling absolute on a relative path that has a root name (e.g. "D:file.txt" when the current working directory is on a different root name, will usually result in a non-existent path.

For POSIX-based operating systems, std::filesystem::absolute(p) is equivalent to std::filesystem::current_path() / p

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

Example

Run this code
#include <iostream>
#include <filesystem>
namespace fs = std::filesystem;
int main()
{
    fs::path p = "C:cl.exe";
    std::cout << "Current path is " << fs::current_path() << '\n'
              << "Absolute path for " << p << " is " << fs::absolute(p) << '\n';
// actual location: "C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\bin\cl.exe"
}

Possible output: 

Current path is "D:/local/ConsoleApplication1"
Absolute path for "C:cl.exe" is "C:/local/ConsoleApplication1/cl.exe"

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=92528"