Boost-Commit :

Date view	Thread view	Subject view	Author view

Subject: [Boost-commit] svn:boost r50654 - sandbox/filesystem-v3/libs/filesystem/doc
From: bdawes_at_[hidden]
Date: 2009-01-17 11:09:41

Author: bemandawes
Date: 2009-01-17 11:09:41 EST (Sat, 17 Jan 2009)
New Revision: 50654
URL: http://svn.boost.org/trac/boost/changeset/50654

Log:
Filesystem.v3: tweak design docs
Text files modified:
sandbox/filesystem-v3/libs/filesystem/doc/v3_design.html | 102 +++++++++++++++++++++++++++------------
1 files changed, 70 insertions(+), 32 deletions(-)

Modified: sandbox/filesystem-v3/libs/filesystem/doc/v3_design.html
==============================================================================
--- sandbox/filesystem-v3/libs/filesystem/doc/v3_design.html (original)
+++ sandbox/filesystem-v3/libs/filesystem/doc/v3_design.html 2009-01-17 11:09:41 EST (Sat, 17 Jan 2009)
@@ -11,7 +11,7 @@

<body>

-<table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="710">
+<table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="100%">
   <tr>
     <td width="277">
<a href="../../../index.htm">
@@ -38,7 +38,10 @@
   <tr>
     <td width="100%" bgcolor="#E8F5FF">
     <a href="#Introduction">Introduction</a><br>
-  </td>
+ Problem<br>
+ Solution<br>
+ Details<br>
+ Prototype</td>
   </tr>
   <tr>
     <td width="100%" bgcolor="#D7EEFF" align="center">
@@ -52,7 +55,7 @@

<h2><a name="Introduction">Introduction</a></h2>

-<p>During the review of Boost.Filesystem V2 (Internationalization), Peter Dimov
+<p>During the review of Boost.Filesystem.V2 (Internationalization), Peter Dimov
suggested that the class basic_path template was unwieldy, and that a single
path type that accommodated multiple character types and encodings would be more
flexible. Although I wasn't willing to stop development at that time to
@@ -64,42 +67,72 @@

<h2><b><a name="Problem">Problem</a></b></h2>

-<p>Say a user needs to take a path argument to a user defined function, and
-wishes to accommodate all applicable character types and encodings.
-<span style="background-color: #FFFF00">Must write template. Must provide
-do-the-right-thing overloads.</span></p>
+<p>With Filesystem.V2, a path argument to a user defined function that is to
+accommodate multiple character types and encodings must be written as a
+template. Do-the-right-thing overloads or template metaprogramming must be
+employed to allow arguments to be written as string literals. Here's what it
+looks like:</p>
+
+<blockquote>
+ <pre>template<class Path>
+void foo( const Path & p );</pre>
+ <pre>inline void foo( const path & p )
+{
+ return foo<path>( p );
+}
+inline void foo( const wpath & p )
+{
+ return foo<wpath>( p );
+}</pre>
+</blockquote>
+<p>That's really ugly for such a simple need, and there would be a combinatorial
+explosion if the function took multiple Path arguments and each could be either
+narrow or wide. It gets even worse if the C++0x <code>char16_t</code> and <code>
+char32_t</code> types are to be supported.</p>

<h2><a name="Solution">Solution</a></h2>

+<p>Overview:</p>
+
<ul>
- <li>A single class path.</li>
- <li>Conversions from and to applicable character types and encodings.</li>
- <li>Internally, the path is held in an object of a string type appropriate to the operating
- system; std::string for POSIX, std::wstring for Windows.</li>
+ <li>Provide a single, non-template, <code>class path</code>.</li>
+ <li>Provide each member function as a template accommodating the various
+ applicable character types, including user-defined character types.</li>
+ <li>Hold the path internally in a string of the type used by the operating
+ system API; <code>std::string</code> for POSIX, <code>std::wstring</code> for Windows.</li>
</ul>

-<p>An object of class <code>path</code> holds its contents as a basic_string of
-the preferred character type used by the operating system for paths, i.e.
-std::string for POSIX-like systems, std::wstring for Windows-like systems.</p>
-<blockquote>
- <p>Thus a path object's c_str() returns a string of the native character type
- and encoding that can be passed to operating system API calls without
- conversion.</p>
-</blockquote>
-<p>Strings representing paths passed as arguments to objects of class path
-undergo no conversion if they are of the native API's preferred character type.</p>
+<p>The signatures presented in Problem collapse to
+simply:</p>
<blockquote>
- <p>This mimics native OS API calls; no conversion are performed. For example,
- POSIX specifies that path strings are passed unchanged by the  API. Note
- that this is different from the POSIX command line utilities, some of which
- are specified to convert according to a locale.</p>
+ <pre>void foo( const path & p );</pre>
</blockquote>
-<p> </p>
+
+<p>That's a signification reduction in code complexity. Specification becomes
+simpler, too. I believe it will be far easier to teach, and result in much more
+flexible user code.</p>
+
+<p>Other benefits:</p>
+<ul>
+ <li>All the polymorphism still occurs at compile time.</li>
+ <li>Efficiency is increased, in that conversions of the encoding, if required,
+ only occur once at the time of creation, not each time the path is used.</li>
+ <li>The size of the implementation code drops approximately in half and
+ becomes much more readable.</li>
+</ul>
+ <p>Possible problems:</p>
+<ul>
+ <li>The combination of member function templates and implicit constructors can
+ result in unclear error messages when the user makes simple commonplace coding
+ errors. This should be much less of a problem with C++ concepts, but in the
+ meantime work continues to restrict over aggressive templates via enable_if/disable_if.</li>
+</ul>
+ <h2><a name="Details">Details</a></h2>

<table border="1" cellpadding="4" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="100%">
   <tr>
     <td width="33%" colspan="3">
- <p align="center"><i><b>Conversions</b></i></td>
+ <p align="center"><b><i>Encoding </i></b><i><b>Conversions</b></i></td>
   </tr>
   <tr>
     <td width="33%">
@@ -110,21 +143,26 @@
     <p align="center"><i><b>wide string path arguments</b></i></td>
   </tr>
   <tr>
- <td width="33%">Systems with char as the preferred path character type (i.e.
+ <td width="33%">Systems with <code>char</code> as the native API path character type (i.e.
     POSIX-like systems)</td>
     <td width="33%">No conversion.</td>
     <td width="34%">Conversion occurs, performed by the current path locale's
- codecvt facet.</td>
+ <code>codecvt</code> facet.</td>
   </tr>
   <tr>
- <td width="33%">Systems with wchar_t as the preferred path character type
+ <td width="33%">Systems with <code>wchar_t</code> as the native API path character type
     (i.e. Windows-like systems).</td>
     <td width="33%">Conversion occurs, performed by the current path locale's
- codecvt facet.</td>
+ <code>codecvt</code> facet.</td>
     <td width="34%">No conversion.</td>
   </tr>
</table>

+<p>When a class path function argument type matches the the operating system's
+API argument type for paths, no conversion is performed rather than conversion
+to a specified encoding such as one of the Unicode encodings. This avoids
+unintended consequences, etc.</p>
+
<h2><a name="Prototype">Prototype</a></h2>

<p>Currently incomplete. Not thoroughly tested. Should not be used for
@@ -132,7 +170,7 @@

<hr>
<p>Revised
-26 December, 2008</p>
+17 January, 2009</p>

<p>© Copyright Beman Dawes, 2008</p>
<p> Use, modification, and distribution are subject to the Boost Software

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