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)