# boost/filesystem/convenience.hpp

Header convenience.hpp provides convenience functions that combine lower-level functions in useful ways.

## Contents

create_directories
extension
basename
change_extension

## create_directories

> `bool create_directories( const path & ph );`

> Precondition: `ph.empty() ||
> forall p: p == ph || is_parent(p, ph): is_directory(p) || !exists( p )`

> Returns: The value of `!exists(ph)` prior to the establishment of the postcondition.

> Postcondition: `exists(ph) && is_directory(ph)`

> Throws: `exists(ph) && !is_directory(ph)`

> Contributed by Vladimir Prus.

## extension

> `std::string extension( const path & ph );`

> Returns: if `ph.leaf()` contains a dot ('.'), returns the substring of `ph.leaf()` starting from the last dot and ending at the string's end. Otherwise, returns empty string.

> Rationale:

> - The dot is included in the return value so that it's possible to tell if extension is empty or absent.
> - It was noted that this definition of extension is probably not sufficient when using Alternate Data Streams — a filesystem feature specific to NTFS. However, semantics in this case were not clear, and the current behavior is still quite useful.

> Acknowlegements: Carl Daniel and Pavel Vozenilek noticed and discussed the ADS issue.

> Contributed by Vladimir Prus.

## basename

> `std::string basename( const path & ph );`

> Returns: if `ph.leaf()` contains a dot ('.'), returns the substring of `ph.leaf()` starting from beginning and ending at the last dot (the dot is not included). Otherwise, returns `ph.leaf()`

> Contributed by Vladimir Prus.

## change_extension

> `path change_extension( const path & ph, const std::string & new_extension );`

> Postcondition: `basename(return_value) == basename(ph) && extension(return_value) == new_extension`

> Note: It follows from the semantic of `extension` that `new_extension` should include dot to achieve reasonable results.

> Rationale: Previously, this functions had `!ph.leaf().empty()` as precondition. It's not clear if it was right or wrong. Changing extension of an empty path looks pointless. On the other hand, the value of precondition was questionable: one would better place such checks at the points where paths are entered by the user. Current decision is to drop the precondition.

> Contributed by Vladimir Prus.

Revised 11 March, 2004

© Copyright Vladimir Prus, 2003

Use, modification, and distribution are subject to the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at www.boost.org/LICENSE_1_0.txt)