| <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 V3 Design</title> |
| <link rel="stylesheet" type="text/css" href="../../../../doc/src/minimal.css"> |
| </head> |
| |
| <body> |
| |
| <table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111"> |
| <tr> |
| <td> |
| <a href="../../../../index.htm"> |
| <img src="../../../../boost.png" alt="boost.png (6897 bytes)" align="middle" border="0" width="300" height="86"></a></td> |
| <td align="middle"> |
| <font size="7">Filesystem Version 3<br> |
| Design</font></td> |
| </tr> |
| </table> |
| |
| <table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" bgcolor="#D7EEFF" width="100%"> |
| <tr> |
| <td><a href="../../../../index.htm">Boost Home</a> |
| <a href="index.htm">Library Home</a> |
| <a href="reference.html">Reference</a> |
| <a href="tutorial.html">Tutorial</a> |
| <a href="faq.htm">FAQ</a> |
| <a href="portability_guide.htm">Portability</a> |
| <a href="v3.html">V3 Intro</a> |
| <a href="v3_design.html">V3 Design</a> |
| <a href="deprecated.html">Deprecated</a> |
| </td> |
| </tr> |
| </table> |
| |
| <table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" align="right"> |
| <tr> |
| <td width="100%" bgcolor="#D7EEFF" align="center"> |
| <i><b>Contents</b></i></td> |
| </tr> |
| <tr> |
| <td width="100%" bgcolor="#E8F5FF"> |
| <a href="#Introduction">Introduction</a><br> |
| <a href="#Problem">Problem</a><br> |
| <a href="#Solution">Solution</a><br> |
| <a href="#Details">Details</a><br> |
| <a href="#Other-changes">Other changes</a><br> |
| <a href="#Acknowledgements">Acknowledgements</a></td> |
| </tr> |
| </table> |
| |
| <p><b>Caution:</b> This page documents thinking early in the V3 development |
| process, and is intended to serve historical purposes. It is not updated to |
| reflect the current state of the library.</p> |
| |
| <h2><a name="Introduction">Introduction</a></h2> |
| |
| <p>During the review of Boost.Filesystem.V2 (Internationalization), Peter Dimov |
| suggested that the<code> basic_path</code> class 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 |
| explore how this idea might be implemented, or to break from the pattern for |
| Internationalization used the C++ standard library, I've often thought about |
| Peter's suggestion. With the advent of C++0x <code>char16_t</code> and <code>char32_t</code> character |
| types, the <code>basic_path</code> class template approach becomes even more unwieldy, so it |
| is time to revisit the problem in light of Peter's suggestion.</p> |
| |
| <h2><b><a name="Problem">Problem</a></b></h2> |
| |
| <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, non-template, <code>class path</code>.</li> |
| <li>Each member function is 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>The signatures presented in <a href="#Problem">Problem</a> collapse to |
| simply:</p> |
| <blockquote> |
| <pre>void foo( const path & p );</pre> |
| </blockquote> |
| |
| <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"><b><i>Encoding </i></b><i><b>Conversions</b></i></td> |
| </tr> |
| <tr> |
| <td width="33%"> |
| <p align="center"><i><b>Host system</b></i></td> |
| <td width="33%"> |
| <p align="center"><i><b>char string path arguments</b></i></td> |
| <td width="34%"> |
| <p align="center"><i><b>wide string path arguments</b></i></td> |
| </tr> |
| <tr> |
| <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 |
| <code>codecvt</code> facet.</td> |
| </tr> |
| <tr> |
| <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 |
| <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="Other-changes">Other changes</a></h2> |
| |
| <p><b>Uniform hybrid error handling: </b>The hybrid error handling idiom has |
| been consistently applied to all applicable functions.</p> |
| |
| <h2><a name="Acknowledgements">Acknowledgements</a></h2> |
| |
| <p>Peter Dimov suggested the idea of a single path class that could cope with |
| multiple character types and encodings. Walter Landry contributed both the design and implementation of the copy_any, |
| copy_directory, copy_symlink, and read_symlink functions.</p> |
| |
| <hr> |
| <p>Revised |
| <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->18 February, 2010<!--webbot bot="Timestamp" endspan i-checksum="40538" --></p> |
| |
| <p>© Copyright Beman Dawes, 2008</p> |
| <p> Use, modification, and distribution are subject to 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> |
| |
| </body> |
| |
| </html> |