Boost logo

Boost-Commit :

Subject: [Boost-commit] svn:boost r59693 - in sandbox/filesystem-v3/libs/filesystem: doc example
From: bdawes_at_[hidden]
Date: 2010-02-15 09:25:17


Author: bemandawes
Date: 2010-02-15 09:25:16 EST (Mon, 15 Feb 2010)
New Revision: 59693
URL: http://svn.boost.org/trac/boost/changeset/59693

Log:
Docs work-in-progress
Text files modified:
   sandbox/filesystem-v3/libs/filesystem/doc/reference.html | 210 +++++++++++----------------------------
   sandbox/filesystem-v3/libs/filesystem/doc/tutorial.html | 193 +++++++++++++++++++++++------------
   sandbox/filesystem-v3/libs/filesystem/example/tut5.cpp | 2
   3 files changed, 188 insertions(+), 217 deletions(-)

Modified: sandbox/filesystem-v3/libs/filesystem/doc/reference.html
==============================================================================
--- sandbox/filesystem-v3/libs/filesystem/doc/reference.html (original)
+++ sandbox/filesystem-v3/libs/filesystem/doc/reference.html 2010-02-15 09:25:16 EST (Mon, 15 Feb 2010)
@@ -111,11 +111,7 @@
 &nbsp;&nbsp;&nbsp;&nbsp symlink_status<br>
 &nbsp;&nbsp;&nbsp;&nbsp system_complete</td>
     <td width="34%" valign="top">
- <a href="#header-fstream">Additions
- to header &lt;fstream&gt;</a><br>
-Suggestions for <fstream><code><br>
-&nbsp; </code>
- implementations<br>
+ File streams<br>
 <a href="#Path-decomposition-table">Path decomposition table</a><br>
 <a href="#Acknowledgements">Acknowledgements</a><br>
 <a href="#References">References</a><br>
@@ -212,7 +208,7 @@
 <p><b><i><a name="native-pathname-format">Native pathname format:</a></i></b>&nbsp;
 An implementation defined format. [<i>Note:</i> For POSIX-like operating
 systems, the native format is the same as the generic format. For Windows, the
-native format is the same as the generic format, except that directory-separator
+native format is similar to the generic format, but the directory-separator
 characters can be either slashes or backslashes. <i>--end note</i>]</p>
 <p><i><b><a name="Link">Link</a>:</b> </i>A directory entry object that associates a
 filename with a file. On some file systems, several directory entries can
@@ -2478,148 +2474,64 @@
     </td>
   </tr>
 </table>
