Library: Foundation
Package: Filesystem
Header: Poco/Path.h
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.
Member Functions: absolute, append, assign, buildUnix, buildVMS, buildWindows, clear, current, depth, directory, expand, find, forDirectory, getBaseName, getDevice, getExtension, getFileName, getNode, home, isAbsolute, isDirectory, isFile, isRelative, listRoots, makeAbsolute, makeDirectory, makeFile, makeParent, null, operator =, operator [], parent, parse, parseDirectory, parseGuess, parseUnix, parseVMS, parseWindows, pathSeparator, popDirectory, popFrontDirectory, pushDirectory, resolve, separator, setBaseName, setDevice, setExtension, setFileName, setNode, swap, temp, toString, transcode, tryParse, version
typedef std::vector < std::string > StringVec;
Unix-style path
Windows-style path
VMS-style path
The current platform's native style
Guess the style by examining the path
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 std::string & path
);
Creates a path from a string.
Copy constructor
Path(
const char * path,
Style style
);
Creates a path from a string.
Path(
const std::string & path,
Style style
);
Creates a path from a string.
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 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.
Path & append(
const Path & path
);
Appends the given path.
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.
Path & clear();
Clears all components.
static std::string current();
Returns the current working directory.
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.
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 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 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.
std::string getBaseName() const;
Returns the basename (the filename sans extension) of the path.
const std::string & getDevice() const;
Returns the device name.
std::string getExtension() const;
Returns the filename extension.
const std::string & getFileName() const;
Returns the filename.
const std::string & getNode() const;
Returns the node name.
static std::string home();
Returns the user's home directory.
bool isAbsolute() const;
Returns true if and only if the path is absolute.
bool isDirectory() const;
Returns true if and only if the path references a directory (the filename part is empty).
bool isFile() const;
Returns true if and only if the path references a file (the filename part is not empty).
bool isRelative() const;
Returns true if and only if the path is relative.
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.
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 & 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.
static std::string null();
Returns the name of the null device.
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.
const std::string & operator[] (
int n
) const;
Returns the n'th directory in the directory list. If n == depth(), returns the filename.
Path parent() const;
Returns a path referring to the path's directory.
Path & parse(
const std::string & path
);
Same as assign().
Path & parse(
const std::string & path,
Style style
);
Assigns a string containing a path.
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.
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 ','.
Path & popDirectory();
Removes the last directory from the directory list.
Path & popFrontDirectory();
Removes the first directory from the directory list.
Path & pushDirectory(
const std::string & dir
);
Adds a directory to the directory list.
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.
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 '.'.
Path & setBaseName(
const std::string & name
);
Sets the basename part of the filename and does not change the extension.
Path & setDevice(
const std::string & device
);
Sets the device name. Setting a non-empty device automatically makes the path an absolute one.
Path & setExtension(
const std::string & extension
);
Sets the filename extension.
Path & setFileName(
const std::string & name
);
Sets the filename.
Path & setNode(
const std::string & node
);
Sets the node name. Setting a non-empty node automatically makes the path an absolute one.
void swap(
Path & path
);
Swaps the path with another one.
static std::string temp();
Returns the temporary directory.
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.
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.
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.
const std::string & version() const;
Returns the file version. VMS only.
std::string buildUnix() const;
std::string buildVMS() const;
std::string buildWindows() const;
void parseGuess(
const std::string & path
);
void parseUnix(
const std::string & path
);
void parseVMS(
const std::string & path
);
void parseWindows(
const std::string & path
);