<a href="#Preliminaries">Preliminaries</a><br>
<a href="#Reporting-size">Reporting the size of a file - (tut1.cpp)</a><br>
<a href="#Using-status-queries">Using status queries to determine file existence and type - (tut2.cpp)</a><br>
- <a href="#Directory-iteration">Directory iteration plus catching
+ <a href="#Directory-iteration">Directory iteration plus catching
exceptions - (tut3.cpp)</a><br>
<a href="#Using-path-decomposition">Using path decomposition, plus sorting results - (tut4.cpp)</a><br>
- <a href="#Class-path-Constructors">Class path: Constructors, including
+ <a href="#Class-path-Constructors">Class path: Constructors, including
Unicode - (tut5.cpp)</a><br>
<a href="#Class-path-formats">Class path: Generic format vs. Native format</a><br>
<a href="#Class path-iterators-etc">Class path: Iterators, observers, composition, decomposition, and query - (path_info.cpp)</a><br>
</p>
<h2><a name="Introduction">Introduction</a></h2>
-<p>This tutorial develops a little command line program to list information
-about files and directories - essentially a much simplified version of the POSIX <code>ls</code> or Windows <code>dir</code>
-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
+<p>This tutorial develops a little command line program to list information
+about files and directories - essentially a much simplified version of the POSIX <code>ls</code> or Windows <code>dir</code>
+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.</p>
-<p>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
+<p>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.</p>
<h2><a name="Preliminaries">Preliminaries</a></h2>
<p>Install the Boost distribution if you haven't already done so. See the
-<a href="http://www.boost.org/more/getting_started/index.html">Boost Getting
+<a href="http://www.boost.org/more/getting_started/index.html">Boost Getting
Started</a> docs.</p>
-<p>This tutorial assumes you are going to compile and test the examples using
+<p>This tutorial assumes you are going to compile and test the examples using
the provided scripts. That's highly recommended.</p>
<blockquote>
-<p><b>If you are planning to compile and test the examples but not use the
-scripts, make sure your build setup knows where to
+<p><b>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.</b></p>
</blockquote>
</td>
</tr>
</table>
-
+
<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" bgcolor="#D7EEFF">
</tr>
</table>
-<p>If the <code>tut1</code> command outputs "<code>Usage: tut1 path</code>", all
+<p>If the <code>tut1</code> command outputs "<code>Usage: tut1 path</code>", all
is well. A set of tutorial example programs has been copied (by <code>setup</code>) to
-<i><b><code>boost-root</code></b></i><code>/libs/filesystem/example/test</code>
-and then built. You are encouraged to modify and experiment with them as the
-tutorial progresses. Just invoke the <code>build</code> script again to rebuild,
+<i><b><code>boost-root</code></b></i><code>/libs/filesystem/example/test</code>
+and then built. You are encouraged to modify and experiment with them as the
+tutorial progresses. Just invoke the <code>build</code> script again to rebuild,
or invoke <code>b2</code> directly.</p>
<p>If something didn't work right, here are some troubleshooting suggestions:</p>
<ul>
- <li>If the <code>b2</code> program executable isn't being found, check your path environmental variable
+ <li>If the <code>b2</code> program executable isn't being found, check your path environmental variable
or see
- <a href="http://www.boost.org/more/getting_started/windows.html">Boost
+ <a href="http://www.boost.org/more/getting_started/windows.html">Boost
Getting Started</a>.<br>
</li>
- <li>Look at <code>b2.log</code> to try to spot an indication of the
+ <li>Look at <code>b2.log</code> to try to spot an indication of the
problem.</li>
</ul>
<h2><a name="Reporting-size">Reporting the size of a file</a> - (<a href="../example/tut1.cpp">tut1.cpp</a>)</h2>
-<p>Let's get started. Our first example program, <a href="../example/tut1.cpp">tut1.cpp</a>,
+<p>Let's get started. Our first example program, <a href="../example/tut1.cpp">tut1.cpp</a>,
reports the size of a file:</p>
<table border="1" cellpadding="3" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" bgcolor="#D7EEFF">
</tr>
</table>
-<p>The Boost.Filesystem <code><a href="reference.html#file_size">file_size</a></code>
-function returns a <code>uintmax_t</code>
-containing the size of the file named by the argument. The declaration looks
+<p>The Boost.Filesystem <code><a href="reference.html#file_size">file_size</a></code>
+function returns a <code>uintmax_t</code>
+containing the size of the file named by the argument. The declaration looks
like this:</p>
<blockquote>
<pre><code>uintmax_t file_size(const path& p);</code> </pre>
</blockquote>
<p>For now, all you need to know is that <code>class path</code> has constructors that take
-<code>const char *</code> and other string types. (If you can't wait to
-find out more, skip ahead to the <a href="#Class-path-Constructors">class path</a> section of
+<code>const char *</code> and other string types. (If you can't wait to
+find out more, skip ahead to the <a href="#Class-path-Constructors">class path</a> section of
the tutorial.)</p>
-<p>Please take a minute to try out <code>tut1</code> on your system, using a
-file that is known to exist, such as <code>tut1.cpp</code>. Here is what the
+<p>Please take a minute to try out <code>tut1</code> on your system, using a
+file that is known to exist, such as <code>tut1.cpp</code>. Here is what the
results look like on two different operating systems:</p>
<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" bgcolor="#D7EEFF">
</td>
</tr>
</table>
-
+
<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" bgcolor="#D7EEFF">
<td align="center"><i><b>Microsoft Windows</b></i></td>
</tr>
<tr>
-
+
<td valign="top">
<pre>>tut1 tut1.cpp
tut1.cpp 592
</tr>
</table>
-<p>So far, so good. The reported Linux and Windows sizes are different because
-the Linux tests used <code>"\n"</code> line endings, while the Windows tests
-used <code>"\r\n"</code> line endings. The sizes reported may differ
+<p>So far, so good. The reported Linux and Windows sizes are different because
+the Linux tests used <code>"\n"</code> line endings, while the Windows tests
+used <code>"\r\n"</code> line endings. The sizes reported may differ
from the above if changes have been made to <code>tut1.cpp</code>.</p>
<p>Now try again, but give a path that doesn't exist:</p>
<td valign="top">
<pre>>tut1 foo</pre>
<p><b><i>An exception is thrown;<br>
- the exact form of the response depends on
+ the exact form of the response depends on
Windows system options.</i></b></td>
</tr>
</table>
<p>What happens?
- There's no file named <code>foo</code> in the current directory, so by default an
-exception is thrown. See <a href="#Error-reporting">Error reporting</a> to learn
+ There's no file named <code>foo</code> in the current directory, so by default an
+exception is thrown. See <a href="#Error-reporting">Error reporting</a> to learn
about error reporting via error codes rather than exceptions.</p>
<p>Try this:</p>
</td>
</tr>
</table>
-
+
<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" bgcolor="#D7EEFF">
</tr>
</table>
- <p>The current directory exists, but <code>file_size()</code> works on regular
+ <p>The current directory exists, but <code>file_size()</code> works on regular
files, not directories, so again an exception is thrown.</p>
<p>We'll deal with those situations in <code>tut2.cpp</code>.</p>
<a href="reference.html#exists-path">exists</a></code>,
<code><a href="reference.html#is_directory-path">is_directory</a></code>, and <code>
<a href="reference.html#is_regular_file-path">is_regular_file</a></code>. These return
-<code>bool</code>'s, and will return <code>true</code> if the condition
-described by their name is met. Otherwise they return <code>false</code>,
-including when any element
+<code>bool</code>'s, and will return <code>true</code> if the condition
+described by their name is met. Otherwise they return <code>false</code>,
+including when any element
of the path argument can't be found.</p>
-<p><a href="../example/tut2.cpp">tut2.cpp</a> uses several of the status query functions to cope with non-existent
+<p><a href="../example/tut2.cpp">tut2.cpp</a> uses several of the status query functions to cope with non-existent
files and with different kinds of files:</p>
<table border="1" cellpadding="3" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" bgcolor="#D7EEFF">
</tr>
</table>
-<p>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 <code>tut3.cpp</code>
+<p>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 <code>tut3.cpp</code>
we will see how to iterate over directories.</p>
<p>But first, let's try one more test:</p>
</td>
</tr>
</table>
-
+
<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" bgcolor="#D7EEFF">
>tut2 e:\</pre>
<p dir="ltr"><b><i>An exception is thrown;<br>
- the exact form of the response depends on
+ the exact form of the response depends on
Windows system options.</i></b></td>
</tr>
</table>
-<p>On the Linux system, the test was being run from an account that did not have
+<p>On the Linux system, the test was being run from an account that did not have
permission to access <code>/home/jane/foo</code>. On the Windows system, <code>
-e:</code> 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 <code>tut3.cpp</code>
+e:</code> 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 <code>tut3.cpp</code>
we will increase the robustness of the code, too.</p>
-<h2><a name="Directory-iteration">Directory iteration</a> plus catching
+<h2><a name="Directory-iteration">Directory iteration</a> plus catching
exceptions - (<a href="../example/tut3.cpp">tut3.cpp</a>)</h2>
<p>Boost.Filesystem's <code><a href="reference.html#directory_iterator">
-directory_iterator</a></code> class is just what we need here. It follows the
-general pattern of the standard library's <code>istream_iterator</code>. Constructed from
-a path, it iterates over the contents of the directory. A default constructed <code>directory_iterator</code>
+directory_iterator</a></code> class is just what we need here. It follows the
+general pattern of the standard library's <code>istream_iterator</code>. Constructed from
+a path, it iterates over the contents of the directory. A default constructed <code>directory_iterator</code>
acts as the end iterator.</p>
<p>The value type of <code>directory_iterator</code> is <code>
<a href="reference.html#directory_entry">directory_entry</a></code>. A <code>
-directory_entry</code> object contains <code>path</code> and <code><a href="reference.html#file_status">file_status</a></code>
+directory_entry</code> object contains <code>path</code> and <code><a href="reference.html#file_status">file_status</a></code>
information. A <code>
-directory_entry</code> object
+directory_entry</code> object
can be used directly, but can also be passed to <code>path</code> arguments in function calls.</p>
-<p>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 <a href="#Error-reporting">Error
-reporting</a>), but for simplicity <a href="../example/tut3.cpp">tut3.cpp</a>
+<p>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 <a href="#Error-reporting">Error
+reporting</a>), but for simplicity <a href="../example/tut3.cpp">tut3.cpp</a>
uses an overall try/catch block.</p>
<table border="1" cellpadding="3" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" bgcolor="#D7EEFF">
cout << p << " is a directory containing:\n";
for (directory_entry& x : directory_iterator(p))
- cout << " " << x.path() << '\n';
+ cout << " " << x.path() << '\n';
}
else
cout << p << " exists, but is not a regular file or directory\n";
</tr>
</table>
-<p>Give <code>tut3</code> 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
+<p>Give <code>tut3</code> 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:</p>
<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" bgcolor="#D7EEFF">
</td>
</tr>
</table>
-
+
<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" bgcolor="#D7EEFF">
<td align="center"><i><b>Microsoft Windows</b></i></td>
</tr>
<tr>
-
+
<td valign="top">
<pre>>tut3 \boost\develop
"\boost\develop" is a directory containing:
<p>Not bad, but we can make further improvements:</p>
<ul>
- <li>The listing would be much easier to read if only the filename was
+ <li>The listing would be much easier to read if only the filename was
displayed, rather than the full path.<br>
</li>
- <li>The Linux listing isn't sorted. That's because the ordering of
- directory iteration is unspecified. Ordering depends on the underlying
- operating system API and file system specifics. So we need to sort the
+ <li>The Linux listing isn't sorted. That's because the ordering of
+ directory iteration is unspecified. Ordering depends on the underlying
+ operating system API and file system specifics. So we need to sort the
results ourselves. </li>
</ul>
std::vector<path> v;
for (auto&& x : directory_iterator(p))
- v.push_back(x.path());
+ v.push_back(x.path());
- std::sort(v.begin(), v.end());
+ std::sort(v.begin(), v.end());
for (auto&& x : v)
cout << " " << x.filename() << '\n';
</tr>
</table>
- <p>The only difference between <code>tut3.cpp</code> and <code>tut4.cpp</code> is
+ <p>The only difference between <code>tut3.cpp</code> and <code>tut4.cpp</code> is
what happens for directories. We changed:</p>
<blockquote>
<pre>for (const directory_entry& x : directory_iterator(p))
<pre>std::vector<path> v;
for (auto&& x : directory_iterator(p))
- v.push_back(x.path());
+ v.push_back(x.path());
-std::sort(v.begin(), v.end());
+std::sort(v.begin(), v.end());
for (auto&& x : v)
cout << " " << x.filename() << '\n';
</pre>
</blockquote>
<p> <code>
- <a href="reference.html#path-filename">filename()</a></code> is one of
- several class <code>path</code> decomposition functions. It extracts the
- filename portion
- from a path (<font face="Courier New">i.e. </font><code>"index.html"</code><font face="Courier New">
- from </font><code>"/home/beman/boost/trunk/index.html"</code>). These decomposition functions are
- more fully explored in the <a href="#Class path-iterators-etc">Path iterators, observers,
+ <a href="reference.html#path-filename">filename()</a></code> is one of
+ several class <code>path</code> decomposition functions. It extracts the
+ filename portion
+ from a path (<font face="Courier New">i.e. </font><code>"index.html"</code><font face="Courier New">
+ from </font><code>"/home/beman/boost/trunk/index.html"</code>). These decomposition functions are
+ more fully explored in the <a href="#Class path-iterators-etc">Path iterators, observers,
composition, decomposition and query</a> portion of this tutorial.</p>
- <p>The above was written as two lines of code for clarity. It could have
+ <p>The above was written as two lines of code for clarity. It could have
been written more concisely as:</p>
<blockquote>
<pre>v.push_back(it->path().filename()); // we only care about the filename</pre>
</tr>
</table>
- <p>That completes the main portion of this tutorial. If you haven't already
- worked through the <a href="#Class-path-Constructors">Class path</a> sections of this tutorial, dig into them now.
- The <a href="#Error-reporting">Error reporting</a> section may also be of
- interest, although it can be skipped unless you are deeply concerned about
+ <p>That completes the main portion of this tutorial. If you haven't already
+ worked through the <a href="#Class-path-Constructors">Class path</a> sections of this tutorial, dig into them now.
+ The <a href="#Error-reporting">Error reporting</a> section may also be of
+ interest, although it can be skipped unless you are deeply concerned about
error handling issues.</p>
-<h2><a name="Class-path-Constructors">Class path: Constructors</a>,
+<h2><a name="Class-path-Constructors">Class path: Constructors</a>,
including Unicode - (<a href="../example/tut5.cpp">tut5.cpp</a>)</h2>
-<p>Traditional C interfaces pass paths as <code>const char*</code> arguments.
-C++ interfaces may add <code>const std::string&</code> overloads, but adding
-overloads becomes untenable if wide characters, containers, and iterator ranges
+<p>Traditional C interfaces pass paths as <code>const char*</code> arguments.
+C++ interfaces may add <code>const std::string&</code> overloads, but adding
+overloads becomes untenable if wide characters, containers, and iterator ranges
need to be supported.</p>
-<p>Passing paths as <code>const path&</code> arguments is far simpler, yet far
+<p>Passing paths as <code>const path&</code> arguments is far simpler, yet far
more flexible because class <code>path</code> itself is far more flexible:</p>
<ol>
- <li>Class <code>path</code> supports multiple character types and encodings, including Unicode, to
+ <li>Class <code>path</code> supports multiple character types and encodings, including Unicode, to
ease internationalization.</li>
- <li>Class <code>path</code> supports multiple source types, such as iterators for null terminated
- sequences, iterator ranges, containers (including <code>std::basic_string</code>),
- and <code><a href="reference.html#Class-directory_entry">directory_entry</a></code>'s,
+ <li>Class <code>path</code> supports multiple source types, such as iterators for null terminated
+ sequences, iterator ranges, containers (including <code>std::basic_string</code>),
+ and <code><a href="reference.html#Class-directory_entry">directory_entry</a></code>'s,
so functions taking paths don't need to provide several overloads.</li>
- <li>Class <code>path</code> supports both native and generic pathname formats, so programs can be
+ <li>Class <code>path</code> supports both native and generic pathname formats, so programs can be
portable between operating systems yet use native formats where desirable.</li>
- <li>Class <code>path</code> supplies a full set of iterators, observers, composition,
- decomposition, and query functions, making pathname manipulations easy,
+ <li>Class <code>path</code> supplies a full set of iterators, observers, composition,
+ decomposition, and query functions, making pathname manipulations easy,
convenient, reliable, and portable.</li>
</ol>
-<p>Here is how (1) and (2) work. Class path constructors,
-assignments, and appends have member templates for sources. For example, here
+<p>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:</p>
<blockquote>
<pre>template <class InputIterator>
path(InputIterator begin, InputIterator end);</pre>
</blockquote>
-<p>Let's look at a little program that shows how comfortable class <code>path</code> is with
-both narrow and wide characters in C-style strings, C++ strings, and via C++
+<p>Let's look at a little program that shows how comfortable class <code>path</code> is with
+both narrow and wide characters in C-style strings, C++ strings, and via C++
iterators:</p>
<table border="1" cellpadding="3" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" bgcolor="#D7EEFF">
</tr>
</table>
-<p>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 <code><i>boost-root</i>/libs/filesystem/example/test</code>
-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
+<p>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 <code><i>boost-root</i>/libs/filesystem/example/test</code>
+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.</p>
- <p>Class <code>path</code> takes care of whatever character type or encoding
+ <p>Class <code>path</code> takes care of whatever character type or encoding
conversions are required by the particular operating system. Thus as <code>
- tut5</code> 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
+ tut5</code> 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 <code>const path&</code> arguments.</p>
- <p>Class <code>path</code> 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
+ <p>Class <code>path</code> 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.</p>
<h2><a name="Class-path-formats">Class path: Generic format vs. Native format</a></h2>
-<p>Class <code>path</code> 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
+<p>Class <code>path</code> 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.</p>
-<p>The <b>generic format</b> is the familiar <code>/my_directory/my_file.txt</code> 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
+<p>The <b>generic format</b> is the familiar <code>/my_directory/my_file.txt</code> 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.</p>
-<p>The <b>native format</b> 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 <code>/my_directory\my_file.txt</code>
-would work fine. Of course, if you write that in a C++ string literal, it
+<p>The <b>native format</b> 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 <code>/my_directory\my_file.txt</code>
+would work fine. Of course, if you write that in a C++ string literal, it
becomes <code>"/my_directory\\my_file.txt"</code>.</p>
-<p>If a drive specifier or a backslash appears
+<p>If a drive specifier or a backslash appears
in a pathname on a Windows system, it is always treated as the native format.</p>
-<p>Class <code>path</code> 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 <a href="#Class path-iterators-etc">next section</a>
+<p>Class <code>path</code> 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 <a href="#Class path-iterators-etc">next section</a>
for how that plays out.</p>
- <p>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
+ <p>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.</p>
- <p>The next section covers class <code>path</code> observers, composition,
+ <p>The next section covers class <code>path</code> observers, composition,
decomposition, query, and iteration over the elements of a path.</p>
-<h2><a name="Class path-iterators-etc">Class path: Iterators, observers, composition, decomposition, and query</a>
+<h2><a name="Class path-iterators-etc">Class path: Iterators, observers, composition, decomposition, and query</a>
- (<a href="../example/path_info.cpp">path_info.cpp</a>)</h2>
-<p>The <code><a href="../example/path_info.cpp">path_info.cpp</a></code> program is handy for learning how class <code>path</code>
-iterators,
-observers, composition, decomposition, and query functions work on your system.
-It is one of the programs built by the <code>build.sh</code> and <code>build.bat</code>
+<p>The <code><a href="../example/path_info.cpp">path_info.cpp</a></code> program is handy for learning how class <code>path</code>
+iterators,
+observers, composition, decomposition, and query functions work on your system.
+It is one of the programs built by the <code>build.sh</code> and <code>build.bat</code>
scripts:</p>
</table>
-<p>Run the examples below on your system, and try some different path arguments
+<p>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:</p>
<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" bgcolor="#D7EEFF">
</td>
</tr>
</table>
-
+
<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" bgcolor="#D7EEFF">
</tr>
</table>
-<p>We will go through the above code in detail to gain a better
+<p>We will go through the above code in detail to gain a better
understanding of what is going on.</p>
-<p dir="ltr">A common need is to compose a path from its constituent
-directories. Class <code>path</code> uses <code>/</code> and <code>/=</code> 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
+<p dir="ltr">A common need is to compose a path from its constituent
+directories. Class <code>path</code> uses <code>/</code> and <code>/=</code> 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.</p>
<p dir="ltr">That's what this code does before displaying the resulting <code>
</table>
-<p>One abstraction for thinking about a path is as a sequence of elements, where
+<p>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
-<code>path</code> provides STL-like iterators and also <code>begin()</code>
+<code>path</code> provides STL-like iterators and also <code>begin()</code>
and <code>end()</code> functions.</p>
<p>Here is the code that produced the list of elements in the above output listing:</p>
</table>
-<p>Native format observers should be used when interacting with the
+<p>Native format observers should be used when interacting with the
operating system or with users; that's what they expect.</p>
-<p>Generic format observers should be used when the results need to be
+<p>Generic format observers should be used when the results need to be
portable and uniform regardless of the operating system.</p>
-<p><code>path</code> objects always hold pathnames in the native
+<p><code>path</code> objects always hold pathnames in the native
format, but otherwise leave them unchanged from their source. The
-<a href="reference.html#preferred">preferred()</a> function will convert to the
-preferred form, if the native format has several forms. Thus on Windows, it will
+<a href="reference.html#preferred">preferred()</a> function will convert to the
+preferred form, if the native format has several forms. Thus on Windows, it will
convert slashes to backslashes.</p>
<p>Moving on to decomposition:</p>
</table>
-<p>These are pretty self-evident, but do note the difference in the
-result of <code>is_absolute()</code> 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
+<p>These are pretty self-evident, but do note the difference in the
+result of <code>is_absolute()</code> 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. </p>
<h2><a name="Error-reporting">Error reporting</a></h2>
- <p>The Boost.Filesystem <code>file_size</code> function, like many of the
+ <p>The Boost.Filesystem <code>file_size</code> function, like many of the
operational functions, has two overloads:</p>
<blockquote>
uintmax_t <a name="file_size2">file_size</a>(const path& p, system::error_code& ec);</pre>
</blockquote>
<p>The only significant difference between the two is how they report errors.</p>
-<p>The
+<p>The
first signature will throw exceptions to report errors. A <code>
-<a href="reference.html#Class-filesystem_error">filesystem_error</a></code> exception will be thrown
-on an
- operational error. <code>filesystem_error</code> is derived from <code>std::runtime_error</code>.
-It has a
+<a href="reference.html#Class-filesystem_error">filesystem_error</a></code> exception will be thrown
+on an
+ operational error. <code>filesystem_error</code> is derived from <code>std::runtime_error</code>.
+It has a
member function to obtain the <code>
-<a href="../../system/doc/reference.html#Class-error_code">error_code</a></code> reported by the source
- of the error. It also has member functions to obtain the path or paths that caused
+<a href="../../system/doc/reference.html#Class-error_code">error_code</a></code> reported by the source
+ of the error. It also has member functions to obtain the path or paths that caused
the error.</p>
<blockquote>
- <p><b>Motivation for the second signature:</b> 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
+ <p><b>Motivation for the second signature:</b> 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.</p>
</blockquote>
- <p>Functions with a <code>system::error_code&</code> argument set that
- argument to report operational error status, and so do not throw exceptions when I/O
+ <p>Functions with a <code>system::error_code&</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
- <a href="reference.html#Error-reporting">Error reporting</a> in the reference
+ <a href="reference.html#Error-reporting">Error reporting</a> in the reference
documentation. </p>
<hr>
</body>
-</html>
\ No newline at end of file
+</html>
projects / platform / upstream / boost.git / blobdiff