Subject: [Boost-commit] svn:boost r59471 - sandbox/filesystem-v3/libs/filesystem/doc
From: bdawes_at_[hidden]
Date: 2010-02-04 12:09:14
Author: bemandawes
Date: 2010-02-04 12:09:12 EST (Thu, 04 Feb 2010)
New Revision: 59471
URL: http://svn.boost.org/trac/boost/changeset/59471
Log:
work-in-progress
Text files modified:
sandbox/filesystem-v3/libs/filesystem/doc/reference.html | 4 +-
sandbox/filesystem-v3/libs/filesystem/doc/tutorial.html | 64 +++++++++++++++++++++++----------------
2 files changed, 40 insertions(+), 28 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-04 12:09:12 EST (Thu, 04 Feb 2010)
@@ -619,7 +619,7 @@
compliant iterator
pointing to contiguous storage. The iterator's value type is required to be <code>char</code>, <code>
wchar_t</code>, <code>char16_t</code>, or <code>char32_t</code>.</p>
-<p><code>Source</code> is required to be one of:</p>
+<p><code><a name="Source">Source</a></code> is required to be one of:</p>
<ul>
<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>
@@ -3185,7 +3185,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 -->01 February 2010<!--webbot bot="Timestamp" endspan i-checksum="40539" --></p>
+<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B %Y" startspan -->03 February 2010<!--webbot bot="Timestamp" endspan i-checksum="40543" --></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-04 12:09:12 EST (Thu, 04 Feb 2010)
@@ -449,7 +449,7 @@
results ourselves. </li>
</ul>
-<p>Move on to the next section to see how those changes play out!</p>
+<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>
@@ -507,7 +507,7 @@
</tr>
</table>
- <p>The key change between <code>tut3.cpp</code> and <code>tut4.cpp</code> is
+ <p>The key difference between <code>tut3.cpp</code> and <code>tut4.cpp</code> is
what happens in the directory iteration loop. We changed:</p>
<blockquote>
<pre>cout << " " << *it << '\n'; // *it returns a directory_entry,</pre>
@@ -520,9 +520,9 @@
<p><code>path()</code>
is a <code>directory_entry</code> observer function. <code>
<a href="reference.html#path-filename">filename()</a></code> is one of
- several path decomposition functions. It extracts the filename portion (<code>"foo.txt"</code>)
- from a path (<code>"/bar/foo.txt"</code>). These decomposition functions are
- explored in the <a href="#path-iteration-etc">Path iterators, observers,
+ several path decomposition functions. It extracts the filename portion (<code>"index.html"</code>)
+ from a path (<code>"/home/beman/boost/trunk/index.html"</code>). These decomposition functions are
+ more fully explored in the <a href="#path-iteration-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
been written more concisely as:</p>
@@ -602,27 +602,41 @@
<h2><a name="Class-path">Class path</a></h2>
-<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>
+<p>A traditional C-style interface to <code>file_size()</code> would look like
+this:</p>
+
+<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& p);</pre>
+</blockquote>
+<p>Class <code>path</code> is far more flexible:</p>
+<ol>
+ <li>It supports multiple character types and encodings, including Unicode, to
+ ease internationalization.</li>
+ <li>It 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,
+ decomposition, and query functions, making pathname manipulations easy,
+ convenient, reliable, and portable.</li>
+</ol>
+<p>Let's take a look at 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 style="font-size: 10pt">
- <pre>template <class Source>
+ <pre>template <class Source>
path(Source const& source);</pre>
+ <pre>template <class ContiguousIterator>
+ path(ContiguousIterator begin, ContiguousIterator end);</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 style="font-size: 10pt">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 style="font-size: 10pt">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 style="font-size: 10pt">A <code>boost::filesystem::directory_entry</code>.</li>
-</ul>
+<p> </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
@@ -638,9 +652,7 @@
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>
+ manipulate the elements of a path. </p>
<hr>
@@ -941,7 +953,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 -->01 February 2010<!--webbot bot="Timestamp" endspan i-checksum="40539" --></p>
+<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B %Y" startspan -->03 February 2010<!--webbot bot="Timestamp" endspan i-checksum="40543" --></p>
</body>