Boost-Commit :

Date view	Thread view	Subject view	Author view

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>.
-<code>Source</code> is required to be one of:
+<code><a name="Source">Source</a></code> is required to be one of:
<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 @@
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>
Revised
-01 February 2010
+03 February 2010

</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>

-Move on to the next section to see how those changes play out!
+Move on to <code>tut4.cpp</code> to see how those changes play out!

<h2>tut4.cpp - Using a path decomposition
function, plus sorting results</h2>
@@ -507,7 +507,7 @@
 </tr>
</table>

- The key change between <code>tut3.cpp</code> and <code>tut4.cpp</code> is
+ The key difference between <code>tut3.cpp</code> and <code>tut4.cpp</code> is
 what happens in the directory iteration loop. We changed:
 <blockquote>
 <pre>cout << " " << *it << '\n'; // *it returns a directory_entry,</pre>
@@ -520,9 +520,9 @@
 <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.
 The above was written as two lines of code for clarity. It could have
 been written more concisely as:
@@ -602,27 +602,41 @@

<h2><a name="Class-path">Class path</a></h2>

-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:
+A traditional C-style interface to <code>file_size()</code> would look like
+this:
+
+<blockquote>
+ <pre>uintmax_t <a name="file_size">file_size</a>(const char* p);</pre>
+</blockquote>
+Compare that with Boost.Filesystem's interface:
+<blockquote>
+ <pre>uintmax_t <a name="file_size">file_size</a>(const path& p);</pre>
+</blockquote>
+Class <code>path</code> is far more flexible:
+<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>
+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:

<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>
-and this allows <code>const path&</code> arguments to be called with a
-variety of object types, such as:
-<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>
+ 
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. 
- More on class <code>path</code>
- later in this tutorial.
+ manipulate the elements of a path. 

 <hr>

@@ -941,7 +953,7 @@
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>
Revised
-01 February 2010
+03 February 2010

</body>

Date view	Thread view	Subject view	Author view

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