| 1 | <html> |
|---|
| 2 | |
|---|
| 3 | <head> |
|---|
| 4 | <meta http-equiv="Content-Language" content="en-us"> |
|---|
| 5 | <meta name="GENERATOR" content="Microsoft FrontPage 5.0"> |
|---|
| 6 | <meta name="ProgId" content="FrontPage.Editor.Document"> |
|---|
| 7 | <meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> |
|---|
| 8 | |
|---|
| 9 | <link rel="stylesheet" type="text/css" href="../../../boost.css"> |
|---|
| 10 | |
|---|
| 11 | <title>Boost Filesystem convenience.hpp Header</title> |
|---|
| 12 | </head> |
|---|
| 13 | |
|---|
| 14 | <body bgcolor="#FFFFFF"> |
|---|
| 15 | |
|---|
| 16 | <h1> |
|---|
| 17 | <img border="0" src="../../../boost.png" align="center" width="277" height="86"><a href="../../../boost/filesystem/convenience.hpp">boost/filesystem/convenience.hpp</a></h1> |
|---|
| 18 | |
|---|
| 19 | <p>Header <a href="../../../boost/filesystem/convenience.hpp">convenience.hpp</a> |
|---|
| 20 | provides convenience functions that combine lower-level functions in useful |
|---|
| 21 | ways.</p> |
|---|
| 22 | |
|---|
| 23 | <h2>Contents</h2> |
|---|
| 24 | |
|---|
| 25 | <dl class="index"> |
|---|
| 26 | <dt><a href="#create_directories">create_directories</a> |
|---|
| 27 | <dt><a href="#extension">extension</a> |
|---|
| 28 | <dt><a href="#basename">basename</a> |
|---|
| 29 | <dt><a href="#change_extension">change_extension</a> |
|---|
| 30 | </dl> |
|---|
| 31 | |
|---|
| 32 | <h2 id="create_directories">create_directories</h2> |
|---|
| 33 | |
|---|
| 34 | <blockquote> |
|---|
| 35 | |
|---|
| 36 | <p><code>bool create_directories( const path & ph );</code></p> |
|---|
| 37 | |
|---|
| 38 | <p><b>Precondition:</b> <code>ph.empty() || <br> |
|---|
| 39 | forall p: p == ph || is_parent(p, ph): is_directory(p) || !exists( p )</code> |
|---|
| 40 | </p> |
|---|
| 41 | <p><b>Returns:</b> The value of <code>!exists(ph)</code> prior to the |
|---|
| 42 | establishment of the postcondition.</p> |
|---|
| 43 | |
|---|
| 44 | <p><b>Postcondition:</b> <code>exists(ph) && is_directory(ph)</code></p> |
|---|
| 45 | |
|---|
| 46 | <p><b>Throws:</b> <code>exists(ph) && !is_directory(ph)</code></p> |
|---|
| 47 | |
|---|
| 48 | <p>Contributed by Vladimir Prus.</p> |
|---|
| 49 | |
|---|
| 50 | </blockquote> |
|---|
| 51 | |
|---|
| 52 | <h2 id="extension">extension</h2> |
|---|
| 53 | |
|---|
| 54 | <blockquote> |
|---|
| 55 | |
|---|
| 56 | <p><code>std::string extension( const path & ph );</code></p> |
|---|
| 57 | |
|---|
| 58 | <p><b>Returns:</b> if <code>ph.leaf()</code> contains a dot ('.'), |
|---|
| 59 | returns the substring of <code>ph.leaf()</code> starting from the last dot and |
|---|
| 60 | ending at the string's end. Otherwise, returns empty string. |
|---|
| 61 | <p><b>Rationale:</b> <ul> |
|---|
| 62 | <li>The dot is included in the return value so that it's |
|---|
| 63 | possible to tell if extension is empty or absent. |
|---|
| 64 | <li>It was noted that this definition of extension is probably not sufficient |
|---|
| 65 | when using <a href="http://support.microsoft.com/kb/105763">Alternate Data Streams</a> — |
|---|
| 66 | a filesystem feature specific to NTFS. However, semantics in this case were not |
|---|
| 67 | clear, and the current behavior is still quite useful. |
|---|
| 68 | </ul> |
|---|
| 69 | <p><b>Acknowlegements:</b> Carl Daniel and Pavel Vozenilek noticed and |
|---|
| 70 | discussed the ADS issue. |
|---|
| 71 | |
|---|
| 72 | <p>Contributed by Vladimir Prus.</p> |
|---|
| 73 | |
|---|
| 74 | </blockquote> |
|---|
| 75 | |
|---|
| 76 | <h2 id="basename">basename</h2> |
|---|
| 77 | |
|---|
| 78 | <blockquote> |
|---|
| 79 | |
|---|
| 80 | <p><code>std::string basename( const path & ph );</code></p> |
|---|
| 81 | |
|---|
| 82 | <p><b>Returns:</b> if <code>ph.leaf()</code> contains a dot ('.'), |
|---|
| 83 | returns the substring of <code>ph.leaf()</code> starting from beginning and |
|---|
| 84 | ending at the last dot (the dot is not included). Otherwise, returns |
|---|
| 85 | <code>ph.leaf()</code> |
|---|
| 86 | |
|---|
| 87 | </p> |
|---|
| 88 | |
|---|
| 89 | <p>Contributed by Vladimir Prus.</p> |
|---|
| 90 | |
|---|
| 91 | </blockquote> |
|---|
| 92 | |
|---|
| 93 | <h2 id="change_extension">change_extension</h2> |
|---|
| 94 | |
|---|
| 95 | <blockquote> |
|---|
| 96 | |
|---|
| 97 | <p><code>path change_extension( const path & ph, const std::string & new_extension );</code></p> |
|---|
| 98 | |
|---|
| 99 | <p><b>Postcondition:</b> <code>basename(return_value) == basename(ph) |
|---|
| 100 | && extension(return_value) == new_extension</code> |
|---|
| 101 | <p><b>Note:</b> It follows from the semantic of <code>extension</code> that |
|---|
| 102 | <code>new_extension</code> should include dot to achieve reasonable results. |
|---|
| 103 | </p> |
|---|
| 104 | <p><b>Rationale:</b> Previously, this functions had |
|---|
| 105 | <code>!ph.leaf().empty()</code> as precondition. It's not clear if it was |
|---|
| 106 | right or wrong. Changing extension of an empty path looks pointless. On the |
|---|
| 107 | other hand, the value of precondition was questionable: one would better place such |
|---|
| 108 | checks at the points where paths are entered by the user. Current decision |
|---|
| 109 | is to drop the precondition.</p> |
|---|
| 110 | |
|---|
| 111 | <p>Contributed by Vladimir Prus.</p> |
|---|
| 112 | |
|---|
| 113 | </blockquote> |
|---|
| 114 | |
|---|
| 115 | |
|---|
| 116 | |
|---|
| 117 | <hr> |
|---|
| 118 | <p>Revised |
|---|
| 119 | <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->11 March, 2004<!--webbot bot="Timestamp" endspan i-checksum="28863" --></p> |
|---|
| 120 | <p>© Copyright Vladimir Prus, 2003</p> |
|---|
| 121 | <p> Use, modification, and distribution are subject to the Boost Software |
|---|
| 122 | License, Version 1.0. (See accompanying file <a href="../../../LICENSE_1_0.txt"> |
|---|
| 123 | LICENSE_1_0.txt</a> or copy at <a href="http://www.boost.org/LICENSE_1_0.txt"> |
|---|
| 124 | www.boost.org/LICENSE_1_0.txt</a>)</p> |
|---|
| 125 | |
|---|
| 126 | </body> |
|---|
| 127 | |
|---|
| 128 | </html> |
|---|
