Class Poco::Path
Author: Applied Informatics Software Engineering GmbH and Contributors

# Poco

# class Path

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_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(
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 '%APPDATA%'.

### 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%'.

### 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 '%APPDATA%'.

### 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 if and only if the path is absolute.

### isDirectory

bool isDirectory() const;

Returns true if and only if the path references a directory (the filename part is empty).

### isFile

bool isFile() const;

Returns true if and only if the path references a file (the filename part is not empty).

### isRelative

bool isRelative() const;

Returns true if and only if 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 = (
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 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.

### 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, 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.

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