ceph/src/boost/libs/filesystem/doc/v3_design.html

   1 <html>
   2
   3 <head>
   4 <meta http-equiv="Content-Language" content="en-us">
   5 <meta name="GENERATOR" content="Microsoft FrontPage 5.0">
   6 <meta name="ProgId" content="FrontPage.Editor.Document">
   7 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
   8 <title>Filesystem V3 Design</title>
   9 <link href="styles.css" rel="stylesheet">
  10 </head>
  11
  12 <body>
  13
  14 <table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse"
  15  bordercolor="#111111">
  16   <tr>
  17     <td>
  18 <a href="../../../index.htm">
  19 <img src="../../../boost.png" alt="boost.png (6897 bytes)" align="middle" border="0"
  20  width="300" height="86"></a></td>
  21     <td align="middle">
  22     <font size="7">Filesystem Version 3<br>
  23     Design</font></td>
  24   </tr>
  25 </table>
  26
  27 <table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse"
  28  bordercolor="#111111" bgcolor="#D7EEFF" width="100%">
  29   <tr>
  30     <td><a href="index.htm">Home</a> &nbsp;&nbsp;
  31     <a href="tutorial.html">Tutorial</a> &nbsp;&nbsp;
  32     <a href="reference.html">Reference</a> &nbsp;&nbsp;
  33     <a href="faq.htm">FAQ</a> &nbsp;&nbsp;
  34     <a href="release_history.html">Releases</a> &nbsp;&nbsp;
  35     <a href="portability_guide.htm">Portability</a> &nbsp;&nbsp;
  36     <a href="v3.html">V3 Intro</a> &nbsp;&nbsp;
  37     <a href="v3_design.html">V3 Design</a> &nbsp;&nbsp;
  38     <a href="deprecated.html">Deprecated</a> &nbsp;&nbsp;
  39     <a href="issue_reporting.html">Bug Reports </a>&nbsp;&nbsp;
  40     </td>
  41 </table>
  42
  43 <table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse"
  44  bordercolor="#111111" align="right">
  45   <tr>
  46     <td width="100%" bgcolor="#D7EEFF" align="center">
  47       <i><b>Contents</b></i></td>
  48   </tr>
  49   <tr>
  50     <td width="100%" bgcolor="#E8F5FF">
  51     <a href="#Introduction">Introduction</a><br>
  52     <a href="#Problem">Problem</a><br>
  53     <a href="#Solution">Solution</a><br>
  54     <a href="#Details">Details</a><br>
  55     <a href="#Other-changes">Other changes</a><br>
  56     <a href="#Acknowledgements">Acknowledgements</a></td>
  57   </tr>
  58   </table>
  59
  60 <p><b>Caution:</b> This page documents thinking early in the V3 development
  61 process, and is intended to serve historical purposes. It is not updated to
  62 reflect the current state of the library.</p>
  63
  64 <h2><a name="Introduction">Introduction</a></h2>
  65
  66 <p>During the review of Boost.Filesystem.V2 (Internationalization), Peter Dimov
  67 suggested that the<code> basic_path</code> class template was unwieldy, and that a single
  68 path type that accommodated multiple character types and encodings would be more
  69 flexible. Although I wasn't willing to stop development at that time to
  70 explore how this idea might be implemented, or to break from the pattern for
  71 Internationalization used the C++ standard library, I've often thought about
  72 Peter's suggestion. With the advent of C++0x <code>char16_t</code> and <code>char32_t</code>
  73 character
  74 types, the <code>basic_path</code> class template approach becomes even more unwieldy, so it
  75 is time to revisit the problem in light of Peter's suggestion.</p>
  76
  77 <h2><b><a name="Problem">Problem</a></b></h2>
  78
  79 <p>With Filesystem.V2, a path argument to a user defined function that is to
  80 accommodate multiple character types and encodings must be written as a
  81 template. Do-the-right-thing overloads or template metaprogramming must be
  82 employed to allow arguments to be written as string literals. Here's what it
  83 looks like:</p>
  84
  85 <blockquote>
  86   <pre>template&lt;class Path&gt;
  87 void foo( const Path &amp; p );</pre>
  88   <pre>inline void foo( const path &amp; p )
  89 {
  90   return foo&lt;path&gt;( p );
  91 }
  92 inline void foo( const wpath &amp; p )
  93 {
  94   return foo&lt;wpath&gt;( p );
  95 }</pre>
  96 </blockquote>
  97 <p>That's really ugly for such a simple need, and there would be a combinatorial
  98 explosion if the function took multiple Path arguments and each could be either
  99 narrow or wide. It gets even worse if the C++0x <code>char16_t</code> and <code>
 100 char32_t</code> types are to be supported.</p>
 101
 102 <h2><a name="Solution">Solution</a></h2>
 103
 104 <p>Overview:</p>
 105
 106 <ul>
 107   <li>A single, non-template, <code>class path</code>.</li>
 108   <li>Each member function is a template accommodating the various
 109   applicable character types, including user-defined character types.</li>
 110   <li>Hold the path internally in a string of the type used by the operating
 111   system API; <code>std::string</code> for POSIX, <code>std::wstring</code> for Windows.</li>
 112 </ul>
 113
 114 <p>The signatures presented in <a href="#Problem">Problem</a> collapse to
 115 simply:</p>
 116 <blockquote>
 117   <pre>void foo( const path &amp; p );</pre>
 118 </blockquote>
 119
 120 <p>That's a signification reduction in code complexity. Specification becomes
 121 simpler, too. I believe it will be far easier to teach, and result in much more
 122 flexible user code.</p>
 123
 124 <p>Other benefits:</p>
 125 <ul>
 126   <li>All the polymorphism still occurs at compile time.</li>
 127   <li>Efficiency is increased, in that conversions of the encoding, if required,
 128   only occur once at the time of creation, not each time the path is used.</li>
 129   <li>The size of the implementation code drops approximately in half and
 130   becomes much more readable.</li>
 131 </ul>
 132   <p>Possible problems:</p>
 133 <ul>
 134   <li>The combination of member function templates and implicit constructors can
 135   result in unclear error messages when the user makes simple commonplace coding
 136   errors. This should be much less of a problem with C++ concepts, but in the
 137   meantime work continues to restrict over aggressive templates via enable_if/disable_if.</li>
 138 </ul>
 139   <h2><a name="Details">Details</a></h2>
 140
 141 <table border="1" cellpadding="4" cellspacing="0" style="border-collapse: collapse"
 142  bordercolor="#111111" width="100%">
 143   <tr>
 144     <td width="33%" colspan="3">
 145     <p align="center"><b><i>Encoding </i></b><i><b>Conversions</b></i></td>
 146   </tr>
 147   <tr>
 148     <td width="33%">
 149     <p align="center"><i><b>Host system</b></i></td>
 150     <td width="33%">
 151     <p align="center"><i><b>char string path arguments</b></i></td>
 152     <td width="34%">
 153     <p align="center"><i><b>wide string path arguments</b></i></td>
 154   </tr>
 155   <tr>
 156     <td width="33%">Systems with <code>char</code> as the native API path character type (i.e.
 157     POSIX-like systems)</td>
 158     <td width="33%">No conversion.</td>
 159     <td width="34%">Conversion occurs, performed by the current path locale's
 160     <code>codecvt</code> facet.</td>
 161   </tr>
 162   <tr>
 163     <td width="33%">Systems with <code>wchar_t</code> as the native API path character type
 164     (i.e. Windows-like systems).</td>
 165     <td width="33%">Conversion occurs, performed by the current path locale's
 166     <code>codecvt</code> facet.</td>
 167     <td width="34%">No conversion.</td>
 168   </tr>
 169 </table>
 170
 171 <p>When a class path function argument type matches the the operating system's
 172 API argument type for paths, no conversion is performed rather than conversion
 173 to a specified encoding such as one of the Unicode encodings. This avoids
 174 unintended consequences, etc.</p>
 175
 176 <h2><a name="Other-changes">Other changes</a></h2>
 177
 178 <p><b>Uniform hybrid error handling: </b>The hybrid error handling idiom has
 179 been consistently applied to all applicable functions.</p>
 180
 181 <h2><a name="Acknowledgements">Acknowledgements</a></h2>
 182
 183 <p>Peter Dimov suggested the idea of a single path class that could cope with
 184 multiple character types and encodings. Walter Landry contributed both the design
 185 and implementation of the copy_any,
 186 copy_directory, copy_symlink, and read_symlink functions.</p>
 187
 188 <hr>
 189 <p>Revised
 190 <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->29 December, 2014<!--webbot bot="Timestamp" endspan i-checksum="38652" --></p>
 191
 192 <p>&copy; Copyright Beman Dawes, 2008</p>
 193 <p> Use, modification, and distribution are subject to the Boost Software
 194 License, Version 1.0. See <a href="http://www.boost.org/LICENSE_1_0.txt">
 195 www.boost.org/LICENSE_1_0.txt</a></p>
 196
 197 </body>
 198
 199 </html>