Class Poco::Path

File Information

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, separator, setBaseName, setDevice, setExtension, setFileName, setNode, swap, temp, tempHome, toString, transcode, tryParse, version

Types

StringVec

typedef std::vector < std::string > StringVec;

Enumerations

Style

PATH_UNIX

Unix-style path

PATH_URI = PATH_UNIX

URI-style path, same as Unix-style

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

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

Path(
const Path & path
);

Copy constructor

Path

Path(
Path && path
) noexcept;

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.

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.

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.

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
);

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.