-<h3><a name="header-fstream">Additions</a> to header <code>&lt;fstream&gt;</code></h3>
-<blockquote>
-<p><span style="background-color: #E0E0E0; font-style:italic">These additions have been carefully
-specified to avoid breaking existing code in common operating environments such as
-</span> <i><span style="background-color: #E0E0E0">POSIX</span></i><span style="background-color: #E0E0E0; font-style:italic">,
-</span> <i>
-<span style="background-color: #E0E0E0">Windows</span></i><span style="background-color: #E0E0E0; font-style:italic">, and
-</span> <i><span style="background-color: #E0E0E0">OpenVMS.
-See </span><a href="#Suggestions-for-fstream">
-<span style="background-color: #E0E0E0">Suggestions for <code>&lt;fstream&gt;</code>
-implementations</span></a><span style="background-color: #E0E0E0"> for
-techniques to avoid breaking existing code in other environments, particularly
-on operating systems allowing slashes in filenames.</span></i></p>
-<p><span style="background-color: #FFFFFF">[<i>Note:</i> The
-&quot;do-the-right-thing&quot; rule in the conformance section does apply to header <code>&lt;fstream&gt;</code>.</span></p>
-<p><span style="background-color: #FFFFFF">The overloads
-below are specified as additions rather than replacements for existing
-functions. This preserves existing code (perhaps
-using a <a name="home-grown-path">home-grown path</a> class) that relies on an
-automatic conversion to <code>const char*</code>.<i> -- end note</i>]</span></p>
-</blockquote>
-<p><span style="background-color: #FFFFFF"><i>In 27.8.1.1 Class template
-basic_filebuf [lib.filebuf] synopsis preceding paragraph 1, add the function:</i></span></p>
-<blockquote>
-<pre><span style="background-color: #FFFFFF"></span><span style="background-color: #FFFFFF">basic_filebuf</span><span style="background-color: #FFFFFF">&lt;charT,traits&gt;* </span><span style="background-color: #FFFFFF">open(const</span><span style="background-color: #FFFFFF"> path p, </span><span style="background-color: #FFFFFF">ios_base::openmode</span><span style="background-color: #FFFFFF"> mode);</span></pre>
-</blockquote>
-<p><span style="background-color: #FFFFFF"><i>In 27.8.1.3 Member functions [lib.filebuf.members],
-add the above to the signature preceding paragraph 2, and replace the
-sentence:</i></span></p>
-<blockquote>
-<p><span style="background-color: #FFFFFF">It then opens a file, if possible,
-whose name is the NTBS s (as if by calling <code>std::fopen(s ,<i>modstr</i>
-))</code>.</span></p>
-</blockquote>
-<p><span style="background-color: #FFFFFF"><i>with:</i></span></p>
-<blockquote>
-<p><span style="background-color: #FFFFFF">It then opens, if possible, the file
-that
-<code>p</code> or <code>path(s)</code> resolves to, as if by calling <code>std::fopen()</code> with a
-second argument of <i>modstr</i>.</span></p>
-</blockquote>
-<p><span style="background-color: #FFFFFF"><i>In 27.8.1.5 Class template
-basic_ifstream [lib.ifstream] synopsis preceding paragraph 1, add the functions:</i></span></p>
-<blockquote>
- <pre><span style="background-color: #FFFFFF">explicit basic_ifstream(const path&amp; p, ios_base::openmode mode = ios_base::in);
-void open(const path&amp; p, ios_base::openmode mode = ios_base::in);</span></pre>
-</blockquote>
-<p><i><span style="background-color: #FFFFFF">In 27.8.1.6 basic_ifstream
-constructors [lib.ifstream.cons] </span></i>
-<span style="background-color: #FFFFFF"><i>add the above constructor to the signature preceding
-paragraph 2, and in paragraph 2 replace</i></span></p>
-<blockquote>
-<p><span style="background-color: #FFFFFF"><code>rdbuf()-&gt;open(s, mode |
-ios_base::in)</code></span></p>
-</blockquote>
-<p><span style="background-color: #FFFFFF"><i>with</i></span></p>
-<blockquote>
-<p><span style="background-color: #FFFFFF"><code>rdbuf()-&gt;open(path(s), mode |
-ios_base::in)</code> or <code>rdbuf()-&gt;open(p, mode | ios_base::in)</code> as
-appropriate</span></p>
-</blockquote>
-<p><i><span style="background-color: #FFFFFF">In 27.8.1.7 Member functions [lib.ifstream.members]
-</span></i><span style="background-color: #FFFFFF"><i>add the above open
-function to the signature
-preceding paragraph 3, and in paragraph 3 replace</i></span></p>
-<blockquote>
-<p><span style="background-color: #FFFFFF"><code>rdbuf()-&gt;open(s, mode |
-ios_base::in)</code></span></p>
-</blockquote>
-<p><span style="background-color: #FFFFFF"><i>with</i></span></p>
-<blockquote>
-<p><span style="background-color: #FFFFFF"><code>rdbuf()-&gt;open(path(s), mode |
-ios_base::in)</code> or <code>rdbuf()-&gt;open(p, mode | ios_base::in)</code> as
-appropriate</span></p>
-</blockquote>
-<p><span style="background-color: #FFFFFF"><i>In 27.8.1.8 Class template
-basic_ofstream [lib.ofstream] synopsis preceding paragraph 1, add the
-
-functions:</i></span></p>
-<blockquote>
- <pre><span style="background-color: #FFFFFF">explicit basic_ofstream(const path&amp; p, ios_base::openmode mode = ios_base::out);
-void open(const path&amp; p, ios_base::openmode mode = ios_base::out);</span></pre>
-</blockquote>
-<p><i><span style="background-color: #FFFFFF">In 27.8.1.9 basic_ofstream
-constructors [lib.ofstream.cons] </span></i>
-<span style="background-color: #FFFFFF"><i>add the above constructor to the signature preceding
-paragraph 2, and in paragraph 2 replace</i></span></p>
-<blockquote>
-<p><span style="background-color: #FFFFFF"><code>rdbuf()-&gt;open(s, mode |
-ios_base::out)</code></span></p>
-</blockquote>
-<p><span style="background-color: #FFFFFF"><i>with</i></span></p>
-<blockquote>
-<p><span style="background-color: #FFFFFF"><code>rdbuf()-&gt;open(path(s), mode |
-ios_base::out)</code> or <code>rdbuf()-&gt;open(p, mode | ios_base::out)</code> as
-appropriate</span></p>
-</blockquote>
-<p><i><span style="background-color: #FFFFFF">In 27.8.1.10 Member functions [lib.ofstream.members]
-</span></i><span style="background-color: #FFFFFF"><i>add the above open
-function to the signature
-preceding paragraph 3, and in paragraph 3 replace</i></span></p>
-<blockquote>
-<p><span style="background-color: #FFFFFF"><code>rdbuf()-&gt;open(s, mode |
-ios_base::out)</code></span></p>
-</blockquote>
-<p><span style="background-color: #FFFFFF"><i>with</i></span></p>
-<blockquote>
-<p><span style="background-color: #FFFFFF"><code>rdbuf()-&gt;open(path(s), mode |
-ios_base::out)</code> or <code>rdbuf()-&gt;open(p, mode | ios_base::out)</code> as
-appropriate</span></p>
-</blockquote>
-<p><span style="background-color: #FFFFFF"><i>In 27.8.1.11 Class template
-basic_fstream [lib.fstream] synopsis preceding paragraph 1, add the functions:</i></span></p>
-<blockquote>
- <pre><span style="background-color: #FFFFFF">explicit basic_fstream(const path&amp; p, ios_base::openmode mode = ios_base::in|ios_base::out);
-void open(const path&amp; p, ios_base::openmode mode = ios_base::in|ios_base::out);</span></pre>
-</blockquote>
-<p><i><span style="background-color: #FFFFFF">In 27.8.1.12 basic_fstream
-constructors [lib.fstream.cons] </span></i>
-<span style="background-color: #FFFFFF"><i>add the above constructor to the signature preceding
-paragraph 2, and in paragraph 2 replace</i></span></p>
-<blockquote>
-<p><span style="background-color: #FFFFFF"><code>rdbuf()-&gt;open(s, mode)</code></span></p>
-</blockquote>
-<p><span style="background-color: #FFFFFF"><i>with</i></span></p>
-<blockquote>
-<p><span style="background-color: #FFFFFF"><code>rdbuf()-&gt;open(path(s), mode)</code>
-or <code>rdbuf()-&gt;open(p, mode)</code> as appropriate</span></p>
-</blockquote>
-<p><i><span style="background-color: #FFFFFF">In 27.8.1.13 Member functions [lib.fstream.members]
-</span></i><span style="background-color: #FFFFFF"><i>add the above open
-function to the signature
-preceding paragraph 3, and in paragraph 3 replace</i></span></p>
-<blockquote>
-<p><span style="background-color: #FFFFFF"><code>rdbuf()-&gt;open(s, mode)</code></span></p>
-</blockquote>
-<p><span style="background-color: #FFFFFF"><i>with</i></span></p>
-<blockquote>
-<p><span style="background-color: #FFFFFF"><code>rdbuf()-&gt;open(path(s), mode)</code>
-or <code>rdbuf()-&gt;open(p, mode)</code> as appropriate</span></p>
-</blockquote>
-<p><span style="background-color: #FFFFFF"><i>End of proposed text.</i></span></p>
+<h3><a name="File-streams">File streams</a></h3>
+<p>Replacements are provided for the file stream classes from the C++ standard
+library's <code>&lt;fstream&gt;</code> header. These replacement classes
+publicly inherit from the standard library classes. In the Boost.Filesystem
+version, constructors and open functions take <code>const path&amp;</code> arguments
+instead of <code>
+const char*</code> arguments. There are no other differences in syntax or
+semantics.</p>
+<pre>namespace boost
+{
+ namespace filesystem
+ {
+ template &lt; class charT, class traits = std::char_traits&lt;charT&gt; &gt;
+ class basic_filebuf : public std::basic_filebuf&lt;charT,traits&gt;
+ {
+ public:
+ basic_filebuf&lt;charT,traits&gt;*
+ open(const path&amp; p, std::ios_base::openmode mode);
+ };
+
+ template &lt; class charT, class traits = std::char_traits&lt;charT&gt; &gt;
+ class basic_ifstream : public std::basic_ifstream&lt;charT,traits&gt;
+ {
+ public:
+ explicit basic_ifstream(const path&amp; p, std::ios_base::openmode mode=std::ios_base::in)
+ void open(const path&amp; p, std::ios_base::openmode mode=std::ios_base::in);
+ };
+
+ template &lt; class charT, class traits = std::char_traits&lt;charT&gt; &gt;
+ class basic_ofstream : public std::basic_ofstream&lt;charT,traits&gt;
+ {
+ public:
+ explicit basic_ofstream(const path&amp; p, std::ios_base::openmode mode=std::ios_base::out);
+ void open(const path&amp; p, std::ios_base::openmode mode=std::ios_base::out);
+ };
+
+ template &lt; class charT, class traits = std::char_traits&lt;charT&gt; &gt;
+ class basic_fstream : public std::basic_fstream&lt;charT,traits&gt;
+ {
+ public:
+ explicit basic_fstream(const path&amp; p,
+ std::ios_base::openmode mode=std::ios_base::in | std::ios_base::out);
+ void open(const path&amp; p,
+ std::ios_base::openmode mode=std::ios_base::in | std::ios_base::out);
+ };
+
+ typedef basic_filebuf&lt;char&gt; filebuf;
+ typedef basic_ifstream&lt;char&gt; ifstream;
+ typedef basic_ofstream&lt;char&gt; ofstream;
+ typedef basic_fstream&lt;char&gt; fstream;
+
+ typedef basic_filebuf&lt;wchar_t&gt; wfilebuf;
+ typedef basic_ifstream&lt;wchar_t&gt; wifstream;
+ typedef basic_fstream&lt;wchar_t&gt; wfstream;
+ typedef basic_ofstream&lt;wchar_t&gt; wofstream;
+
+ } // namespace filesystem
+} // namespace boost</pre>
 <h2><a name="Path-decomposition-table">Path decomposition table</a></h2>
 <p>The table is generated by a program compiled with the Boost implementation.</p>
 <p>Shaded entries indicate cases where <i>POSIX</i> and <i>Windows</i>
