libs/filesystem/doc/v3.html

   1 <html>
   2
   3 <head>
   4 <meta name="GENERATOR" content="Microsoft FrontPage 5.0">
   5 <meta name="ProgId" content="FrontPage.Editor.Document">
   6 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
   7 <title>Filesystem V3 Intro</title>
   8 <link href="styles.css" rel="stylesheet">
   9
  10 <body>
  11
  12 <table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111">
  13   <tr>
  14     <td width="277">
  15 <a href="../../../index.htm">
  16 <img src="../../../boost.png" alt="boost.png (6897 bytes)" align="middle" width="300" height="86" border="0"></a></td>
  17     <td align="middle">
  18     <font size="7">Filesystem
  19     Version 3<br>
  20     Introduction</font></td>
  21   </tr>
  22 </table>
  23
  24 <table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse"
  25  bordercolor="#111111" bgcolor="#D7EEFF" width="100%">
  26   <tr>
  27     <td><a href="index.htm">Home</a> &nbsp;&nbsp;
  28     <a href="tutorial.html">Tutorial</a> &nbsp;&nbsp;
  29     <a href="reference.html">Reference</a> &nbsp;&nbsp;
  30     <a href="faq.htm">FAQ</a> &nbsp;&nbsp;
  31     <a href="release_history.html">Releases</a> &nbsp;&nbsp;
  32     <a href="portability_guide.htm">Portability</a> &nbsp;&nbsp;
  33     <a href="v3.html">V3 Intro</a> &nbsp;&nbsp;
  34     <a href="v3_design.html">V3 Design</a> &nbsp;&nbsp;
  35     <a href="deprecated.html">Deprecated</a> &nbsp;&nbsp;
  36     <a href="issue_reporting.html">Bug Reports </a>&nbsp;&nbsp;
  37     </td>
  38 </table>
  39
  40 <h1>Boost Filesystem Version 3</h1>
  41
  42 <p>Version 3 is a major revision of the Boost Filesystem library. Important
  43 changes include:</p>
  44
  45 <ul>
  46   <li>A single class <code>path</code> handles all aspects of
  47   internationalization, replacing the previous template and its <code>path</code>
  48   and <code>wpath</code> instantiations. Character types <code>char</code>,
  49   <code>wchar_t</code>, <code>char16_t</code>, and <code>char32_t</code> are
  50   supported. This is a major simplification of the path abstraction,
  51   particularly for functions that take path arguments.<br>
  52 &nbsp;</li>
  53   <li>New <code>class path</code> members include:<br>
  54 &nbsp;<ul>
  55   <li><code><a href="reference.html#path-has_stem">has_stem</a>()</code></li>
  56   <li><code><a href="reference.html#path-has_extension">has_extension</a>()</code></li>
  57   <li><code><a href="reference.html#path-is_absolute">is_absolute</a>()</code>. This renames <code>is_complete()</code>, which
  58   is now deprecated.</li>
  59   <li><code><a href="reference.html#path-is_relative">is_relative</a>()</code></li>
  60   <li><code><a href="reference.html#path-make_preferred">make_preferred</a>()<br>
  61 &nbsp;</code></li>
  62 </ul>
  63
  64   </li>
  65   <li>New or improved operations functions include:<br>
  66 &nbsp;<ul>
  67     <li><code><a href="reference.html#absolute">absolute</a>()</code>. This replaces the operations function <code>
  68   complete()</code>, which is now deprecated. Semantics are now provided for a
  69     Windows corner case where the <code>base</code> argument was not an absolute
  70     path. Previously this resulted in an exception being thrown.</li>
  71     <li><code><a href="reference.html#create_symlink">create_symlink</a>()</code> now supported on both POSIX and Windows.</li>
  72     <li><code><a href="reference.html#read_symlink">read_symlink</a>()</code> function added. Supported on both POSIX and
  73     Windows. Used to read the contents of a symlink itself.</li>
  74     <li><code><a href="reference.html#resize_file">resize_file</a>()</code> function added. Supported on both POSIX and
  75     Windows. Used to shrink or grow a regular file.</li>
  76     <li><code><a href="reference.html#unique_path">unique_path</a>()</code> function added. Supported on both POSIX and
  77     Windows. Used to generate a secure temporary pathname.<br>
  78 &nbsp;</li>
  79   </ul>
  80   </li>
  81   <li>Support for error reporting via <code>error_code</code> is now uniform
  82   throughout the operations functions.<br>
  83 &nbsp;</li>
  84   <li>Documentation has been reworked, including re-writes of major portions.<br>
  85 &nbsp;</li>
  86   <li>A new <a href="tutorial.html">Tutorial</a> provides a hopefully much
  87   gentler and more complete introduction for new users. Current users might want
  88   to review the <a href="tutorial.html">three sections related to class path</a>.</li>
  89 </ul>
  90
  91 <h2>Deprecated names and other features</h2>
  92
  93 <p>See the <a href="deprecated.html">Deprecated Features page</a> for transition
  94 aids that allow much existing code to compile without change using Version 3.</p>
  95
  96 <h2>Breaking changes</h2>
  97
  98 <p>To ease the transition, Versions 2 and 3 will both be included in the next
  99 several Boost releases. Version 2 will be the default version for one release
 100 cycle, and then Version 3 will become the default version.</p>
 101 <h3>Class <code>path</code></h3>
 102 <ul>
 103   <li>Class template <code>basic_path</code> and its specializations are
 104   replaced by a single <code>class path</code>. Thus any code, such as
 105   overloaded functions, that depends on <code>path</code> and <code>wpath</code>
 106   being two distinct types will fail to compile and must be restructured.
 107   Restructuring may be as simple as removing one of the overloads, but also
 108   might require more complex redesign.<br>
 109 &nbsp;</li>
 110   <li>Certain functions now return <code>path</code> objects rather than <code>
 111   string or wstring</code> objects:<ul>
 112     <li><code>root_name()</code></li>
 113     <li><code>root_directory()</code></li>
 114     <li><code>filename()</code></li>
 115     <li><code>stem()</code></li>
 116     <li><code>extension()</code></li>
 117   </ul>
 118   <p>Not all uses will fail; if the function is being called in a context that
 119   accepts a <code>path</code>, all is well. If the result is being used in a
 120   context requiring a <code>std::string</code> or <code>std::wstring</code>,
 121   then <code>.string()</code> or <code>.wstring()</code> respectively must be
 122   appended to the function call.<br>
 123 &nbsp;</li>
 124   <li>&nbsp;<code>path::iterator::value_type</code> and&nbsp; <code>
 125   path::const_iterator::value_type</code> is <code>path</code> rather than <code>
 126   basic_string</code>.</li>
 127 </ul>
 128 <h3>Compiler support</h3>
 129 <ul>
 130   <li>Compilers and standard libraries that do not fully support wide characters
 131   and wide character strings (<code>std::wstring</code>) are no longer
 132   supported.<br>
 133 &nbsp;</li>
 134   <li>Cygwin versions prior to 1.7 are no longer supported because they lack
 135   wide string support. Cygwin now compiles only for the Windows API and path
 136   syntax.<br>
 137 &nbsp;</li>
 138   <li>MinGW versions not supporting wide strings are no longer supported.<br>
 139 &nbsp;</li>
 140   <li>Microsoft VC++ 7.1 and earlier are no longer supported.</li>
 141 </ul>
 142
 143 <hr>
 144 <p>&copy; Copyright Beman Dawes, 2009</p>
 145 <p>Distributed under the Boost Software License, Version 1.0. See
 146 <a href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/LICENSE_1_0.txt</a></p>
 147 <p>Revised
 148 <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B %Y" startspan -->29 December 2014<!--webbot bot="Timestamp" endspan i-checksum="39176" --></p>
 149
 150 </body>
 151
 152 </html>