Subject: [Boost-commit] svn:boost r58641 - sandbox/filesystem-v3/libs/filesystem/doc
From: bdawes_at_[hidden]
Date: 2010-01-02 10:05:57
Author: bemandawes
Date: 2010-01-02 10:05:56 EST (Sat, 02 Jan 2010)
New Revision: 58641
URL: http://svn.boost.org/trac/boost/changeset/58641
Log:
Initial commit
Added:
sandbox/filesystem-v3/libs/filesystem/doc/do_list.html (contents, props changed)
sandbox/filesystem-v3/libs/filesystem/doc/tut1_crash.jpg (contents, props changed)
sandbox/filesystem-v3/libs/filesystem/doc/tutorial.html (contents, props changed)
Added: sandbox/filesystem-v3/libs/filesystem/doc/do_list.html
==============================================================================
--- (empty file)
+++ sandbox/filesystem-v3/libs/filesystem/doc/do_list.html 2010-01-02 10:05:56 EST (Sat, 02 Jan 2010)
@@ -0,0 +1,20 @@
+<html>
+
+<head>
+<meta http-equiv="Content-Language" content="en-us">
+<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
+<meta name="ProgId" content="FrontPage.Editor.Document">
+<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
+<title>Do List</title>
+</head>
+
+<body>
+
+<h1>Boost.Filesystem Do List</h1>
+<ul>
+ <li>Rename path::is_complete() -> is_absolute().</li>
+</ul>
+
+</body>
+
+</html>
Added: sandbox/filesystem-v3/libs/filesystem/doc/tut1_crash.jpg
==============================================================================
Binary file. No diff available.
Added: sandbox/filesystem-v3/libs/filesystem/doc/tutorial.html
==============================================================================
--- (empty file)
+++ sandbox/filesystem-v3/libs/filesystem/doc/tutorial.html 2010-01-02 10:05:56 EST (Sat, 02 Jan 2010)
@@ -0,0 +1,457 @@
+<html>
+
+<head>
+<meta http-equiv="Content-Language" content="en-us">
+<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
+<meta name="ProgId" content="FrontPage.Editor.Document">
+<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
+<title>Filesystem Tutorial</title>
+<style type="text/css">
+ body { font-family: sans-serif; margin: 1em; }
+ p, td, li, blockquote { font-size: 10pt; }
+ pre { font-size: 9pt; }
+</style>
+</head>
+
+<body>
+
+<table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="742">
+ <tr>
+ <td width="277">
+<a href="../../../index.htm">
+<img src="../../../boost.png" alt="boost.png (6897 bytes)" align="middle" width="277" height="86" border="0"></a></td>
+ <td width="442" align="middle">
+ <font size="7">Filesystem Tutorial</font>
+ </td>
+ </tr>
+</table>
+
+<table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" bgcolor="#D7EEFF" width="100%">
+ <tr>
+ <td>Boost Home
+ Library Home
+ <a href="reference.html">
+ Reference</a>
+ FAQ</td>
+ </tr>
+</table>
+
+<h3>Preliminaries</h3>
+
+<p>Install the Boost distribution if you haven't already done so. Since
+Boost.Filesystem is a compiled library, you will need to do a library build if
+this hasn't been done already.</p>
+
+<h2>Basics</h2>
+
+<p>Let's look at the <code>rename</code> function to get an idea of some of the
+differences in approach taken by Boost.Filesystem compared to legacy C language
+interfaces.</p>
+
+<table align="center" border="1" cellpadding="3" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" bgcolor="#D7EEFF" width="90%">
+ <tr>
+ <td style="font-size: 10pt">
+ <b>C++ Standard library <code>rename</code> function from <cstdio></b><blockquote style="font-size: 10pt">
+ <pre>int rename(const char *old, const char *new);</pre>
+ </blockquote>
+ <p><b>Boost Filesystem library <code>rename</code> function from
+ <filesystem.hpp></b></p>
+ <blockquote style="font-size: 10pt">
+ <pre>void <a name="rename">rename</a>(const path& old_p, const path& new_p);
+void <a name="rename">rename</a>(const path& old_p, const path& new_p, system::error_code& ec);</pre>
+ </blockquote>
+ </td>
+ </tr>
+</table>
+
+<h3>Class path</h3>
+
+<p>Rather than trafficking in <code>const char*</code>'s, Boost.Filesystem
+operational functions traffics in objects of class path,
+which are a lot more flexible. For example, class path has a converting constructor
+template:</p>
+
+<blockquote>
+ <pre>template <class Source>
+ path(Source const& source);</pre>
+</blockquote>
+<p>and this allows <code>const path&</code> arguments to be called with a
+variety of object types, such as:</p>
+<ul>
+ <li style="font-size: 10pt">An iterator, such as a pointer, for a null terminated byte-string.
+ Value type can be <code>char</code>, <code>
+ wchar_t</code>, <code>char16_t</code>, or <code>char32_t</code>.</li>
+ <li>A container with a value type of <code>char</code>, <code>
+ wchar_t</code>, <code>char16_t</code>, or <code>char32_t</code>.</li>
+ <li>A C-array with a value type of <code>char</code>, <code>
+ wchar_t</code>, <code>char16_t</code>, or <code>char32_t</code>.</li>
+ <li>A <code>boost::filesystem::directory_entry</code>.</li>
+</ul>
+<p>In addition to handling a variety of types, class path function templates
+also handle conversion between the argument's encoding and the internal encoding
+required for communication with the operating system. Thus 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. </p>
+<p>Say we have a file named <code><font size="4">valentine</font></code> we'd
+like to rename <code><font size="4">♥valentine</font></code>. Here's the code:</p>
+<blockquote>
+ <pre>boost::filesystem::rename("valentine", L"\u2665valentine");</pre>
+</blockquote>
+
+ <p>Class <code>path</code> will take care of whatever character type or
+ encoding conversions are required by the particular operating system. It 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. <span style="background-color: #FFFF00">
+ More on class </span><code><span style="background-color: #FFFF00">path</span></code><span style="background-color: #FFFF00">
+ later in this tutorial.</span></p>
+
+ <h3>Error reporting</h3>
+
+ <p>Legacy C interfaces like the original <code>rename</code> function report
+ errors via an error code, typically obtained via <code>errno</code>. The
+ preferred C++ practice is to throw an exception to report an error, and that's
+ how the first of the two Boost.Filesystem <code>rename</code> functions
+ reports errors. A <code>filesystem_error</code> exception will be thrown on an
+ operational error. It's derived from <code>std::runtime_error</code> and has a
+ member function to obtain the <code>error_code</code> reported by the source
+ of the error. It also has member functions to obtain the path[s] that caused
+ the error.</p>
+
+ <p>That was the entire error reporting story for the earliest versions of
+ Boost.Filesystem, and indeed throwing exceptions on errors worked very well in
+ many applications. But some user reports trickled in of code that became so
+ littered by try and catch blocks as to be unreadable and unmaintainable. In
+ some applications I/O errors aren't exceptional, and that's why most
+ Boost.Filesystem operational functions come in two flavors.</p>
+
+ <p>Functions without a <code>system::error_code&</code>
+argument throw exceptions to report operational errors. These functions should
+ be your default choice, unless you really do need to deal with errors via hand
+ coded error tests.</p>
+
+ <p>Functions with a <code>system::error_code&</code>
+argument report operational error status by setting the <code>ec</code> argument, and
+do not throw exceptions when I/O errors occur.
+ <span style="background-color: #FFFF00">More on that later in the tutorial.</span></p>
+
+<h2>File size - tut1.cpp</h2>
+
+<p>Let's develop 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. Source code for each version is available, and you are
+encouraged to compile, test, and experiment with it.</p>
+
+<p>To conserve space, we won't show all the boilerplate code here, but the
+source code does include it. </p>
+
+<p>Let's get started.</p>
+
+<table align="center" border="1" cellpadding="3" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" bgcolor="#D7EEFF" width="90%">
+ <tr>
+ <td style="font-size: 10pt">
+ <pre>tut1.cpp</pre>
+ <blockquote>
+ <pre>int main(int argc, char* argv[])
+{
+
+ std::cout << argv[1] << ": " << file_size(argv[1]) << '\n';
+
+ return 0;
+}</pre>
+ </blockquote>
+ </td>
+ </tr>
+</table>
+
+<p>The Boost.Filesystem <code>file_size</code> function returns an <code>uintmax_t</code>
+containing the size of the file named in the argument.</p>
+
+<p>Build tut1.cpp and give it a try. Use whatever build environment you
+are most comfortable with.</p>
+<p>Here's a test on Windows, in the
+directory containing the build output. It contains a directory named test with a
+file named valentine:</p>
+<blockquote>
+ <pre>C:\v3d>dir test\valentine
+...
+12/30/2009 10:06 AM 23 valentine
+...
+
+C:\v3d>tut1 test\valentine
+test\valentine: 23
+
+C:\v3d>tut1 test/valentine
+test/valentine: 23
+
+C:\v3d>tut1 test</pre>
+</blockquote>
+ <p><img border="0" src="tut1_crash.jpg" width="474" height="302"><br>
+ <br>
+ Oops! <code>file_size</code> only works on files, not directories, so an
+ exception was thrown.</p>
+<blockquote>
+ <pre>C:\v3d>tut1 foo</pre>
+</blockquote>
+ <p><img border="0" src="tut1_crash.jpg" width="474" height="302"><br>
+ <br>
+ There's no file named <code>foo</code> in the current directory, so again an
+exception was thrown.</p>
+ <p>We'll deal with those conditions in tut2.cpp.</p>
+
+<h2>tut2.cpp - Using status queries to determine file existence and type</h2>
+
+<p>Boost.filesystem includes status query functions such as <code>exists</code>,
+<code>is_directory</code>, and <code>is_regular_file</code>. These all return
+<code>bool</code>'s, and will return <code>true</code> if the condition
+described by their name is met. They return <code>false</code> when any element
+of the path argument can't be found.</p>
+
+<p>tut2.cpp uses several of the status query functions to cope with non-existent
+files and with different file types. </p>
+
+<table align="center" border="1" cellpadding="3" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" bgcolor="#D7EEFF" width="90%">
+ <tr>
+ <td style="font-size: 10pt">
+ <pre>tut2.cpp</pre>
+ <blockquote style="font-size: 10pt">
+ <pre>int main(int argc, char* argv[])
+{
+ path p (argv[1]); // p reads clearer than argv[1] in the following code
+
+ cout << p << ": "; // utilize the path narrow stream inserter
+
+ if ( exists(p) ) // does p actually exist?
+ {
+ if ( is_regular_file(p) ) // is p a regular file?
+ cout << file_size(p) << '\n';
+
+ else if ( is_directory(p) ) // is p a directory?
+ cout << "is a directory\n";
+
+ else
+ cout << "exists, but is neither a regular file nor a directory\n";
+ }
+ else
+ cout << "does not exist\n";
+
+ return 0;
+}</pre>
+ </blockquote>
+ </td>
+ </tr>
+</table>
+
+<p>This works fine - give it a try yourself. However, the output is less than
+satisfactory a directory because we'd typically like to see its contents. Move
+on to tut3.cpp to see how to iterate over directories.</p>
+
+<h2>tut3.cpp - Directory iteration</h2>
+
+<p>Boost.Filesystem's <code><a href="reference.html#directory_iterator">
+directory_iterator</a></code> class is just what we need here. Constructed from
+a path, it iterates over the contents of the directory. The value type is
+directory_entry, which
+can be used for function arguments requiring a <code>path</code>.</p>
+
+<table align="center" border="1" cellpadding="3" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" bgcolor="#D7EEFF" width="90%">
+ <tr>
+ <td style="font-size: 10pt">
+ <pre>tut3.cpp</pre>
+ <blockquote>
+ <pre>int main(int argc, char* argv[])
+{
+ path p (argv[1]); // p reads clearer than argv[1] in the following code
+
+ cout << p << ": "; // utilize the path narrow stream inserter
+
+ if ( exists(p) ) // does p actually exist?
+ {
+ if ( is_regular_file(p) ) // is p a regular file?
+ cout << file_size(p) << '\n';
+
+ else if ( is_directory(p) ) // is p a directory?
+ {
+ cout << "is a directory containing:\n";
+
+ for ( directory_iterator it (p); // initialize it to the first element
+ it != directory_iterator(); // test for the past-the-end element
+ ++it ) // increment
+ {
+ cout << " " << *it << '\n'; // *it returns a directory_entry,
+ // which is converted to a path by the
+ // stream inserter.
+ // it->path() would be wordier, but would
+ // eliminate an unnecessary path temporary
+ }
+ }
+
+ else
+ cout << "exists, but is neither a regular file nor a directory\n";
+ }
+ else
+ cout << "does not exist\n";
+
+ return 0;
+}</pre>
+ </blockquote>
+ </td>
+ </tr>
+</table>
+
+<p>Give tut3 a try, passing it a path to a directory as a command line argument.
+Here is a run on a Boost Subversion trunk checkout:</p>
+
+<blockquote>
+ <pre>C:\v3d>tut3 c:\boost\trunk
+c:\boost\trunk: is a directory containing:
+ c:\boost\trunk\.svn
+ c:\boost\trunk\boost
+ c:\boost\trunk\boost-build.jam
+ c:\boost\trunk\boost.css
+ c:\boost\trunk\boost.png
+ c:\boost\trunk\bootstrap.bat
+ c:\boost\trunk\bootstrap.sh
+ c:\boost\trunk\CMakeLists.txt
+ c:\boost\trunk\doc
+ c:\boost\trunk\index.htm
+ c:\boost\trunk\index.html
+ c:\boost\trunk\INSTALL
+ c:\boost\trunk\Jamroot
+ c:\boost\trunk\libs
+ c:\boost\trunk\LICENSE_1_0.txt
+ c:\boost\trunk\more
+ c:\boost\trunk\people
+ c:\boost\trunk\rst.css
+ c:\boost\trunk\status
+ c:\boost\trunk\tools
+ c:\boost\trunk\wiki</pre>
+</blockquote>
+<p>It would be nice to output just the filename, without the parent path. Class
+<code>path</code> has functions to do just that, and a whole lot more. Let's
+take a side trip to learn more about class <code>path</code> observer, composition, decomposition and query
+functions.</p>
+<h2>path_info.cpp - Path observer, composition, decomposition and query</h2>
+
+<p> </p>
+
+<table align="center" border="1" cellpadding="3" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" bgcolor="#D7EEFF" width="90%">
+ <tr>
+ <td style="font-size: 10pt">
+ <pre>path_info.cpp</pre>
+ <blockquote style="font-size: 10pt">
+ <div dir="ltr">
+ <pre>const char * say_what(bool b) { return b ? "true" : "false"; }
+
+int main(int argc, char* argv[])
+{
+ if (argc < 2)
+ {
+ std::cout << "Usage: path_info path-portion...\n";
+ return 1;
+ }
+
+ fs::path p;
+
+ for (; argc > 1; --argc, ++argv)
+ p /= argv[1];
+
+ std::cout << "\npath \"" << p << "\"\n";
+
+ std::cout << "\nelements:\n";
+ for (fs::path::iterator it = p.begin(); it != p.end(); ++it)
+ std::cout << " " << *it << '\n';
+
+ std::cout << "\nobservers, native format:\n";
+ STD_OUT << " native()---------: " << p.native() << '\n';
+ STD_OUT << " c_str()----------: " << p.c_str() << '\n';
+ std::cout << " native_string()--: " << p.native_string() << std::endl;
+ std::wcout << " native_wstring()-: " << p.native_wstring() << std::endl;
+
+ std::cout << "\nobservers, portable format:\n";
+ std::cout << " string()---------: " << p.string() << std::endl;
+ std::wcout << " wstring()--------: " << p.wstring() << std::endl;
+
+ std::cout << "\ndecomposition:\n";
+ std::cout << " root_name()------: " << p.root_name() << '\n';
+ std::cout << " root_directory()-: " << p.root_directory() << '\n';
+ std::cout << " root_path()------: " << p.root_path() << '\n';
+ std::cout << " relative_path()--: " << p.relative_path() << '\n';
+ std::cout << " parent_path()----: " << p.parent_path() << '\n';
+ std::cout << " filename()-------: " << p.filename() << '\n';
+ std::cout << " stem()-----------: " << p.stem() << '\n';
+ std::cout << " extension()------: " << p.extension() << '\n';
+
+ std::cout << "\nquery:\n";
+ std::cout << " empty()--------------: " << say_what(p.empty()) << '\n';
+ std::cout << " is_complete()--------: " << say_what(p.is_complete()) << '\n';
+ std::cout << " has_root_name()------: " << say_what(p.has_root_name()) << '\n';
+ std::cout << " has_root_directory()-: " << say_what(p.has_root_directory()) << '\n';
+ std::cout << " has_root_path()------: " << say_what(p.has_root_path()) << '\n';
+ std::cout << " has_relative_path()--: " << say_what(p.has_relative_path()) << '\n';
+ std::cout << " has_parent_path()----: " << say_what(p.has_parent_path()) << '\n';
+ std::cout << " has_filename()-------: " << say_what(p.has_filename()) << '\n';
+ std::cout << " has_stem()-----------: " << say_what(p.has_stem()) << '\n';
+ std::cout << " has_extension()------: " << say_what(p.has_extension()) << '\n';
+
+ return 0;
+}
+</pre>
+ </div>
+ </blockquote>
+ </td>
+ </tr>
+</table>
+
+<h3>Directory iteration tweak - tut4.cpp</h3>
+
+<table align="center" border="1" cellpadding="3" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" bgcolor="#D7EEFF" width="90%">
+ <tr>
+ <td style="font-size: 10pt">
+ <pre>tut4.cpp</pre>
+ <blockquote>
+ <pre>int main(int argc, char* argv[])
+{
+ path p (argv[1]);
+
+ cout << p << ": ";
+ if ( exists(p) )
+ {
+ if ( is_regular_file(p) )
+ cout << file_size(p) << '\n';
+ else if ( is_directory(p) )
+ {
+ cout << "is a directory containing:\n";
+ for ( directory_iterator it (p); it != directory_iterator (); ++it )
+ {
+ <span style="background-color: #88FFA3">std::cout << " " << it-></span><span style="background-color: #88FFA3">path().filename</span><span style="background-color: #88FFA3">() << '\n';</span>
+ }
+ }
+ else
+ std::cout << "exists, but is neither a regular file nor a directory\n";<span style="background-color: #88FFA3">
+</span> }
+ else
+ std::cout << "does not exist\n";
+
+ return 0;
+}</pre>
+ </blockquote>
+ </td>
+ </tr>
+</table>
+
+<h3>Error handling - tut5.cpp</h3>
+
+<p> </p>
+
+<hr>
+<p>© Copyright Beman Dawes 2009</p>
+<p>Distributed under the Boost Software License, Version 1.0. See
+www.boost.org/LICENSE_1_0.txt</p>
+<p>Revised
+<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B %Y" startspan -->02 January 2010<!--webbot bot="Timestamp" endspan i-checksum="32136" --></p>
+
+</body>
+
+</html>
\ No newline at end of file