Path Class Reference

#include <ImFusion/Core/Filesystem/Path.h>

Entity representing a path in the filesystem. More...

Detailed Description

Entity representing a path in the filesystem.

Such an object is concerned only with the lexical and syntactic aspects of a path. The path does not necessarily exist in external storage, and the pathname is not necessarily valid for the current operating system or for a particular file system. Use the Directory and File classes to actually interact with the filesystem.

A Path consists of a series of components, which are separated by the generic path separator '/'. For convenience, member functions also accept the native separator (e.g. the '\' on Windows systems) as input and will convert accordingly. The output of all member functions will be in the generic format. You can use makeNative() to extract a string representaion suitable for the underlying OS API.

A path can be decomposed into it's individual parts and has the generic form of

[/|C:/][foo/bar/][<baseName>.can.have.multiple.dots.<extension>]
\_____/           \__________\____________________/___________/
<root>               <fullBaseName>          <fullExtension>
\_____________/  \_____________________________________________/
 <parentPath>                      <filename>

Note that the root component is platform-dependent.

All interfaces of Path assume the path to be encoded in UTF-8. Potentially required conversion to a platform-specific encoding (e.g. UTF-16 on Windows) is handled internally.

Technically, a Path is just a wrapper around a std::string providing a different set of member functions and expressing intent through the type. Since conversion from and to string is transparent and does not change/lose any data (except for transforming native separators to their generic from, see above), the conversion operators from and to std::string are defined implicit.

Examples

Filesystem.cpp.

Public Member Functions
	Path ()=default
	Default-constructed paths are empty by definition.
	Path (const std::string_view &path)
	Instantiate a path from a given string.
	Path (const std::string &path)
	Path (const char *path)
	Path (const std::string &base, const std::string &path)
	Instantiate a path concatenating the two given strings for convenience.
bool	operator== (const Path &other) const
	Two paths are equal when their representing strings are lexically equal.
bool	operator!= (const Path &other) const
Path	operator/ (const Path &other) const
	Concatenate paths. The right hand argument should be a relative path.
Path	operator+ (const Path &other) const
	Basic string concatenation of paths without introducing any directory separator.
	operator std::string () const
	Provide implicit conversion to std::string since it's not a narrowing conversion.
	operator std::string_view () const
	Provide implicit conversion to std::string_view since it's not a narrowing conversion.

Convert to Related Types
std::string	string () const
	Return the path as string in generic format.
File	asFile () const
	Constructs a File instance from this path, convenience function for Filesystem::File(*this).
Directory	asDirectory () const
	Constructs a Directory instance from this path, convenience function for Filesystem::Directory(*this).

Path Decomposition into Components
Path	parentPath () const
	Return this path without the last component (filename).
Directory	parentDirectory () const
	Return this path without the last component (filename).
std::string	filename () const
	Return the last component of the path (independent of whether it represents an actual file or not).
std::string	baseName () const
	Gets the base resource name until the first dot (essentially filename - fullExtension).
std::string	fullBaseName () const
	Gets the base resource name until the last dot (essentially filename - extension).
std::string	extension () const
	Gets the last extension of the path not including the dot (essentially filename - fullBaseName).
std::string	fullExtension () const
	Gets the full extension of the path not including the first dot (essentially filename - baseName).
size_t	length () const
	Returns the length of the path, convenience function for string().length().

Query Filesystem Properties
bool	exists () const
	Check if a resource exists under the given path.
bool	isRelative () const
	Check if the path is relative.
bool	isAbsolute () const
	Check if the path is absolute.
bool	isFile () const
	Check whether the resource exists and represents a file.
bool	isDirectory () const
	Check whether the resource exists and represents a directory.
bool	isSymlink () const
	Check whether the resource exists and represents a symlink.
SpaceInfo	spaceInfo () const
	Returns space information about the filesystem on which this path is located In case of an error, returns 0_bytes in all fields.
time_t	lastModified () const
	Gets the time of the last modification to the path.

Derive or Modify Paths
Path	makeRelativeTo (const Path &basePath) const
	Returns path made relative to basePath.
Path	makeAbsolute () const
	It creates a copy if the path is absolute, otherwise it prepends the path with the current working directory.
Path	makeNormalized () const
	Returns a copy of the path where redundant elements such as .
Path	makeCanonical () const
	It converts the path into an absolute path, cleans it up by removing and resolving elements such as .
std::string	makeNative () const
	Returns the native string representation of the path, using native path separator, character type, and encoding so that it is suitable for usage with the API of the underlying OS.
Path	resolveSymlink () const
	Resolves the full path to the symlink. If not a symlink, returns an empty Path.
void	replaceFilename (const std::string &newFilename)
	Replaces the filename() component with the given string.
void	replaceExtension (const std::string &newExtension)
	Replaces the extension() component with the given string.

Constructor & Destructor Documentation

Path()

Path	(	const std::string &	base,
		const std::string &	path )

Instantiate a path concatenating the two given strings for convenience.

Has the same effect as Path(base) / Path(path).

Parameters

base	The first part of the path
path	The second part of the path

Member Function Documentation

operator==()

bool operator== ( const Path & other ) const

inline

Two paths are equal when their representing strings are lexically equal.

To determine if two paths resolve to the same entity use makeCanonical().

parentPath()

Path parentPath

(

)

const

Return this path without the last component (filename).

If the path ends with a trailing slash, the last component is considered present (yet empty).

Path("/foo/bar.txt").parentPath();  ->  "/foo"
Path("/foo/bar").parentPath();      ->  "/foo"
Path("/foo/bar/").parentPath();     ->  "/foo/bar"
Path("/").parentPath();             ->  ""
Path(".").parentPath();             ->  ""
Path("..").parentPath();            ->  ""

Examples

Filesystem.cpp.

parentDirectory()

Directory parentDirectory

(

)

const

Return this path without the last component (filename).

If the path ends with a trailing slash, the last component is considered present (yet empty).

Path("/foo/bar.txt").parentPath();  ->  "/foo"
Path("/foo/bar").parentPath();      ->  "/foo"
Path("/foo/bar/").parentPath();     ->  "/foo/bar"
Path("/").parentPath();             ->  ""
Path(".").parentPath();             ->  ""
Path("..").parentPath();            ->  ""

Convenience function for parentPath().asDirectory().

filename()

std::string filename

(

)

const

Return the last component of the path (independent of whether it represents an actual file or not).

If the path ends with a trailing slash the last filename is considered empty.

Path("/foo/bar.txt").filename();  ->  "bar.txt"
Path("/foo/bar").filename();      ->  "bar"
Path("/foo/bar/").filename();     ->  ""
Path("/").filename();             ->  ""
Path(".").filename();             ->  "."
Path("..").filename();            ->  ".."

baseName()

std::string baseName

(

)

const

Gets the base resource name until the first dot (essentially filename - fullExtension).

If the path ends with a trailing slash the last filename is considered empty.

Path("./directory1/myfile.tar.gz").baseName();  ->  "myfile"
Path("./directory1/myfile.pdf").baseName();     ->  "myfile"
Path("./directory1/myfile").baseName();         ->  "myfile"
Path("./directory1/").baseName();               ->  ""
Path("/").baseName();                           ->  ""

fullBaseName()

std::string fullBaseName

(

)

const

Gets the base resource name until the last dot (essentially filename - extension).

If the path ends with a trailing slash the last filename is considered empty.

Path("./directory1/myfile.tar.gz").fullBaseName();  ->  "myfile.tar"
Path("./directory1/myfile.pdf").fullBaseName();     ->  "myfile"
Path("./directory1/myfile").fullBaseName();         ->  "myfile"
Path("./directory1/").fullBaseName();               ->  ""
Path("/").fullBaseName();                           ->  ""

extension()

std::string extension

(

)

const

Gets the last extension of the path not including the dot (essentially filename - fullBaseName).

Path("./directory1/myfile.pdf").extension();     ->  "pdf"
Path("./directory1/myfile.pdf.gz").extension();  ->  "gz"
Path("./directory1/myfile").extension();         ->  ""
Path("./directory1/").extension();               ->  ""

fullExtension()

std::string fullExtension

(

)

const

Gets the full extension of the path not including the first dot (essentially filename - baseName).

Path("./directory1/myfile.pdf").fullExtension();     ->  "pdf"
Path("./directory1/myfile.pdf.gz").fullExtension();  ->  "pdf.gz"
Path("./directory1/myfile").fullExtension();         ->  ""
Path("./directory1/").fullExtension();               ->  ""

exists()

bool exists

(

)

const

Check if a resource exists under the given path.

It returns false if the path is not valid. If it is a relative path, it prepends the current working directory to it.

Returns

True if a resource under the path exists

makeRelativeTo()

Path makeRelativeTo

(

const Path &

basePath

)

const

Returns path made relative to basePath.

Treats empty or identical paths as corner cases, not errors. Does not resolve symlinks. Does not first normalize this or basePath.

Parameters

basePath

The path we take as reference.

Examples

Filesystem.cpp.

makeAbsolute()

Path makeAbsolute

(

)

const

It creates a copy if the path is absolute, otherwise it prepends the path with the current working directory.

Returns

An absolute path

makeNormalized()

Path makeNormalized

(

)

const

Returns a copy of the path where redundant elements such as .

, .., and / are removed. Unlike makeCanonical() this function will not convert to an absolute path, resolve symlinks, or access the underlying filesystem in any form.

Path("foo/./bar/..").makeNormalized();                   ->  "foo"
Path("foo/./bar/../..").makeNormalized();                ->  "."
Path("foo/.///bar/../").makeNormalized();                ->  "foo/"
Path("foo/./bar/../file..with..dots").makeNormalized();  ->  "foo/file..with..dots"

makeCanonical()

Path makeCanonical

(

)

const

It converts the path into an absolute path, cleans it up by removing and resolving elements such as .

, .., and resolves symbolic links. If the resource does not exist, it returns an empty path.

See also

Use makeNormalized() if you want to clean a path from redundant elements independent of symlinks or the existence of the resource.

Examples

Filesystem.cpp.

---

The documentation for this class was generated from the following file:

• ImFusion/Core/Filesystem/Path.h