mirror of
https://github.com/boostorg/filesystem.git
synced 2026-02-01 08:32:08 +00:00
255 lines
13 KiB
HTML
255 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 path.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/path.hpp">boost/filesystem/path.hpp</a></h1>
|
|
|
|
<p>
|
|
<a href="#Introduction">Introduction</a><br>
|
|
<a href="#Grammar">Grammar for generic path strings</a><br>
|
|
<a href="#Canonical">Canonical form</a><br>
|
|
<a href="#synopsis">Header synopsis</a><br>
|
|
<a href="#Class path">Class path</a><br>
|
|
<a href="#Member">Member functions</a><br>
|
|
<a href="#Non-member functions">Non-member functions</a></p>
|
|
<h2><a name="Introduction">Introduction</a></h2>
|
|
|
|
<p>Many Filesystem Library functions traffic in objects of class <i>path</i>,
|
|
provided by this header. Non-member functions for error checking are also
|
|
supplied.</p>
|
|
|
|
<p>For actual operations on files and directories, see <a href="operations.htm">
|
|
boost/filesystem/operations.hpp documentation</a>.</p>
|
|
|
|
<p>For file I/O stream operations, 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><a name="Class path">Class path</a></h2>
|
|
<p>Class <i>path</i> provides for portable mechanism for representing
|
|
<a href="reference.htm#path">paths</a> in C++ programs. Class <i>path</i>
|
|
is concerned with the lexical and syntactic aspects of a path, regardless of
|
|
whether or not such a path currently exists in the operating system's
|
|
filesystem. </p>
|
|
<p><b>Rationale:</b> If filesystem functions trafficked in <i>std::strings</i> or C-style strings, the
|
|
functions
|
|
would provide only an illusion of portability since the function calls would be
|
|
portable but the strings they operate on would not be portable.</p>
|
|
<h2><a name="Conceptual model">Conceptual model</a> of a path</h2>
|
|
<p>An object of class <i>path</i> can be conceptualized as containing a vector
|
|
of strings, where each string contains the name of a directory, or, in the case
|
|
of the last string, a directory or file. Such a path representation is
|
|
completely independent of any particular representation of the path as a single
|
|
string.</p>
|
|
<p>There is no requirement that an implementation of class <i>path</i> actually
|
|
contain a vector of strings, but conceptualizing the contents that way provides
|
|
a completely portable way to reason about paths.</p>
|
|
<p>So that programs can portably express paths as a single string, class <i>path</i>
|
|
defines a <a href="#Grammar">grammar</a> for a portable generic path string
|
|
format, and supplies a constructor and append operations taking such strings as
|
|
arguments. Because user input or third-party library functions may supply path
|
|
strings formatted according to operating system specific rules, an additional
|
|
constructor is provided which takes a system-specific format as an argument.</p>
|
|
<p>Access functions are provided to retrieve the contents of a object of class
|
|
<i>path</i> formatted as a portable path string, a directory path string using
|
|
the operating system's format, and a file path string using the operating
|
|
system's format. Additional access functions retrieve specific portions of
|
|
the contained path.</p>
|
|
<p></p>
|
|
<p></p>
|
|
<p></p>
|
|
<p></p>
|
|
<p></p>
|
|
<p></p>
|
|
<h2><a name="Grammar">Grammar</a> for portable generic path string</h2>
|
|
<p>The grammar is specified in extended BNF, with terminal symbols in quotes:
|
|
</p>
|
|
<blockquote>
|
|
<pre>path ::= [system-specific-root] [relative-path] </pre>
|
|
<pre>relative-path ::= element { "/" element } </pre>
|
|
<pre>element ::= name | parent-directory </pre>
|
|
<pre>parent-directory ::= ".." </pre>
|
|
<pre>name ::= char { char }</pre>
|
|
</blockquote>
|
|
<p><i>system-specific-root</i> grammar is implementation-defined. <i>
|
|
system-specific-root</i> must not be present in generic input (the undecorated
|
|
<i>path</i> constructors); it may be part of the strings returned by <i>path</i>
|
|
member functions, and may be present in the argument to <i>path</i> constructors
|
|
with the <i><a href="#system_specific">system_specific</a></i> decorator.</p>
|
|
<p>Although implementation-defined, it is desirable that <i>
|
|
system-specific-root</i> have a grammar which is distinguishable from other grammar elements,
|
|
and follow the conventions of the operating system.</p>
|
|
<p>Whether or not a generic path string is actually portable will depend on the
|
|
names used. See <font color="#FF0000"><i>to be provided</i></font></p>
|
|
<h2><a name="Canonical">Canonical</a> form</h2>
|
|
<p>Adjacent <i>name, parent-directory</i> elements in <code>m_name</code>
|
|
have been recursively removed. </p>
|
|
<h2>Header <a href="../../../boost/filesystem/path.hpp">
|
|
boost/filesystem/path.hpp</a> <a name="synopsis">synopsis</a></h2>
|
|
<pre>namespace boost
|
|
{
|
|
namespace filesystem
|
|
{
|
|
class path
|
|
{
|
|
public:
|
|
enum format { <a name="system_specific">system_specific</a> };
|
|
|
|
// compiler generates copy constructor,
|
|
// copy assignment, and destructor
|
|
|
|
// constructors:
|
|
<a href="#constructors">path</a>();
|
|
<a href="#constructors">path</a>( const std::string & src );
|
|
<a href="#constructors">path</a>( const char * src );
|
|
<a href="#constructors">path</a>( const std::string & src, format );
|
|
<a href="#constructors">path</a>( const char * src, format );
|
|
|
|
// append operations:
|
|
path & <a href="#operator-shift-equal">operator<<=</a>( const path & rhs );
|
|
const path <a href="#operator-shift">operator<<</a> ( const path & rhs ) const;
|
|
|
|
// query functions:
|
|
bool <a href="#empty">empty()</a> const;
|
|
const std::string & <a href="#generic_path">generic_path</a>() const;
|
|
const char * <a href="#file_c_str">file_c_str</a>() const;
|
|
const char * <a href="#directory_c_str">directory_c_str</a>() const;
|
|
const std::string <a href="#leaf">leaf</a>() const;
|
|
const path <a href="#branch">branch</a>() const;
|
|
|
|
private:
|
|
std::vector<std::string> m_name; // for exposition only
|
|
};
|
|
}
|
|
}</pre>
|
|
<h2><a name="Member">Member</a> functions</h2>
|
|
<p>For the sake of exposition, class <i>path</i> member functions are described
|
|
as if the class contains a private member <code>std::vector<std::string> m_name</code>.
|
|
Actual implementations may differ.</p>
|
|
<p><b>Rationale:</b> Return types of query functions have been chosen to match
|
|
the types needed by important uses, and to be efficient in common
|
|
implementations.</p>
|
|
<p><b>Note:</b> There is no guarantee that a <i>path</i> object represents a
|
|
path which would be considered valid by the operating system. A path might be
|
|
invalid to the operating system because it contains invalid names (too long,
|
|
invalid characters, and so on), or because it is a partial path still as yet
|
|
unfinished by the program. An invalid path will normally be detected at time of
|
|
use, such as by one of the Filesystem Library's <a href="operations.htm">
|
|
operations</a> or <a href="fstream.htm">fstream</a> functions.</p>
|
|
<p><b>Portability Warning:</b> There is no guarantee that a <i>path</i> object
|
|
represents a path which would be portable to other operating systems. A path
|
|
might be non-portable because it contains names which other operating systems
|
|
consider too long or containing invalid characters.
|
|
<a href="???????to-be-supplied">Validity checking functions</a> are supplied to
|
|
ensure names in paths are as portable as desired, but they must be explicitly
|
|
called by the user.</p>
|
|
<h3><a name="constructors">constructors</a></h3>
|
|
<blockquote>
|
|
<pre>path();</pre>
|
|
<p><b>Effects:</b> Default constructs an object of class <i>path</i>.</p>
|
|
<pre>path( const std::string & src );
|
|
path( const char * src );</pre>
|
|
<p><b>Precondition:</b> <i>src</i> conforms to the <a href="#Grammar">generic
|
|
path string grammar</a> <i>relative-path</i> syntax, and contains no embedded
|
|
'\0' characters.</p>
|
|
<p><b>Effects:</b> For each <i>src</i> <i>element</i>, <code>m_name.push_back( <i>element</i> )</code>.</p>
|
|
<p><b>Postcondition:</b> <code>m_name</code> has been reduced to
|
|
<a href="#Canonical">canonical form</a>.</p>
|
|
<p><b>Rationale:</b> These constructors are not explicit because an intended
|
|
use is automatic conversion of strings to paths. </p>
|
|
<pre>path( const std::string & src, format );
|
|
path( const char * src, format );</pre>
|
|
<p><b>Precondition:</b> <i>src</i> conforms to the operating system's grammar
|
|
for path strings, and contains no embedded '\0' characters.</p>
|
|
<p><b>Effects:</b> For each <i>src</i> element (where an element represents a
|
|
directory name, file name, or parent-directory indicator), <code>m_name.push_back( <i>element</i> )</code>.</p>
|
|
<p><b>Postcondition:</b> <code>m_name</code> has been reduced to
|
|
<a href="#Canonical">canonical form</a>.</p>
|
|
</blockquote>
|
|
<h3><a name="operator-shift-equal">operator <<=</a></h3>
|
|
<blockquote>
|
|
<pre>path & operator<<=( const path & rhs );</pre>
|
|
<p><b>Effects:</b> Append <code>rhs.m_name</code> to <code>m_name</code>.</p>
|
|
<p><b>Returns:</b> <code>*this</code></p>
|
|
<p><b>Postcondition:</b> <code>m_name</code> has been reduced to
|
|
<a href="#Canonical">canonical form</a>.</p>
|
|
</blockquote>
|
|
<h3><a name="operator-shift">operator <<</a></h3>
|
|
<blockquote>
|
|
<pre>const path operator<< ( const path & rhs ) const;</pre>
|
|
<p><b>Returns:</b> <code>path( *this ) <<= rhs</code></p>
|
|
<p><b>Rationale: </b>Operator <<, together with operator <<=, provides a
|
|
convenient way for users to supply paths with a variable number of elements.
|
|
For example, <code>initial_directory() << "src" << test_name</code>.
|
|
Operator+, with operator+=, were considered as alternatives, but deemed too
|
|
easy to confuse with those operators for std::string.</p>
|
|
</blockquote>
|
|
<h3><a name="empty">empty</a></h3>
|
|
<blockquote>
|
|
<pre>bool empty() const;</pre>
|
|
<p><b>Returns:</b> <code>m_name.size() == 0</code></p>
|
|
<p><b>Rationale:</b> The name is the same as the equivalent function in standard
|
|
library containers.</p>
|
|
</blockquote>
|
|
<h3><a name="generic_path">generic_path</a></h3>
|
|
<blockquote>
|
|
<pre>const std::string & generic_path() const;</pre>
|
|
<p><b>Returns:</b> The contents of <code>m_name</code>, formatted according to
|
|
the rules of the <a href="#Grammar">generic path string grammar</a>.</p>
|
|
<p><b>Note:</b> If any m_name elements originated from the system specific
|
|
constructors, there is no guarantee that the returned string is unambiguous
|
|
according to the grammar. A system-specific-root indistinguishable from a
|
|
relative-path name, a name containing "/", a name "..", and a
|
|
system-specific-root beyond the first element all could cause ambiguities. Such
|
|
an ambiguous representation might still be useful for some purposes, such as
|
|
display. If no m_name elements originated from the system specific constructors,
|
|
the returned string is always unambiguous.</p>
|
|
</blockquote>
|
|
<h3><a name="file_c_str">file_c_str</a></h3>
|
|
<blockquote>
|
|
<pre>const char * file_c_str() const;</pre>
|
|
<p><b>Returns:</b> The contents of <code>m_name</code>, formatted according to
|
|
the operating system's rules for file paths.</p>
|
|
</blockquote>
|
|
<h3><a name="directory_c_str">directory_c_str</a></h3>
|
|
<blockquote>
|
|
<pre>const char * directory_c_str() const;</pre>
|
|
<p><b>Returns:</b> The contents of <code>m_name</code>, formatted according to
|
|
the operating system's rules for directory paths.</p>
|
|
</blockquote>
|
|
<h3><a name="leaf">leaf</a></h3>
|
|
<blockquote>
|
|
<pre>const std::string leaf() const;</pre>
|
|
<p><b>Returns:</b> <code>empty() ? string() : m_name.back()</code></p>
|
|
<p><b>Rationale: </b>Return type is <code>string</code> rather than <code>const
|
|
string &</code> to give implementations freedom to avoid maintaining the
|
|
leaf as a separate <code>string</code> object.</p>
|
|
</blockquote>
|
|
<h3><a name="branch">branch</a></h3>
|
|
<blockquote>
|
|
<pre>const path branch() const;</pre>
|
|
<p><b>Returns:</b> <code>m_name.size() <= 1 ? path("") : x</code>, where <code>x</code>
|
|
is a path constructed from all the elements of <code>m_name</code> except the
|
|
last.</p>
|
|
</blockquote>
|
|
<h2><a name="Non-member functions">Non-member functions</a></h2>
|
|
<p>(to be supplied)</p>
|
|
<hr>
|
|
<p>© Copyright Beman Dawes, 2002</p>
|
|
<p>Revised
|
|
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->10 July, 2002<!--webbot bot="Timestamp" endspan i-checksum="21077" --></p>
|
|
|
|
</body>
|
|
|
|
</html> |