forked from boostorg/filesystem
-
Notifications
You must be signed in to change notification settings - Fork 0
/
v3_design.html
199 lines (172 loc) · 7.65 KB
/
v3_design.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
<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=utf-8">
<title>Filesystem V3 Design</title>
<link href="styles.css" rel="stylesheet">
</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">Home</a>
<a href="tutorial.html">Tutorial</a>
<a href="reference.html">Reference</a>
<a href="faq.htm">FAQ</a>
<a href="release_history.html">Releases</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>
<a href="issue_reporting.html">Bug Reports </a>
</td>
</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 -->29 December, 2014<!--webbot bot="Timestamp" endspan i-checksum="38652" --></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>