Filesystem Version 3 Introduction

Boost Filesystem Version 3

Version 3 is a major revision of the Boost Filesystem library. Important changes include:

• A single class path handles all aspects of internationalization, replacing the previous template and its path and wpath instantiations. Character types char, wchar_t, char16_t, and char32_t are supported. This is a major simplification of the path abstraction, particularly for functions that take path arguments.
   
• New class path members include:
   
  • has_stem()
  • has_extension()
  • is_absolute(). This renames is_complete(), which is now deprecated.
  • is_relative()
  • make_preferred()
 
• New or improved operations functions include:
   
  • absolute(). This replaces the operations function complete(), which is now deprecated. Semantics are now provided for a Windows corner case where the base argument was not an absolute path. Previously this resulted in an exception being thrown.
  • create_symlink() now supported on both POSIX and Windows.
  • read_symlink() function added. Supported on both POSIX and Windows. Used to read the contents of a symlink itself.
  • resize_file() function added. Supported on both POSIX and Windows. Used to shrink or grow a regular file.
  • unique_path() function added. Supported on both POSIX and Windows. Used to generate a secure temporary pathname.
     
• Support for error reporting via error_code is now uniform throughout the operations functions.
   
• Documentation has been reworked, including re-writes of major portions.
   
• A new Tutorial provides a hopefully much gentler and more complete introduction for new users. Current users might want to review the three sections related to class path.

Deprecated names and other features

See the Deprecated Features page for transition aids that allow much existing code to compile without change using Version 3.

Breaking changes

To ease the transition, Versions 2 and 3 will both be included in the next several Boost releases. Version 2 will be the default version for one release cycle, and then Version 3 will become the default version.

Class path

• Class template basic_path and its specializations are replaced by a single class path. Thus any code, such as overloaded functions, that depends on path and wpath being two distinct types will fail to compile and must be restructured. Restructuring may be as simple as removing one of the overloads, but also might require more complex redesign.
   
• Certain functions now return path objects rather than string or wstring objects:
  • root_name()
  • root_directory()
  • filename()
  • stem()
  • extension()

  Not all uses will fail; if the function is being called in a context that accepts a path, all is well. If the result is being used in a context requiring a std::string or std::wstring, then .string() or .wstring() respectively must be appended to the function call.
   

•  path::iterator::value_type and  path::const_iterator::value_type is path rather than basic_string.

Compiler support

• Compilers and standard libraries that do not fully support wide characters and wide character strings (std::wstring) are no longer supported.
   
• Cygwin versions prior to 1.7 are no longer supported because they lack wide string support. Cygwin now compiles only for the Windows API and path syntax.
   
• MinGW versions not supporting wide strings are no longer supported.
   
• Microsoft VC++ 7.1 and earlier are no longer supported.

© Copyright Beman Dawes, 2009

Distributed under the Boost Software License, Version 1.0. See www.boost.org/LICENSE_1_0.txt

Revised 20 February 2011