@@ -3182,7 +3094,7 @@
 <p>Distributed under the Boost Software License, Version 1.0. See
 <a href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/LICENSE_1_0.txt</a></p>
 <p>Revised
-<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B %Y" startspan -->04 February 2010<!--webbot bot="Timestamp" endspan i-checksum="40545" --></p>
+<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B %Y" startspan -->14 February 2010<!--webbot bot="Timestamp" endspan i-checksum="40546" --></p>
 
 </body>
 

Modified: sandbox/filesystem-v3/libs/filesystem/doc/tutorial.html
==============================================================================
--- sandbox/filesystem-v3/libs/filesystem/doc/tutorial.html (original)
+++ sandbox/filesystem-v3/libs/filesystem/doc/tutorial.html 2010-02-15 09:25:16 EST (Mon, 15 Feb 2010)
@@ -35,21 +35,32 @@
     <a href="faq.htm">FAQ</a></td>
   </tr>
 </table>
-
-<h2>Introduction</h2>
+<p>
+ Introduction<br>
+ Preliminaries<br>
+ Reporting the size of a file - (tut1.cpp)<br>
+ Using status queries to determine file existence and type - (tut2.cpp)<br>
+ Directory iteration - (tut3.cpp)<br>
+ Using path decomposition, plus sorting results - (tut4.cpp)<br>
+ Class path: Constructors - (tut5.cpp)<br>
+ Class path: Generic format vs. Native format<br>
+ Class path: Iterators, observers, composition, decomposition, and query - (path_info.cpp)<br>
+ Error reporting<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
-to know about to use Boost.Filesystem effectively.</p>
+to know about to understand Boost.Filesystem.</p>
 
