Library: Foundation
Package: Filesystem
Header: Poco/Path.h
Description
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 Summary
Member Functions: absolute, append, assign, buildUnix, buildVMS, buildWindows, cacheHome, clear, config, configHome, current, dataHome, 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, self, separator, setBaseName, setDevice, setExtension, setFileName, setNode, swap, temp, tempHome, toString, transcode, tryParse, version
Types
StringVec
typedef std::vector < std::string > StringVec;
Enumerations
Style
Unix-style path
PATH_URI = PATH_UNIX
URI-style path, same as Unix-style
Windows-style path
VMS-style path
The current platform's native style
Guess the style by examining the path
Constructors
Path
Path();
Creates an empty relative path.
Path
Path(
bool absolute
);
Creates an empty absolute or relative path.
Path
Path(
const char * path
);
Creates a path from a string.
Path
Path(
const std::string & path
);
Creates a path from a string.
Path
Copy constructor
Path
Move constructor.
Path
Path(
const char * path,
Style style
);
Creates a path from a string.
Path
Path(
const std::string & path,
Style style
);
Creates a path from a string.
Path
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
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
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.
Destructor
~Path
~Path();
Destroys the Path.
Member Functions
absolute
Path absolute() const;
Returns an absolute variant of the path, taking the current working directory as base.
absolute
Path absolute(
const Path & base
) const;
Returns an absolute variant of the path, taking the given path as base.
append
Path & append(
const Path & path
);
Appends the given path.
assign
Path & assign(
const std::string & path
);
Assigns a string containing a path in native format.
assign
Path & assign(
const std::string & path,
Style style
);
Assigns a string containing a path.
assign
Path & assign(
const Path & path
);
Assigns the given path.
assign
Path & assign(
const char * path
);
Assigns a string containing a path.
cacheHome 
static std::string cacheHome();
Returns the user's cache directory.
On Unix systems, this is the '~/.cache/'. On Windows systems, this is the same as tempHome().
clear
Path & clear();
Clears all components.
config
static std::string config();
Returns the systemwide config directory.
On Unix systems, this is the '/etc/'.
configHome
static std::string configHome();
Returns the user's config directory.
On Unix systems, this is the '~/.config/'. On Windows systems, this is '%APPDATA%' (typically C:\Users\user\AppData\Roaming).
current
static std::string current();
Returns the current working directory.
dataHome
static std::string dataHome();
Returns the user's data directory.
On Unix systems, this is the '~/.local/share/'. On Windows systems, this is '%LOCALAPPDATA%' (typically C:\Users\user\AppData\Local).
depth 
int depth() const;
Returns the number of directories in the directory list.
directory
const std::string & directory(
int n
) const;
Returns the n'th directory in the directory list. If n == depth(), returns the filename.
expand
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.
find
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.
find
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.
forDirectory
static Path forDirectory(
const std::string & path
);
Creates a path referring to a directory.
forDirectory
static Path forDirectory(
const std::string & path,
Style style
);
Creates a path referring to a directory.
getBaseName
std::string getBaseName() const;
Returns the basename (the filename sans extension) of the path.
getDevice
const std::string & getDevice() const;
Returns the device name.
getExtension
std::string getExtension() const;
Returns the filename extension.
getFileName
const std::string & getFileName() const;
Returns the filename.
getNode
const std::string & getNode() const;
Returns the node name.
home
static std::string home();
Returns the user's home directory.
isAbsolute
bool isAbsolute() const;
Returns true iff the path is absolute.
isDirectory
bool isDirectory() const;
Returns true iff the path references a directory (the filename part is empty).
isFile
bool isFile() const;
Returns true iff the path references a file (the filename part is not empty).
isRelative
bool isRelative() const;
Returns true iff the path is relative.
listRoots
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.
makeAbsolute
Path & makeAbsolute();
Makes the path absolute if it is relative. The current working directory is taken as base directory.
makeAbsolute
Path & makeAbsolute(
const Path & base
);
Makes the path absolute if it is relative. The given path is taken as base.
makeDirectory
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.
makeFile
Path & makeFile();
If the path contains no filename, the last directory becomes the filename.
makeParent
Path & makeParent();
Makes the path refer to its parent.
null
static std::string null();
Returns the name of the null device.
operator =
Path & operator = (
const Path & path
);
Assignment operator.
operator =
Path & operator = (
Path && path
) noexcept;
Move assignment.
operator =
Path & operator = (
const std::string & path
);
Assigns a string containing a path in native format.
operator =
Path & operator = (
const char * path
);
Assigns a string containing a path in native format.
operator []
const std::string & operator[] (
int n
) const;
Returns the n'th directory in the directory list. If n == depth(), returns the filename.
parent
Path parent() const;
Returns a path referring to the path's directory.
parse
Path & parse(
const std::string & path
);
Same as assign().
parse
Path & parse(
const std::string & path,
Style style
);
Assigns a string containing a path.
parseDirectory
Path & parseDirectory(
const std::string & path
);
The resulting path always refers to a directory and the filename part is empty.
parseDirectory
Path & parseDirectory(
const std::string & path,
Style style
);
The resulting path always refers to a directory and the filename part is empty.
pathSeparator
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 ','.
popDirectory
Path & popDirectory();
Removes the last directory from the directory list.
popFrontDirectory
Path & popFrontDirectory();
Removes the first directory from the directory list.
pushDirectory
Path & pushDirectory(
const std::string & dir
);
Adds a directory to the directory list.
resolve
Path & resolve(
const Path & path
);
Resolves the given path against the current one.
If the given path is absolute, it replaces the current one. Otherwise, the relative path is appended to the current path.
self
static std::string self();
Return path to the executable file, empty string if failed. The path is absolute one.
separator
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 '.'.
setBaseName
Path & setBaseName(
const std::string & name
);
Sets the basename part of the filename and does not change the extension.
setDevice
Path & setDevice(
const std::string & device
);
Sets the device name. Setting a non-empty device automatically makes the path an absolute one.
setExtension
Path & setExtension(
const std::string & extension
);
Sets the filename extension.
setFileName
Path & setFileName(
const std::string & name
);
Sets the filename.
setNode
Path & setNode(
const std::string & node
);
Sets the node name. Setting a non-empty node automatically makes the path an absolute one.
swap
void swap(
Path & path
) noexcept;
Swaps the path with another one.
temp
static std::string temp();
Returns the temporary directory.
tempHome
static std::string tempHome();
Returns the user's temp directory.
On Unix systems, this is the '~/.local/temp/'.
toString
std::string toString() const;
Returns a string containing the path in native format.
toString
std::string toString(
Style style
) const;
Returns a string containing the path in the given format.
transcode
static std::string transcode(
const std::string & path
);
On Windows, 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.
tryParse
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.
tryParse
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.
version
const std::string & version() const;
Returns the file version. VMS only.
buildUnix 
std::string buildUnix() const;
buildVMS
std::string buildVMS() const;
buildWindows
std::string buildWindows() const;
parseGuess
void parseGuess(
const std::string & path
);
parseUnix
void parseUnix(
const std::string & path
);
parseVMS
void parseVMS(
const std::string & path
);
parseWindows
void parseWindows(
const std::string & path
);