9a14c37d6f
The directory_options enum reflects the same-named enum from C++20. It is now supported by both directory_iterator and recursive_directory_iterator. In particular, both iterators now support skip_permission_denied option. recursive_directory_iterator is now set to end by default on errors, as required by C++20. An additional directory_options::pop_on_error policy is added to allow the iterator recover from an error. When this option is specified and an error occurs, the iterator repeatedly pops the recursion level until the pop completes successfully or the end state is reached. recursive_directory_iterator that have standard counterparts (level, no_push_pending, no_push_request and no_push) are now deprecated and can be removed by defining BOOST_FILESYSTEM_NO_DEPRECATED. These members will be removed in a future release. Docs and tests updated accordingly. Also, in docs reconstructed release history for the past releases from Boost release notes. Fixes https://github.com/boostorg/filesystem/issues/112 Fixes https://github.com/boostorg/filesystem/issues/113
200 lines
7.6 KiB
HTML
200 lines
7.6 KiB
HTML
<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 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>
|