Filesystem V3 Intro

| Filesystem Version 3 Introduction

Boost Home Library Home Reference Tutorial FAQ Portability V3 Intro V3 Design Deprecated

# 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 02 July 2010