mirror of
https://github.com/boostorg/filesystem.git
synced 2026-01-30 20:02:10 +00:00
284 lines
13 KiB
HTML
284 lines
13 KiB
HTML
<html>
|
|
|
|
<head>
|
|
<meta http-equiv="Content-Language" content="en-us">
|
|
<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
|
|
<meta name="ProgId" content="FrontPage.Editor.Document">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
|
|
<title>Boost Filesystem operations.hpp Header</title>
|
|
</head>
|
|
|
|
<body bgcolor="#FFFFFF">
|
|
|
|
<h1>
|
|
<img border="0" src="../../../c++boost.gif" align="center" width="277" height="86"><a href="../../../boost/filesystem/operations.hpp">boost/filesystem/operations.hpp</a></h1>
|
|
|
|
<p><a href="#Introduction">Introduction</a><br>
|
|
<a href="#Synopsis">Header synopsis</a><br>
|
|
<a href="#Class directory_iterator">Class directory_iterator</a><br>
|
|
<a href="#constructors">Constructors</a><br>
|
|
<a href="#destructor">Destructor</a><br>
|
|
<a href="#other functions">Other functions</a><br>
|
|
<a href="#Non-member functions">Non-member functions</a><br>
|
|
<a href="#exists">exists</a><br>
|
|
<a href="#is_directory">is_directory</a><br>
|
|
<a href="#is_empty">is_empty</a><br>
|
|
<a href="#create_directory">create_directory</a><br>
|
|
<a href="#remove">remove</a><br>
|
|
<a href="#remove_all">remove_all</a><br>
|
|
<a href="#rename">rename</a><br>
|
|
<a href="#copy_file">copy_file</a><br>
|
|
<a href="#initial_directory">initial_directory</a></p>
|
|
|
|
<h2><a name="Introduction">Introduction</a></h2>
|
|
|
|
<p>The <a href="../../../boost/filesystem/operations.hpp">
|
|
boost/filesystem/operations.hpp</a> header provides operations on files and
|
|
directories.</p>
|
|
|
|
<p>These operations traffic in paths; see <a href="path.htm">
|
|
boost/filesystem/path.hpp documentation</a>.</p>
|
|
|
|
<p>For file I/O streams, see <a href="fstream.htm">boost/filesystem/fstream.hpp
|
|
documentation</a>.</p>
|
|
|
|
<p>As with all Filesystem Library components, errors may result in <i>
|
|
<a href="exception.htm">filesystem_error</a></i> or <i>std::bad_alloc</i>
|
|
exceptions being thrown. See <a href="reference.htm#Requirements">Requirements</a>.</p>
|
|
|
|
<h2>Header <a href="../../../boost/filesystem/operations.hpp">boost/filesystem/operations.hpp</a>
|
|
<a name="Synopsis">synopsis</a></h2>
|
|
<pre>namespace boost
|
|
{
|
|
namespace filesystem
|
|
{
|
|
|
|
class <a href="#Class directory_iterator">directory_iterator</a>
|
|
{
|
|
public:
|
|
typedef <a href="path.htm">path</a> value_type;
|
|
typedef std::ptrdiff_t difference_type;
|
|
typedef path * pointer;
|
|
typedef path & reference;
|
|
typedef std::input_iterator_tag iterator_category;
|
|
|
|
<a href="#constructors">directory_iterator</a>();
|
|
explicit <a href="#constructors">directory_iterator</a>( const path & directory_ph );
|
|
|
|
<a href="#destructor">~directory_iterator</a>();
|
|
|
|
// <a href="#other functions">other functions</a>
|
|
// ...
|
|
};
|
|
|
|
bool <a href="#exists">exists</a>( const path & ph );
|
|
bool <a href="#is_directory">is_directory</a>( const path & ph );
|
|
bool <a href="#is_empty">is_empty</a>( const path & ph );
|
|
|
|
void <a href="#create_directory">create_directory</a>( const path & directory_ph );
|
|
void <a href="#remove">remove</a>( const path & ph );
|
|
unsigned long <a href="#remove_all">remove_all</a>( const path & ph );
|
|
void <a href="#rename">rename</a>( const path & from_path,
|
|
const path & to_path );
|
|
void <a href="#copy_file">copy_file</a>( const path & from_file_ph,
|
|
const path & to_file_ph );
|
|
|
|
const path & <a href="#initial_directory">initial_directory</a>();
|
|
|
|
} // namespace filesystem
|
|
} // namespace boost
|
|
</pre>
|
|
|
|
<h2><a name="Class directory_iterator">Class directory_iterator</a></h2>
|
|
|
|
<p>Class <i>directory_iterator</i> provides a C++ standard conforming input
|
|
iterator which accesses the contents of a <a href="reference.htm#directory">
|
|
directory</a>. </p>
|
|
|
|
<p>The value type is <i><a href="path.htm">boost::filesystem::path</a></i>, so
|
|
dereferencing a <i>directory_iterator</i> yields a <a href="reference.htm#path">
|
|
path</a> to a file or directory contained within the directory represented by
|
|
the directory-path argument supplied at construction. The path returned by
|
|
dereferencing a a <i>directory_iterator</i> is composed by appending the name of
|
|
the directory entry to the directory path supplied at construction.</p>
|
|
|
|
<p>A path returned by dereferencing a <i>directory_iterator</i> is, if
|
|
representing a directory, suitable for use as an argument to Filesystem Library
|
|
functions specified as accepting paths or directory paths. If not representing a
|
|
directory, the dereferenced path is suitable for use as an argument to
|
|
Filesystem Library functions specified as accepting paths or file paths, or C++
|
|
Standard Library functions specified as taking file names. The leaf of a path
|
|
returned by dereferencing a <i>directory_iterator</i> will never be <code>".."</code>
|
|
or <code>"."</code>.</p>
|
|
|
|
<p><b>Note:</b> The implication of the above requirement is that if a operating
|
|
system's directories can contain entries which are not usable by Filesystem
|
|
Library or Standard Library functions, these entries will be skipped during
|
|
directory iteration. Such entries are by definition non-portable, but can always
|
|
be accessed via the native operating system API if required.</p>
|
|
|
|
<h3><a name="constructors">Constructors</a></h3>
|
|
<blockquote>
|
|
|
|
<p><code>directory_iterator();</code></p>
|
|
|
|
<p><b>Effects:</b> Constructs a <i>directory_iterator</i> having the <i>
|
|
past-the-end</i> value as described in the C++ standard, section 24.1.</p>
|
|
|
|
<p><code>explicit directory_iterator( const path & directory_ph );</code></p>
|
|
|
|
<p><b>Effects:</b> Constructs a <i>directory_iterator</i> with a value
|
|
representing the first path in <i>directory_ph</i>, or if <code>
|
|
empty(directory_ph)</code>, the <i>past-the-end</i> value.</p>
|
|
</blockquote>
|
|
|
|
<h3><a name="destructor">Destructor</a></h3>
|
|
|
|
<blockquote>
|
|
|
|
<p><code>~directory_iterator();</code></p>
|
|
|
|
<p>If <code>*this == directory_iterator()</code>, the destructor may possibly
|
|
throw an exception. Otherwise, the iterator has the <i>past-the-end</i>
|
|
value, and the destructor is guaranteed to never throw an exception.</p>
|
|
|
|
<p><b>Effects:</b> Destroys *this</p>
|
|
|
|
</blockquote>
|
|
|
|
<h3><a name="other functions">Other functions</a></h3>
|
|
|
|
<p>Class <i>directory_iterator</i> also supplies all the other functions
|
|
required by the C++ standard clause 24 for input iterators, such as <i>operator==</i>,
|
|
<i>operator++</i>, and <i>operator*</i>.</p>
|
|
|
|
<h2><a name="Non-member functions">Non-member functions</a></h2>
|
|
|
|
<p>
|
|
The non-member functions provide common operations on files and directories.
|
|
They follow traditional practice of the C and C++ standard libraries, except
|
|
they:</p>
|
|
|
|
<ul>
|
|
<li>Traffic in <i>paths</i> rather than <code>char*</code>'s, for much
|
|
enhanced portability.</li>
|
|
<li>Report errors by throwing exceptions, for safer and better error handling.</li>
|
|
<li>Tighten specifications slightly, for improved portability.</li>
|
|
</ul>
|
|
|
|
<p>
|
|
<b>Rationale:</b> Functions which already exist in the C++ Standard Library,
|
|
such as <i><a href="#remove">remove()</a></i> and <i><a href="#rename">rename()</a></i>,
|
|
retain the same names and general behavior in the Filesystem Library, to
|
|
minimize surprises.</p>
|
|
|
|
<p>
|
|
<b>Naming Rationale:</b> See class <i>path</i>
|
|
<a href="path.htm#Naming Rationale">Naming Rationale</a>.</p>
|
|
|
|
<h3><a name="exists">exists</a></h3>
|
|
<blockquote>
|
|
<p><code>bool exists( const path & ph );</code></p>
|
|
<p><b>Returns:</b> True if the operating system reports the path
|
|
represented by <i>ph</i> exists, else false.</p>
|
|
<p><b>Note: </b>Even if <i>exists( ph ) == true</i>, there is no guarantee that it
|
|
will be possible to perform other operations on the file or directory. Access
|
|
rights or other security concerns, for example, may cause other operations to
|
|
fail.</p>
|
|
</blockquote>
|
|
<h3><a name="is_directory">is_directory</a></h3>
|
|
<blockquote>
|
|
<p><code>bool is_directory( const path & ph );</code></p>
|
|
<p><b>Returns:</b> True if the operating system reports the path represented by
|
|
<i>ph</i> is a directory, else false.</p>
|
|
<p><b>Throws:</b> if <code>!exists(ph)</code></p>
|
|
<p><b>Rationale:</b> Treating <code>!exists(ph)</code> as an exception rather
|
|
than just returning false came about because in real code <code>!exists(ph)</code>
|
|
has
|
|
often been the first indicate of a programming error. A compound function returning <code>
|
|
exists(ph) && is_directory(ph)</code> can always be added later.</p>
|
|
</blockquote>
|
|
<h3><a name="is_empty">is_empty</a></h3>
|
|
<blockquote>
|
|
<p><code>bool is_empty( const path & ph );</code></p>
|
|
<p><b>Returns:</b> True if the operating system reports the path represented by
|
|
<i>ph</i> is an empty file or empty directory, else false.</p>
|
|
<p><b>Throws:</b> if <code>!exists(path)</code></p>
|
|
</blockquote>
|
|
<h3><a name="create_directory">create_directory</a></h3>
|
|
<blockquote>
|
|
<p><code>void create_directory( const path & & directory_ph );</code></p>
|
|
<p><b>Postcondition:</b> <code>exists(directory_ph) &&
|
|
is_directory(directory_ph) && is_empty(directory_ph)</code></p>
|
|
<p><b>Throws: </b>if <code>exists(directory_ph)) || !exists(branch(directory_ph))</code></p>
|
|
</blockquote>
|
|
<h3><a name="remove">remove</a></h3>
|
|
<blockquote>
|
|
<p><code>void remove( const path & ph );</code></p>
|
|
<p><b>Postcondition:</b> <code>!exists( ph )</code></p>
|
|
<p><b>Throws:</b> if <code>!exists(ph) || (is_directory(ph) && !is_empty(ph))</code></p>
|
|
</blockquote>
|
|
<h3><a name="remove_all">remove_all</a></h3>
|
|
<blockquote>
|
|
<p><code>unsigned long remove_all( const path & ph );</code></p>
|
|
<p><b>Postcondition:</b> <code>!exists( ph )</code></p>
|
|
<p><b>Returns:</b> The number of files and directories removed.</p>
|
|
</blockquote>
|
|
<h3><a name="rename">rename</a></h3>
|
|
<blockquote>
|
|
<p><code>void rename( const path & from_ph, const path & to_ph
|
|
);</code></p>
|
|
<p><b>Effects:</b> Changes the name of file or directory <i>from_ph</i>
|
|
to <i>to_ph</i>.</p>
|
|
<p><b>Postconditions:</b> <code>!exists(from_ph) && exists(to_ph)</code>,
|
|
and the file or directory contents and attributes are otherwise unchanged.</p>
|
|
<p><b>Throws:</b> if <code>!exists(from_ph) || exists(to_ph) || !exists(branch(to_ph))</code></p>
|
|
<p><b>Note:</b> <i>rename</i> is effectively the same operation as <i>move</i>.</p>
|
|
<p><b>Note:</b> If <code>branch(from_path)</code> resolves to the same directory
|
|
as <code>branch(to_ph)</code>, then <code>leaf(from_ph)</code> must not be
|
|
the same name as <code>leaf(to_ph)</code>, but if the branch directories are
|
|
different, it doesn't matter if the leaf names are the same.</p>
|
|
<p><b>Note:</b> Some operating systems with multi-rooted filesystems
|
|
representing different drives, devices, or volumes, do not allow <i>rename</i>
|
|
operations between roots . Implementations should not take heroic efforts, such
|
|
as switching to a copy mode, to make an otherwise failing <i>rename </i>succeed
|
|
across drives, devices, or volumes. </p>
|
|
</blockquote>
|
|
<h3><a name="copy_file">copy_file</a></h3>
|
|
<blockquote>
|
|
<p><code>void copy_file( const path & from_file_ph, const path &
|
|
to_file_ph );</code></p>
|
|
<p><b>Effects:</b> Copies the file represented by <i>from_file_ph</i> to <i>
|
|
to_file_ph</i>.</p>
|
|
<p><b>Throws:</b> if <code>!exists(from_file_ph) || directory(from_file_ph)
|
|
|| exists(to_file_ph) || !exist(branch(to_path))</code></p>
|
|
</blockquote>
|
|
<h3><a name="initial_directory">initial_directory</a></h3>
|
|
<blockquote>
|
|
<p><code>const path & initial_directory();</code></p>
|
|
<p><b>Effects:</b> The first time the function is called, stores an absolute
|
|
directory path.</p>
|
|
<p>The preferred value for the stored path is the initial working directory path when <i>
|
|
main()</i> was called. Implementations are permitted, however, to store the
|
|
current working directory at the time of the first call to <i>initial_directory()</i>. If neither of these actions is possible, a diagnostic
|
|
is required.</p>
|
|
<p><b>Returns:</b> The stored path.</p>
|
|
<p><b>Rationale:</b> The semantics, in effect, turn a global variable into
|
|
a safer global constant. The preferred implementation requires runtime library
|
|
support, so alternate semantics are supplied for those implementations which
|
|
cannot change an existing the runtime library.</p>
|
|
<p><b>Note:</b> It would be good practice in a program dependent on <i>
|
|
initial_directory()</i> to call it immediately upon entering<i> main()</i>. That
|
|
protects against another function altering the current working
|
|
directory (using a native platform function) before the first call to <i>
|
|
initial_directory()</i>.</p>
|
|
|
|
</blockquote>
|
|
<hr>
|
|
<p>© Copyright Beman Dawes, 2002</p>
|
|
<p>Revised
|
|
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->01 August, 2002<!--webbot bot="Timestamp" endspan i-checksum="34406" --></p>
|
|
|
|
</body>
|
|
|
|
</html> |