-<p>Source code for each version of the tutorial program is available, and you
+<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>
 
-<h3>Preliminaries</h3>
+<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
@@ -109,7 +120,7 @@
     problem.</li>
   </ul>
 
-<h2>tut1.cpp - Reporting the size of a file</h2>
+<h2><a name="Reporting-size">Reporting the size of a file</a> - (tut1.cpp)</h2>
 
 <p>Let's get started. One of the simplest things we can do is report the size of
 a file.</p>
@@ -234,7 +245,7 @@
 
   <p>We'll deal with those situations in <code>tut2.cpp</code>.</p>
 
-<h2>tut2.cpp - Using status queries to determine file existence and type</h2>
+<h2><a name="Using-status-queries">Using status queries to determine file existence and type</a> - (tut2.cpp)</h2>
 
 <p>Boost.Filesystem includes status query functions such as <code>
 <a href="reference.html#exists-path">exists</a></code>,
@@ -313,7 +324,7 @@
 satisfactory for a directory since we'd typically like to see the directory's contents. Move
 on to <code>tut3.cpp</code> to see how to iterate over directories.</p>
 
-<h2>tut3.cpp - Directory iteration</h2>
+<h2><a name="Directory-iteration">Directory iteration</a> - (tut3.cpp)</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
@@ -451,8 +462,7 @@
 
 <p>Move on to <code>tut4.cpp</code> to see how those changes play out!</p>
 
