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> 31 <a href="tutorial.html">Tutorial</a> 32 <a href="reference.html">Reference</a> 33 <a href="faq.htm">FAQ</a> 34 <a href="release_history.html">Releases</a> 35 <a href="portability_guide.htm">Portability</a> 36 <a href="v3.html">V3 Intro</a> 37 <a href="v3_design.html">V3 Design</a> 38 <a href="deprecated.html">Deprecated</a> 39 <a href="issue_reporting.html">Bug Reports </a> 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 61process, and is intended to serve historical purposes. It is not updated to 62reflect 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 67suggested that the<code> basic_path</code> class template was unwieldy, and that a single 68path type that accommodated multiple character types and encodings would be more 69flexible. Although I wasn't willing to stop development at that time to 70explore how this idea might be implemented, or to break from the pattern for 71Internationalization used the C++ standard library, I've often thought about 72Peter's suggestion. With the advent of C++0x <code>char16_t</code> and <code>char32_t</code> 73character 74types, the <code>basic_path</code> class template approach becomes even more unwieldy, so it 75is 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 80accommodate multiple character types and encodings must be written as a 81template. Do-the-right-thing overloads or template metaprogramming must be 82employed to allow arguments to be written as string literals. Here's what it 83looks like:</p> 84 85<blockquote> 86 <pre>template<class Path> 87void foo( const Path & p );</pre> 88 <pre>inline void foo( const path & p ) 89{ 90 return foo<path>( p ); 91} 92inline void foo( const wpath & p ) 93{ 94 return foo<wpath>( p ); 95}</pre> 96</blockquote> 97<p>That's really ugly for such a simple need, and there would be a combinatorial 98explosion if the function took multiple Path arguments and each could be either 99narrow or wide. It gets even worse if the C++0x <code>char16_t</code> and <code> 100char32_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 115simply:</p> 116<blockquote> 117 <pre>void foo( const path & p );</pre> 118</blockquote> 119 120<p>That's a signification reduction in code complexity. Specification becomes 121simpler, too. I believe it will be far easier to teach, and result in much more 122flexible 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 operating system's 172API argument type for paths, no conversion is performed rather than conversion 173to a specified encoding such as one of the Unicode encodings. This avoids 174unintended 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 179been 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 184multiple character types and encodings. Walter Landry contributed both the design 185and implementation of the copy_any, 186copy_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>© Copyright Beman Dawes, 2008</p> 193<p> Use, modification, and distribution are subject to the Boost Software 194License, Version 1.0. See <a href="http://www.boost.org/LICENSE_1_0.txt"> 195www.boost.org/LICENSE_1_0.txt</a></p> 196 197</body> 198 199</html> 200
