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

void create_directories( const path & ph );

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

Postcondition: 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 defintion of extension is probably not sufficient when using Alternate Data Streams — a filesystem feature specific to NTFS. However, semantic in this case was not clear, and the current one is quite usefull still.

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 basename( 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 02 October, 2003

© 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)