-<h2>tut4.cpp - Using a path decomposition
-function, plus sorting results</h2>
+<h2><a name="Using-path-decomposition">Using path decomposition, plus sorting results</a> - (tut4.cpp)</h2>
 
 <table align="center" border="1" cellpadding="3" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" bgcolor="#D7EEFF" width="90%">
   <tr>
@@ -600,29 +610,24 @@
 
 <hr>
 
-<h2><a name="Class-path">Class path</a></h2>
-
-<p>A traditional C-style interface to <code>file_size()</code> would look like
-this:</p>
+<h2>&nbsp;<a name="Class-path-Constructors">Class path: Constructors</a> - (tut5.cpp)</h2>
 
-<blockquote>
- <pre><span style="background-color: #FFFFFF; ">uintmax_t</span> <a name="file_size">file_size</a>(const char* p);</pre>
-</blockquote>
-<p>Compare that with Boost.Filesystem's interface:</p>
-<blockquote>
- <pre><span style="background-color: #FFFFFF; ">uintmax_t</span> <a name="file_size">file_size</a>(const path&amp; p);</pre>
-</blockquote>
-<p>Class <code>path</code> is far more flexible:</p>
+<p>Traditional C interfaces pass paths as <code>const char*</code> arguments.
+C++ interfaces may add <code>const std::string&amp;</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&amp;</code> arguments is far simpler, yet far
+more flexible because class <code>path</code> itself is far more flexible:</p>
 <ol>
- <li>It 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>It supports multiple source types, such as iterators for null terminated
+ <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>directory_entry</code>'s,
   so functions taking paths don't need to provide several overloads.</li>
- <li>It supports both native and generic pathname formats, so programs can be
- portable between operating systems yet use native conventions where desirable.</li>
- <li>It supplies a full set of iterators, observers, composition,
+ <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,
   convenient, reliable, and portable.</li>
 </ol>
@@ -636,7 +641,9 @@
   <pre>template &lt;class InputIterator&gt;
   path(InputIterator begin, InputIterator end);</pre>
 </blockquote>
-<p>Let's look at a little program that shows off these features:</p>
+<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 align="center" border="1" cellpadding="3" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" bgcolor="#D7EEFF" width="90%">
   <tr>
@@ -673,6 +680,8 @@
   { fs::ofstream f(L&quot;smile\u263A&quot;); }
   { fs::ofstream f(narrow_string); }
   { fs::ofstream f(wide_string); }
+ // { fs::ofstream f(narrow_list); } and { fs::ofstream f(wide_list); }
+ // would work, but we want to show off construction from an iterator range:
   { fs::ofstream f(fs::path(narrow_list.begin(), narrow_list.end())); }
   { fs::ofstream f(fs::path(wide_list.begin(), wide_list.end())); }
 
@@ -683,7 +692,7 @@
   </tr>
 </table>
 
-<p>Testing tut5:</p>
+<p>Testing <code>tut5</code>:</p>
 
   <table align="center" border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" bgcolor="#D7EEFF" width="90%">
     <tr>
@@ -710,29 +719,96 @@
   </table>
 
 <p>Note that the exact appearance of the smiling face will depend on the font,
-font size, and other settings for your command line window.</p>
-<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">&#9829;valentine</font></code>. Here's the code:</p>
-<blockquote style="font-size: 10pt">
- <pre>boost::filesystem::rename(&quot;valentine&quot;, L&quot;\u2665valentine&quot;);</pre>
-</blockquote>
+font size, and other settings for your command line window. The above tests were
+run with out-of-the-box Ubuntu 9.10 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
+ 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
+ functions that take <code>const path&amp;</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
+ tutorial deals with path syntax.</p>
+
+ <hr>
 
