topical media & game development
lib-of-vs-libs-Poco-include-Poco-Path.h / h
//
// Path.h
//
//
//
// Library: Foundation
// Package: Filesystem
// Module: Path
//
// Definition of the Path class.
//
// Copyright (c) 2004-2006, Applied Informatics Software Engineering GmbH.
// and Contributors.
//
// Permission is hereby granted, free of charge, to any person or organization
// obtaining a copy of the software and accompanying documentation covered by
// this license (the "Software") to use, reproduce, display, distribute,
// execute, and transmit the Software, and to prepare derivative works of the
// Software, and to permit third-parties to whom the Software is furnished to
// do so, all subject to the following:
//
// The copyright notices in the Software and this entire statement, including
// the above license grant, this restriction and the following disclaimer,
// must be included in all copies of the Software, in whole or in part, and
// all derivative works of the Software, unless such copies or derivative
// works are solely in the form of machine-executable object code generated by
// a source language processor.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT
// SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE
// FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE,
// ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
// DEALINGS IN THE SOFTWARE.
//
ifndef Foundation_Path_INCLUDED
define Foundation_Path_INCLUDED
include "Poco/Foundation.h"
include <vector>
namespace Poco {
class Foundation_API Path
This class represents filesystem paths in a
platform-independent manner.
Unix, Windows and OpenVMS all use a different
syntax for filesystem paths.
This class can work with all three formats.
A path is made up of an optional node name
(only Windows and OpenVMS), an optional
device name (also only Windows and OpenVMS),
a list of directory names and an optional
filename.
{
public:
enum Style
{
PATH_UNIX,
Unix-style path
PATH_WINDOWS,
Windows-style path
PATH_VMS,
VMS-style path
PATH_NATIVE,
The current platform's native style
PATH_GUESS
Guess the style by examining the path
};
typedef std::vector
<std::string> StringVec;
Path();
Creates an empty relative path.
Path(bool absolute);
Creates an empty absolute or relative path.
Path(const char* path);
Creates a path from a string.
Path(const char* path, Style style);
Creates a path from a string.
Path(const std::string& path);
Creates a path from a string.
Path(const std::string& path, Style style);
Creates a path from a string.
Path(const Path& path);
Copy constructor
Path(const Path& parent, const std::string& fileName);
Creates a path from a parent path and a filename.
The parent path is expected to reference a directory.
Path(const Path& parent, const char* fileName);
Creates a path from a parent path and a filename.
The parent path is expected to reference a directory.
Path(const Path& parent, const Path& relative);
Creates a path from a parent path and a relative path.
The parent path is expected to reference a directory.
The relative path is appended to the parent path.
~Path();
Destroys the Path.
Path& operator = (const Path& path);
Assignment operator.
Path& operator = (const std::string& path);
Assigns a string containing a path in native format.
Path& operator = (const char* path);
Assigns a string containing a path in native format.
void swap(Path& path);
Swaps the path with another one.
Path& assign(const std::string& path);
Assigns a string containing a path in native format.
Path& assign(const std::string& path, Style style);
Assigns a string containing a path.
Path& assign(const Path& path);
Assigns the given path.
Path& assign(const char* path);
Assigns a string containing a path.
std::string toString() const;
Returns a string containing the path in native format.
std::string toString(Style style) const;
Returns a string containing the path in the given format.
Path& parse(const std::string& path);
Same as assign().
Path& parse(const std::string& path, Style style);
Assigns a string containing a path.
bool tryParse(const std::string& path);
Tries to interpret the given string as a path
in native format.
If the path is syntactically valid, assigns the
path and returns true. Otherwise leaves the
object unchanged and returns false.
bool tryParse(const std::string& path, Style style);
Tries to interpret the given string as a path,
according to the given style.
If the path is syntactically valid, assigns the
path and returns true. Otherwise leaves the
object unchanged and returns false.
Path& parseDirectory(const std::string& path);
The resulting path always refers to a directory and
the filename part is empty.
Path& parseDirectory(const std::string& path, Style style);
The resulting path always refers to a directory and
the filename part is empty.
Path& makeDirectory();
If the path contains a filename, the filename is appended
to the directory list and cleared. Thus the resulting path
always refers to a directory.
Path& makeFile();
If the path contains no filename, the last directory
becomes the filename.
Path& makeParent();
Makes the path refer to its parent.
Path& makeAbsolute();
Makes the path absolute if it is relative.
The current working directory is taken as base directory.
Path& makeAbsolute(const Path& base);
Makes the path absolute if it is relative.
The given path is taken as base.
Path& append(const Path& path);
Appends the given path.
Path& resolve(const Path& path);
Resolves the given path agains the current one.
If the given path is absolute, it replaces the current one.
Otherwise, the relative path is appended to the current path.
bool isAbsolute() const;
Returns true iff the path is absolute.
bool isRelative() const;
Returns true iff the path is relative.
bool isDirectory() const;
Returns true iff the path references a directory
(the filename part is empty).
bool isFile() const;
Returns true iff the path references a file
(the filename part is not empty).
void setNode(const std::string& node);
Sets the node name.
Setting a non-empty node automatically makes
the path an absolute one.
const std::string& getNode() const;
Returns the node name.
void setDevice(const std::string& device);
Sets the device name.
Setting a non-empty device automatically makes
the path an absolute one.
const std::string& getDevice() const;
Returns the device name.
int depth() const;
Returns the number of directories in the directory list.
const std::string& directory(int n) const;
Returns the n'th directory in the directory list.
If n == depth(), returns the filename.
const std::string& operator [] (int n) const;
Returns the n'th directory in the directory list.
If n == depth(), returns the filename.
void pushDirectory(const std::string& dir);
Adds a directory to the directory list.
void popDirectory();
Removes the last directory from the directory list.
void setFileName(const std::string& name);
Sets the filename.
const std::string& getFileName() const;
Returns the filename.
void setBaseName(const std::string& name);
Sets the basename part of the filename and
does not change the extension.
std::string getBaseName() const;
Returns the basename (the filename sans
extension) of the path.
void setExtension(const std::string& extension);
Sets the filename extension.
std::string getExtension() const;
Returns the filename extension.
const std::string& version() const;
Returns the file version. VMS only.
void clear();
Clears all components.
Path parent() const;
Returns a path referring to the path's
directory.
Path absolute() const;
Returns an absolute variant of the path,
taking the current working directory as base.
Path absolute(const Path& base) const;
Returns an absolute variant of the path,
taking the given path as base.
static Path forDirectory(const std::string& path);
Creates a path referring to a directory.
static Path forDirectory(const std::string& path, Style style);
Creates a path referring to a directory.
static char separator();
Returns the platform's path name separator, which separates
the components (names) in a path.
On Unix systems, this is the slash '/'. On Windows systems,
this is the backslash '\'. On OpenVMS systems, this is the
period '.'.
static char pathSeparator();
Returns the platform's path separator, which separates
single paths in a list of paths.
On Unix systems, this is the colon ':'. On Windows systems,
this is the semicolon ';'. On OpenVMS systems, this is the
comma ','.
static std::string current();
Returns the current working directory.
static std::string home();
Returns the user's home directory.
static std::string temp();
Returns the temporary directory.
static std::string null();
Returns the name of the null device.
static std::string expand(const std::string& path);
Expands all environment variables contained in the path.
On Unix, a tilde as first character in the path is
replaced with the path to user's home directory.
static void listRoots(std::vector<std::string>& roots);
Fills the vector with all filesystem roots available on the
system. On Unix, there is exactly one root, "/".
On Windows, the roots are the drive letters.
On OpenVMS, the roots are the mounted disks.
static bool find(StringVec::const_iterator it, StringVec::const_iterator end, const std::string& name, Path& path);
Searches the file with the given name in the locations (paths) specified
by it and end. A relative path may be given in name.
If the file is found in one of the locations, the complete
path of the file is stored in the path given as argument and true is returned.
Otherwise false is returned and the path argument remains unchanged.
static bool find(const std::string& pathList, const std::string& name, Path& path);
Searches the file with the given name in the locations (paths) specified
in pathList. The paths in pathList must be delimited by the platform's
path separator (see pathSeparator()). A relative path may be given in name.
If the file is found in one of the locations, the complete
path of the file is stored in the path given as argument and true is returned.
Otherwise false is returned and the path argument remains unchanged.
static std::string transcode(const std::string& path);
On Windows, if POCO has been compiled with Windows UTF-8 support
(POCO_WIN32_UTF8), this function converts a string (usually containing a path)
encoded in UTF-8 into a string encoded in the current Windows code page.
This function should be used for every string passed as a file name to
a string stream or fopen().
On all other platforms, or if POCO has not been compiled with Windows UTF-8
support, this function returns the string unchanged.
protected:
void parseUnix(const std::string& path);
void parseWindows(const std::string& path);
void parseVMS(const std::string& path);
void parseGuess(const std::string& path);
std::string buildUnix() const;
std::string buildWindows() const;
std::string buildVMS() const;
private:
std::string _node;
std::string _device;
std::string _name;
std::string _version;
StringVec _dirs;
bool _absolute;
};
//
// inlines
//
inline bool Path::isAbsolute() const
{
return _absolute;
}
inline bool Path::isRelative() const
{
return !_absolute;
}
inline bool Path::isDirectory() const
{
return _name.empty();
}
inline bool Path::isFile() const
{
return !_name.empty();
}
inline Path& Path::parse(const std::string& path)
{
return assign(path);
}
inline Path& Path::parse(const std::string& path, Style style)
{
return assign(path, style);
}
inline const std::string& Path::getNode() const
{
return _node;
}
inline const std::string& Path::getDevice() const
{
return _device;
}
inline const std::string& Path::getFileName() const
{
return _name;
}
inline int Path::depth() const
{
return int(_dirs.size());
}
inline const std::string& Path::version() const
{
return _version;
}
inline Path Path::forDirectory(const std::string& path)
{
Path p;
return p.parseDirectory(path);
}
inline Path Path::forDirectory(const std::string& path, Style style)
{
Path p;
return p.parseDirectory(path, style);
}
inline char Path::separator()
{
if defined(POCO_OS_FAMILY_VMS)
return '.';
#elif defined(POCO_OS_FAMILY_WINDOWS)
return '\\';
else
return '/';
endif
}
inline char Path::pathSeparator()
{
if defined(POCO_OS_FAMILY_VMS)
return ',';
#elif defined(POCO_OS_FAMILY_WINDOWS)
return ';';
else
return ':';
endif
}
inline void swap(Path& p1, Path& p2)
{
p1.swap(p2);
}
} // namespace Poco
endif // Foundation_Path_INCLUDED
(C) Æliens
04/09/2009
You may not copy or print any of this material without explicit permission of the author or the publisher.
In case of other copyright issues, contact the author.
