Filesystem Tutorial |
Home Tutorial Reference FAQ Releases Portability V3 Intro V3 Design Deprecated Bug Reports |
Introduction
Preliminaries
Reporting the size of a file - (tut1.cpp)
Using status queries to determine file existence and type - (tut2.cpp)
Directory iteration plus catching
exceptions - (tut3.cpp)
Using path decomposition, plus sorting results - (tut4.cpp)
Class path: Constructors, including
Unicode - (tut5.cpp)
Class path: Generic format vs. Native format
Class path: Iterators, observers, composition, decomposition, and query - (path_info.cpp)
Error reporting
This tutorial develops a little command line program to list information
about files and directories - essentially a much simplified version of the POSIX ls
or Windows dir
commands. We'll start with the simplest possible version and progress to more
complex functionality. Along the way we'll digress to cover topics you'll need
to know about to understand Boost.Filesystem.
Source code for each of the tutorial programs is available, and you are encouraged to compile, test, and experiment with it. To conserve space, we won't always show boilerplate code here, but the provided source is complete and ready to build.
Install the Boost distribution if you haven't already done so. See the Boost Getting Started docs.
This tutorial assumes you are going to compile and test the examples using the provided scripts. That's highly recommended.
If you are planning to compile and test the examples but not use the scripts, make sure your build setup knows where to locate or build the Boost library binaries.
Fire up your command line interpreter, and type the following commands:
Ubuntu Linux |
$ cd boost-root/libs/filesystem/example/test $ ./setup.sh Copying example programs... $ ./build.sh Compiling example programs... $ ./tut1 Usage: tut1 path |
Microsoft Windows |
>cd boost-root\libs\filesystem\example\test >setup Copying example programs... >build Compiling example programs... >tut1 Usage: tut1 path |
If the tut1
command outputs "Usage: tut1 path
", all
is well. A set of tutorial example programs has been copied (by setup
) to
boost-root
/libs/filesystem/example/test
and then built. You are encouraged to modify and experiment with them as the
tutorial progresses. Just invoke the build
script again to rebuild,
or invoke b2
directly.
If something didn't work right, here are some troubleshooting suggestions:
b2
program executable isn't being found, check your path environmental variable
or see
Boost
Getting Started.b2.log
to try to spot an indication of the
problem.Let's get started. Our first example program, tut1.cpp, reports the size of a file:
#include <iostream> #include <boost/filesystem.hpp> using namespace boost::filesystem; int main(int argc, char* argv[]) { if (argc < 2) { std::cout << "Usage: tut1 path\n"; return 1; } std::cout << argv[1] << " " << file_size(argv[1]) << '\n'; return 0; } |
The Boost.Filesystem file_size
function returns a uintmax_t
containing the size of the file named by the argument. The declaration looks
like this:
uintmax_t file_size(const path& p);
For now, all you need to know is that class path
has constructors that take
const char *
and other string types. (If you can't wait to
find out more, skip ahead to the class path section of
the tutorial.)
Please take a minute to try out tut1
on your system, using a
file that is known to exist, such as tut1.cpp
. Here is what the
results look like on two different operating systems:
Ubuntu Linux |
$ ./tut1 tut1.cpp tut1.cpp 569 $ ls -l tut1.cpp -rw-rw-r-- 1 beman beman 569 Jul 26 12:04 tut1.cpp |
Microsoft Windows |
>tut1 tut1.cpp tut1.cpp 592 >dir tut1.cpp ... 07/26/2015 07:20 AM 592 tut1.cpp ... |
So far, so good. The reported Linux and Windows sizes are different because
the Linux tests used "\n"
line endings, while the Windows tests
used "\r\n"
line endings. The sizes reported may differ
from the above if changes have been made to tut1.cpp
.
Now try again, but give a path that doesn't exist:
Ubuntu Linux |
$ ./tut1 foo terminate called after throwing an instance of 'boost::filesystem::filesystem_error' what(): boost::filesystem::file_size: No such file or directory: "foo" Aborted (core dumped) |
Microsoft Windows |
>tut1 foo An exception is thrown; |
What happens?
There's no file named foo
in the current directory, so by default an
exception is thrown. See Error reporting to learn
about error reporting via error codes rather than exceptions.
Try this:
Ubuntu Linux |
$ ./tut1 . terminate called after throwing an instance of 'boost::filesystem::filesystem_error' what(): boost::filesystem::file_size: Operation not permitted: "." Aborted (core dumped) |
Microsoft Windows |
>tut1 . An exception is thrown; |
The current directory exists, but file_size()
works on regular
files, not directories, so again an exception is thrown.
We'll deal with those situations in tut2.cpp
.
Boost.Filesystem includes status query functions such as
exists
,
is_directory
, and
is_regular_file
. These return
bool
's, and will return true
if the condition
described by their name is met. Otherwise they return false
,
including when any element
of the path argument can't be found.
tut2.cpp uses several of the status query functions to cope with non-existent files and with different kinds of files:
#include <iostream> #include <boost/filesystem.hpp> using namespace std; using namespace boost::filesystem; int main(int argc, char* argv[]) { if (argc < 2) { cout << "Usage: tut2 path\n"; return 1; } path p(argv[1]); // avoid repeated path construction below if (exists(p)) // does path p actually exist? { if (is_regular_file(p)) // is path p a regular file? cout << p << " size is " << file_size(p) << '\n'; else if (is_directory(p)) // is path p a directory? cout << p << " is a directory\n"; else cout << p << " exists, but is not a regular file or directory\n"; } else cout << p << " does not exist\n"; return 0; } |
Give it a try:
Ubuntu Linux |
$ ./tut2 tut2.cpp "tut2.cpp" size is 997 $ ./tut2 foo "foo" does not exist $ ./tut2 . "." is a directory |
Microsoft Windows |
>tut2 tut2.cpp tut2.cpp size is 1039 >tut2 foo "foo" does not exist >tut2 . "." is a directory |
Although tut2 works OK in these tests, the output is less than satisfactory
for a directory. We'd typically like to see a list of the directory's contents. In tut3.cpp
we will see how to iterate over directories.
But first, let's try one more test:
Ubuntu Linux |
$ ls /home/jane/foo ls: cannot access /home/jane/foo: No such file or directory $ ./tut2 /home/jane/foo terminate called after throwing an instance of 'boost:: filesystem::filesystem_error>' what(): boost::filesystem::status: Permission denied: "/home/jane/foo" Aborted |
Microsoft Windows |
>dir e:\ The device is not ready. >tut2 e:\ An exception is thrown; |
On the Linux system, the test was being run from an account that did not have
permission to access /home/jane/foo
. On the Windows system,
e:
was a Compact Disc reader/writer that was not ready. End users
shouldn't have to interpret cryptic exceptions reports, so as we move on to tut3.cpp
we will increase the robustness of the code, too.
Boost.Filesystem's
directory_iterator
class is just what we need here. It follows the
general pattern of the standard library's istream_iterator
. Constructed from
a path, it iterates over the contents of the directory. A default constructed directory_iterator
acts as the end iterator.
The value type of directory_iterator
is
directory_entry
. A
directory_entry
object contains path
and file_status
information. A
directory_entry
object
can be used directly, but can also be passed to path
arguments in function calls.
The other need is increased robustness in the face of the many kinds of errors that can affect file system operations. We could do that at the level of each call to a Boost.Filesystem function (see Error reporting), but for simplicity tut3.cpp uses an overall try/catch block.
#include <iostream> #include <boost/filesystem.hpp> using std::cout; using namespace boost::filesystem; int main(int argc, char* argv[]) { if (argc < 2) { cout << "Usage: tut3 path\n"; return 1; } path p (argv[1]); try { if (exists(p)) { if (is_regular_file(p)) cout << p << " size is " << file_size(p) << '\n'; else if (is_directory(p)) { cout << p << " is a directory containing:\n"; for (directory_entry& x : directory_iterator(p)) cout << " " << x.path() << '\n'; } else cout << p << " exists, but is not a regular file or directory\n"; } else cout << p << " does not exist\n"; } catch (const filesystem_error& ex) { cout << ex.what() << '\n'; } return 0; } |
Give tut3
a try, passing it a path to a directory as a command line argument.
Here is a run on a checkout of the Boost Git develop branch, followed by a repeat
of the test cases that caused exceptions on Linux and Windows:
Ubuntu Linux |
$ ./tut3 ~/boost/develop "/home/beman/boost/develop" is a directory containing: "/home/beman/boost/develop/rst.css" "/home/beman/boost/develop/boost" "/home/beman/boost/develop/boost.png" "/home/beman/boost/develop/libs" "/home/beman/boost/develop/doc" "/home/beman/boost/develop/project-config.jam.2" "/home/beman/boost/develop/.gitmodules" "/home/beman/boost/develop/boostcpp.py" "/home/beman/boost/develop/.travis.yml" "/home/beman/boost/develop/.gitattributes" "/home/beman/boost/develop/index.htm" "/home/beman/boost/develop/index.html" "/home/beman/boost/develop/bjam" "/home/beman/boost/develop/project-config.jam.1" "/home/beman/boost/develop/LICENSE_1_0.txt" "/home/beman/boost/develop/.git" "/home/beman/boost/develop/tools" "/home/beman/boost/develop/stage" "/home/beman/boost/develop/boostcpp.jam" "/home/beman/boost/develop/Jamroot" "/home/beman/boost/develop/.gitignore" "/home/beman/boost/develop/INSTALL" "/home/beman/boost/develop/more" "/home/beman/boost/develop/bin.v2" "/home/beman/boost/develop/project-config.jam" "/home/beman/boost/develop/boost-build.jam" "/home/beman/boost/develop/bootstrap.bat" "/home/beman/boost/develop/bootstrap.sh" "/home/beman/boost/develop/status" "/home/beman/boost/develop/boost.css" |
Microsoft Windows |
>tut3 \boost\develop "\boost\develop" is a directory containing: "\boost\develop\.git" "\boost\develop\.gitattributes" "\boost\develop\.gitignore" "\boost\develop\.gitmodules" "\boost\develop\.travis.yml" "\boost\develop\bin.v2" "\boost\develop\boost" "\boost\develop\boost-build.jam" "\boost\develop\boost.css" "\boost\develop\boost.png" "\boost\develop\boostcpp.jam" "\boost\develop\boostcpp.py" "\boost\develop\bootstrap.bat" "\boost\develop\bootstrap.sh" "\boost\develop\doc" "\boost\develop\index.htm" "\boost\develop\index.html" "\boost\develop\INSTALL" "\boost\develop\Jamroot" "\boost\develop\libs" "\boost\develop\LICENSE_1_0.txt" "\boost\develop\more" "\boost\develop\project-config.jam" "\boost\develop\rst.css" "\boost\develop\stage" "\boost\develop\status" "\boost\develop\tools" >tut3 e:\ boost::filesystem::status: The device is not ready: "e:\" |
Not bad, but we can make further improvements:
The next sections show how those changes play out, so read on!
For directories, tut4.cpp builds a
std::vector
of all the entries and then sorts it before writing to
cout
.
#include <iostream> #include <vector> #include <algorithm> #include <boost/filesystem.hpp> using std::cout; using namespace boost::filesystem; int main(int argc, char* argv[]) { if (argc < 2) { cout << "Usage: tut4 path\n"; return 1; } path p (argv[1]); try { if (exists(p)) { if (is_regular_file(p)) cout << p << " size is " << file_size(p) << '\n'; else if (is_directory(p)) { cout << p << " is a directory containing:\n"; std::vector<path> v; for (auto&& x : directory_iterator(p)) v.push_back(x.path()); std::sort(v.begin(), v.end()); for (auto&& x : v) cout << " " << x.filename() << '\n'; } else cout << p << " exists, but is not a regular file or directory\n"; } else cout << p << " does not exist\n"; } catch (const filesystem_error& ex) { cout << ex.what() << '\n'; } return 0; } |
The only difference between tut3.cpp
and tut4.cpp
is
what happens for directories. We changed:
for (const directory_entry& x : directory_iterator(p)) cout << " " << x.path() << '\n';
to:
std::vector<path> v; for (auto&& x : directory_iterator(p)) v.push_back(x.path()); std::sort(v.begin(), v.end()); for (auto&& x : v) cout << " " << x.filename() << '\n';
filename()
is one of
several class path
decomposition functions. It extracts the
filename portion
from a path (i.e. "index.html"
from "/home/beman/boost/trunk/index.html"
). These decomposition functions are
more fully explored in the Path iterators, observers,
composition, decomposition and query portion of this tutorial.
The above was written as two lines of code for clarity. It could have been written more concisely as:
v.push_back(it->path().filename()); // we only care about the filename
Here is the output from a test of tut4.cpp
:
Ubuntu Linux |
$ ./tut4 v |
Microsoft Windows |
$ ./tut4 ~/boost/develop "/home/beman/boost/develop" is a directory containing: .git .gitattributes .gitignore .gitmodules .travis.yml INSTALL Jamroot LICENSE_1_0.txt bin.v2 boost boost-build.jam boost.css boost.png boostcpp.jam boostcpp.py bootstrap.bat bootstrap.sh doc index.htm index.html libs more project-config.jam project-config.jam.1 project-config.jam.2 rst.css stage status tools |
That completes the main portion of this tutorial. If you haven't already worked through the Class path sections of this tutorial, dig into them now. The Error reporting section may also be of interest, although it can be skipped unless you are deeply concerned about error handling issues.
Traditional C interfaces pass paths as const char*
arguments.
C++ interfaces may add const std::string&
overloads, but adding
overloads becomes untenable if wide characters, containers, and iterator ranges
need to be supported.
Passing paths as const path&
arguments is far simpler, yet far
more flexible because class path
itself is far more flexible:
path
supports multiple character types and encodings, including Unicode, to
ease internationalization.path
supports multiple source types, such as iterators for null terminated
sequences, iterator ranges, containers (including std::basic_string
),
and directory_entry
's,
so functions taking paths don't need to provide several overloads.path
supports both native and generic pathname formats, so programs can be
portable between operating systems yet use native formats where desirable.path
supplies a full set of iterators, observers, composition,
decomposition, and query functions, making pathname manipulations easy,
convenient, reliable, and portable.Here is how (1) and (2) work. Class path constructors, assignments, and appends have member templates for sources. For example, here are the constructors that take sources:
template <class Source> path(Source const& source);template <class InputIterator> path(InputIterator begin, InputIterator end);
Let's look at a little program that shows how comfortable class path
is with
both narrow and wide characters in C-style strings, C++ strings, and via C++
iterators:
#include <boost/filesystem/fstream.hpp> #include <string> #include <list> namespace fs = boost::filesystem; int main() { // \u263A is "Unicode WHITE SMILING FACE = have a nice day!" std::string narrow_string ("smile2"); std::wstring wide_string (L"smile2\u263A"); std::list<char> narrow_list; narrow_list.push_back('s'); narrow_list.push_back('m'); narrow_list.push_back('i'); narrow_list.push_back('l'); narrow_list.push_back('e'); narrow_list.push_back('3'); std::list<wchar_t> wide_list; wide_list.push_back(L's'); wide_list.push_back(L'm'); wide_list.push_back(L'i'); wide_list.push_back(L'l'); wide_list.push_back(L'e'); wide_list.push_back(L'3'); wide_list.push_back(L'\u263A'); { fs::ofstream f("smile"); } { fs::ofstream f(L"smile\u263A"); } { fs::ofstream f(narrow_string); } { fs::ofstream f(wide_string); } { fs::ofstream f(narrow_list); } { fs::ofstream f(wide_list); } narrow_list.pop_back(); narrow_list.push_back('4'); wide_list.pop_back(); wide_list.pop_back(); wide_list.push_back(L'4'); wide_list.push_back(L'\u263A'); { fs::ofstream f(fs::path(narrow_list.begin(), narrow_list.end())); } { fs::ofstream f(fs::path(wide_list.begin(), wide_list.end())); } return 0; } |
Testing tut5
:
Ubuntu Linux |
$ ./tut5 $ ls smile* smile smile☺ smile2 smile2☺ smile3 smile3☺ smile4 smile4☺ |
Microsoft Windows |
>tut5 >dir /b smile* smile smile2 smile2☺ smile3 smile3☺ smile4 smile4☺ smile☺ |
The exact appearance of the smiling face will depend on the font,
font size, and other settings for your command line window. The above tests were
run with out-of-the-box Ubuntu 14.04 and Windows 7, US Edition. If you don't get
the above results, take a look at the boost-root/libs/filesystem/example/test
directory with your system's GUI file browser, such as Linux Nautilus, Mac OS X
Finder, or Windows Explorer. These tend to be more comfortable with
international character sets than command line interpreters.
Class path
takes care of whatever character type or encoding
conversions are required by the particular operating system. Thus as
tut5
demonstrates, it's no problem to pass a wide character string to a
Boost.Filesystem operational function even if the underlying operating system
uses narrow characters, and visa versa. And the same applies to user supplied
functions that take const path&
arguments.
Class path
also provides path syntax that is portable across operating systems,
element iterators, and observer, composition, decomposition, and query
functions to manipulate the elements of a path. The next section of this
tutorial deals with path syntax.
Class path
deals with two different pathname
formats - generic format and native format. For POSIX-like
file systems, these formats are the same. But for users of Windows and
other non-POSIX file systems, the distinction is important. Even
programmers writing for POSIX-like systems need to understand the distinction if
they want their code to be portable to non-POSIX systems.
The generic format is the familiar /my_directory/my_file.txt
format used by POSIX-like
operating systems such as the Unix variants, Linux, and Mac OS X. Windows also
recognizes the generic format, and it is the basis for the familiar Internet URL
format. The directory
separator character is always one or more slash characters.
The native format is the format as defined by the particular
operating system. For Windows, either the slash or the backslash can be used as
the directory separator character, so /my_directory\my_file.txt
would work fine. Of course, if you write that in a C++ string literal, it
becomes "/my_directory\\my_file.txt"
.
If a drive specifier or a backslash appears in a pathname on a Windows system, it is always treated as the native format.
Class path
has observer functions that allow you to
obtain the string representation of a path object in either the native format
or the generic format. See the next section
for how that plays out.
The distinction between generic format and native format is important when communicating with native C-style API's and with users. Both tend to expect paths in the native format and may be confused by the generic format. The generic format is great, however, for writing portable programs that work regardless of operating system.
The next section covers class path
observers, composition,
decomposition, query, and iteration over the elements of a path.
The path_info.cpp
program is handy for learning how class path
iterators,
observers, composition, decomposition, and query functions work on your system.
It is one of the programs built by the build.sh
and build.bat
scripts:
#include <iostream> #include <boost/filesystem.hpp> using namespace std; using namespace boost::filesystem; const char * say_what(bool b) { return b ? "true" : "false"; } int main(int argc, char* argv[]) { if (argc < 2) { cout << "Usage: path_info path-element [path-element...]\n" "Composes a path via operator/= from one or more path-element arguments\n" "Example: path_info foo/bar baz\n" # ifdef BOOST_POSIX_API " would report info about the composed path foo/bar/baz\n"; # else // BOOST_WINDOWS_API " would report info about the composed path foo/bar\\baz\n"; # endif return 1; } path p; for (; argc > 1; --argc, ++argv) p /= argv[1]; // compose path p from the command line arguments cout << "\ncomposed path:\n"; cout << " operator<<()---------: " << p << "\n"; cout << " make_preferred()-----: " << p.make_preferred() << "\n"; cout << "\nelements:\n"; for (auto element : p) cout << " " << element << '\n'; cout << "\nobservers, native format:" << endl; # ifdef BOOST_POSIX_API cout << " native()-------------: " << p.native() << endl; cout << " c_str()--------------: " << p.c_str() << endl; # else // BOOST_WINDOWS_API wcout << L" native()-------------: " << p.native() << endl; wcout << L" c_str()--------------: " << p.c_str() << endl; # endif cout << " string()-------------: " << p.string() << endl; wcout << L" wstring()------------: " << p.wstring() << endl; cout << "\nobservers, generic format:\n"; cout << " generic_string()-----: " << p.generic_string() << endl; wcout << L" generic_wstring()----: " << p.generic_wstring() << endl; cout << "\ndecomposition:\n"; cout << " root_name()----------: " << p.root_name() << '\n'; cout << " root_directory()-----: " << p.root_directory() << '\n'; cout << " root_path()----------: " << p.root_path() << '\n'; cout << " relative_path()------: " << p.relative_path() << '\n'; cout << " parent_path()--------: " << p.parent_path() << '\n'; cout << " filename()-----------: " << p.filename() << '\n'; cout << " stem()---------------: " << p.stem() << '\n'; cout << " extension()----------: " << p.extension() << '\n'; cout << "\nquery:\n"; cout << " empty()--------------: " << say_what(p.empty()) << '\n'; cout << " is_absolute()--------: " << say_what(p.is_absolute()) << '\n'; cout << " has_root_name()------: " << say_what(p.has_root_name()) << '\n'; cout << " has_root_directory()-: " << say_what(p.has_root_directory()) << '\n'; cout << " has_root_path()------: " << say_what(p.has_root_path()) << '\n'; cout << " has_relative_path()--: " << say_what(p.has_relative_path()) << '\n'; cout << " has_parent_path()----: " << say_what(p.has_parent_path()) << '\n'; cout << " has_filename()-------: " << say_what(p.has_filename()) << '\n'; cout << " has_stem()-----------: " << say_what(p.has_stem()) << '\n'; cout << " has_extension()------: " << say_what(p.has_extension()) << '\n'; return 0; } |
Run the examples below on your system, and try some different path arguments as we go along. Here is the invocation we will talk about in detail:
Ubuntu Linux |
$ ./path_info /foo bar baa.txt composed path: operator<<()---------: "/foo/bar/baa.txt" make_preferred()-----: "/foo/bar/baa.txt" elements: "/" "foo" "bar" "baa.txt" observers, native format: native()-------------: /foo/bar/baa.txt c_str()--------------: /foo/bar/baa.txt string()-------------: /foo/bar/baa.txt wstring()------------: /foo/bar/baa.txt observers, generic format: generic_string()-----: /foo/bar/baa.txt generic_wstring()----: /foo/bar/baa.txt decomposition: root_name()----------: "" root_directory()-----: "/" root_path()----------: "/" relative_path()------: "foo/bar/baa.txt" parent_path()--------: "/foo/bar" filename()-----------: "baa.txt" stem()---------------: "baa" extension()----------: ".txt" query: empty()--------------: false is_absolute()--------: true has_root_name()------: false has_root_directory()-: true has_root_path()------: true has_relative_path()--: true has_parent_path()----: true has_filename()-------: true has_stem()-----------: true has_extension()------: true |
Microsoft Windows |
>path_info \foo bar baa.txt composed path: operator<<()---------: "\foo\bar\baa.txt" make_preferred()-----: "\foo\bar\baa.txt" elements: "/" "foo" "bar" "baa.txt" observers, native format: native()-------------: \foo\bar\baa.txt c_str()--------------: \foo\bar\baa.txt string()-------------: \foo\bar\baa.txt wstring()------------: \foo\bar\baa.txt observers, generic format: generic_string()-----: /foo/bar/baa.txt generic_wstring()----: /foo/bar/baa.txt decomposition: root_name()----------: "" root_directory()-----: "\" root_path()----------: "\" relative_path()------: "foo\bar\baa.txt" parent_path()--------: "\foo\bar" filename()-----------: "baa.txt" stem()---------------: "baa" extension()----------: ".txt" query: empty()--------------: false is_absolute()--------: false has_root_name()------: false has_root_directory()-: true has_root_path()------: true has_relative_path()--: true has_parent_path()----: true has_filename()-------: true has_stem()-----------: true has_extension()------: true |
We will go through the above code in detail to gain a better understanding of what is going on.
A common need is to compose a path from its constituent
directories. Class path
uses /
and /=
operators to
append elements. That's a reminder
that these operations append the operating system's preferred directory
separator if needed. The preferred
directory separator is a slash on POSIX-like systems, and a backslash on
Windows-like systems.
That's what this code does before displaying the resulting
path p
using the class path
stream inserter:
path p; for (; argc > 1; --argc, ++argv) p /= argv[1]; // compose path p from the command line arguments cout << "\ncomposed path:\n"; cout << " operator<<()---------: " << p << "\n"; cout << " make_preferred()-----: " << p.make_preferred() << "\n"; |
One abstraction for thinking about a path is as a sequence of elements, where
the elements are directory and file names. To support this abstraction, class
path
provides STL-like iterators and also begin()
and end()
functions.
Here is the code that produced the list of elements in the above output listing:
cout << "\nelements:\n"; for (auto element : p) cout << " " << element << '\n'; |
Let's look at class path observer functions:
cout << "\nobservers, native format:" << endl; # ifdef BOOST_POSIX_API cout << " native()-------------: " << p.native() << endl; cout << " c_str()--------------: " << p.c_str() << endl; # else // BOOST_WINDOWS_API wcout << L" native()-------------: " << p.native() << endl; wcout << L" c_str()--------------: " << p.c_str() << endl; # endif cout << " string()-------------: " << p.string() << endl; wcout << L" wstring()------------: " << p.wstring() << endl; cout << "\nobservers, generic format:\n"; cout << " generic_string()-----: " << p.generic_string() << endl; wcout << L" generic_wstring()----: " << p.generic_wstring() << endl; |
Native format observers should be used when interacting with the operating system or with users; that's what they expect.
Generic format observers should be used when the results need to be portable and uniform regardless of the operating system.
path
objects always hold pathnames in the native
format, but otherwise leave them unchanged from their source. The
preferred() function will convert to the
preferred form, if the native format has several forms. Thus on Windows, it will
convert slashes to backslashes.
Moving on to decomposition:
cout << "\ndecomposition:\n"; cout << " root_name()----------: " << p.root_name() << '\n'; cout << " root_directory()-----: " << p.root_directory() << '\n'; cout << " root_path()----------: " << p.root_path() << '\n'; cout << " relative_path()------: " << p.relative_path() << '\n'; cout << " parent_path()--------: " << p.parent_path() << '\n'; cout << " filename()-----------: " << p.filename() << '\n'; cout << " stem()---------------: " << p.stem() << '\n'; cout << " extension()----------: " << p.extension() << '\n'; |
And, finally, query functions:
cout << "\nquery:\n"; cout << " empty()--------------: " << say_what(p.empty()) << '\n'; cout << " is_absolute()--------: " << say_what(p.is_absolute()) << '\n'; cout << " has_root_name()------: " << say_what(p.has_root_name()) << '\n'; cout << " has_root_directory()-: " << say_what(p.has_root_directory()) << '\n'; cout << " has_root_path()------: " << say_what(p.has_root_path()) << '\n'; cout << " has_relative_path()--: " << say_what(p.has_relative_path()) << '\n'; cout << " has_parent_path()----: " << say_what(p.has_parent_path()) << '\n'; cout << " has_filename()-------: " << say_what(p.has_filename()) << '\n'; cout << " has_stem()-----------: " << say_what(p.has_stem()) << '\n'; cout << " has_extension()------: " << say_what(p.has_extension()) << '\n'; |
These are pretty self-evident, but do note the difference in the
result of is_absolute()
between Linux and Windows. Because there is
no root name (i.e. drive specifier or network name), a lone slash (or backslash)
is a relative path on Windows but an absolute path on POSIX-like operating
systems.
The Boost.Filesystem file_size
function, like many of the
operational functions, has two overloads:
uintmax_t file_size(const path& p); uintmax_t file_size(const path& p, system::error_code& ec);
The only significant difference between the two is how they report errors.
The
first signature will throw exceptions to report errors. A
filesystem_error
exception will be thrown
on an
operational error. filesystem_error
is derived from std::runtime_error
.
It has a
member function to obtain the
error_code
reported by the source
of the error. It also has member functions to obtain the path or paths that caused
the error.
Motivation for the second signature: Throwing exceptions on errors was the entire error reporting story for the earliest versions of Boost.Filesystem, and indeed throwing exceptions on errors works very well for many applications. But user reports trickled in that some code became so littered with try and catch blocks as to be unreadable and unmaintainable. In some applications I/O errors aren't exceptional, and that's the use case for the second signature.
Functions with a system::error_code&
argument set that
argument to report operational error status, and so do not throw exceptions when I/O
related errors occur. For a full explanation, see
Error reporting in the reference
documentation.
© Copyright Beman Dawes 2010, 2015
Distributed under the Boost Software License, Version 1.0. See www.boost.org/LICENSE_1_0.txt
Revised 07 August 2017