- <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. </p>
+<h2><a name="Class-path-formats">Class path: Generic format vs. Native format</a></h2>
+
+<p dir="ltr"><b>Class <code>path</code> deals with two different pathname
+formats - generic format and native format.</b> In the case of 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 dir="ltr">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 dir="ltr">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. If a drive specified or a backslash appears
+in a pathname on a Windows system, it is always treated as the native format.</p>
+
+<p dir="ltr">We can use <code>tut4</code> to explore the two formats:</p>
+
+ <table align="center" border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" bgcolor="#D7EEFF" width="90%">
+ <tr>
+ <td align="center" width="50%" style="font-size: 10pt"><i><b>Ubuntu Linux </b></i></td>
+ <td align="center" style="font-size: 10pt"><i><b>Microsoft Windows</b></i></td>
+ </tr>
+ <tr>
+ <td width="50%" style="font-size: 10pt" valign="top">
+ <pre>$ ./tut4 tut4.cpp
+tut4.cpp: 1920
+
+$ ./tut4 ./tut4.cpp
+./tut4.cpp: 1920
+
+$ ./tut4 .\tut4.cpp
+.tut4.cpp: does not exist
+
+$ ./tut4 .\\tut4.cpp
+.\tut4.cpp: does not exist</pre>
+ </td>
+ <td style="font-size: 10pt" valign="top">
+ <pre>&gt;tut4 tut4.cpp
+tut4.cpp: 1984
+
+&gt;tut4 ./tut4.cpp
+./tut4.cpp: 1984
+
+&gt;tut4 .\tut4.cpp
+.\tut4.cpp: 1984
+
+&gt;tut4 .\\tut4.cpp
+.\\tut4.cpp: 1984</pre>
+ </td>
+ </tr>
+ </table>
+
+ <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 are confused by the generic format. The generic
+ format is great, however, for writing portable programs that work regardless
+ of operating system.</p>
 
     <hr>
 
-<h2><a name="path-iteration-etc"></a>Path iterators, observers, composition, decomposition, and query</h2>
+<h2><a name="Class path-iterators-etc">Class path: Iterators, observers, composition, decomposition, and query</a>
+- (path_info.cpp)</h2>
 
-<p>The path_info.cpp program is handy for learning how class <code>path</code>
+<p>The <code>path_info.cpp</code> program is handy for learning how class <code>path</code>
 iterators,
 observers, composition, decomposition, and query functions work on your system.
 If it hasn't already already been built on your system, please build it now. Run
@@ -838,22 +914,6 @@
     </tr>
   </table>
 
-<p dir="ltr"><b>Class <code>path</code> deals with two different pathname
-formats - a generic format and a native format.</b> In the case of POSIX-like
-operating systems, these formats are the same. But for users of Windows and
-other non-POSIX operating 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 dir="ltr">The <b>generic format</b> is the format used by POSIX-like
-operating systems such as the Unixes, Linux, and Mac OS X. The directory
-separator character is a slash.</p>
-
-<p dir="ltr">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. If a drive specified or a backslash appears
-in a pathname on a Windows system, it is always treated as the native format.</p>
-
 <p dir="ltr">Native format observers should be used when interacting with the
 operating system or with users; that's what they expect.</p>
 
@@ -1017,17 +1077,14 @@
 
   <p>Functions with a <code>system::error_code&amp;</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>
-
-<p>&nbsp;</p>
+do not throw exceptions when I/O errors occur.</p>
 
 <hr>
 <p>© Copyright Beman Dawes 2010</p>
 <p>Distributed under the Boost Software License, Version 1.0. See
 <a href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/LICENSE_1_0.txt</a></p>
 <p>Revised
-<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B %Y" startspan -->05 February 2010<!--webbot bot="Timestamp" endspan i-checksum="40547" --></p>
+<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B %Y" startspan -->15 February 2010<!--webbot bot="Timestamp" endspan i-checksum="40548" --></p>
 
 </body>
 

Modified: sandbox/filesystem-v3/libs/filesystem/example/tut5.cpp
==============================================================================
--- sandbox/filesystem-v3/libs/filesystem/example/tut5.cpp (original)
+++ sandbox/filesystem-v3/libs/filesystem/example/tut5.cpp 2010-02-15 09:25:16 EST (Mon, 15 Feb 2010)
@@ -37,6 +37,8 @@
   { fs::ofstream f(L"smile\u263A"); }
   { fs::ofstream f(narrow_string); }
   { fs::ofstream f(wide_string); }
+ // { fs::ofstream f(narrow_list); } and { fs::ofstream f(wide_list); }
+ // would work, but we want to show off construction from an iterator range:
   { fs::ofstream f(fs::path(narrow_list.begin(), narrow_list.end())); }
   { fs::ofstream f(fs::path(wide_list.begin(), wide_list.end())); }
 


Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk