Path#

Fully qualified name: carb::extras::Path

Defined in carb/extras/Path.h

class Path#

Path objects are used for filesystem path manipulations.

All paths are UTF-8 encoded using forward slash as path separator.

Note: the class supports implicit casting to a “std::string” and explicit cast to a “const char *” pointer

Public Functions

Path() = default#

Default constructor.

inline Path(const char *path, size_t pathLen)#

Constructs a Path from a counted char array containing a UTF-8 encoded string.

The Path object converts all backslashes to forward slashes.

Parameters:

• path – a pointer to the UTF-8 string data

• pathLen – the size of path in bytes

inline Path(const char *path)#

Constructs a Path from a NUL-terminated char buffer containing a UTF-8 encoded string.

The Path object converts all backslashes to forward slashes.

Parameters:

path – a pointer to the UTF-8 string data

inline Path(std::string path)#

Constructs a Path from a std::string containing a UTF-8 encoded string.

The Path object converts all backslashes to forward slashes.

Parameters:

path – The source string

inline Path(const omni::string &path)#

Constructs a Path from an omni::string containing a UTF-8 encoded string.

The Path object converts all backslashes to forward slashes.

Parameters:

path – The source string

inline Path(const Path &other)#

Copy constructor.

Copies a Path from another Path.

Parameters:

other – The other path to copy from

inline Path(Path &&other) noexcept#

Move constructor.

Moves a Path from another Path, which is left in a valid but unspecified state.

Parameters:

other – The other path to move from

inline Path &operator=(const Path &other)#

Copy-assign operator.

Copies another Path into *this.

Parameters:

other – The other path to copy from

Returns:

*this

inline Path &operator=(Path &&other) noexcept#

Move-assign operator.

Moves another Path into *this and leaves the other path in a valid but unspecified state.

Parameters:

other – The other path to move from

Returns:

*this

~Path() = default#

Destructor.

inline std::string getString() const#

Gets the string representation of the path.

Returns:

a copy of the UTF-8 string representation of the internal data

inline operator std::string() const#

Implicit conversion operator to a string representation.

Returns:

a copy of the UTF-8 string representation of the internal data

inline const char *c_str() const noexcept#

Gets the string data owned by this Path.

Warning

the return value from this function should not be retained, and may be dangling after *this is modified in any way.

Returns:

pointer to the start of the path data

inline const char *getStringBuffer() const noexcept#

Gets the string data owned by this Path.

Warning

the return value from this function should not be retained, and may be dangling after *this is modified in any way.

Returns:

pointer to the start of the path data

inline std::ostream &operator<<(std::ostream &os, const Path &path)#

Enables outputting this Path to a stream object.

Parameters:

• os – the stream to output to

• path – the Path to output

inline explicit operator const char*() const noexcept#

Explicit conversion operator to get the string data owned by this Path.

Warning

the return value from this function should not be retained, and may be dangling after *this is modified in any way.

Returns:

pointer to the start of the path data

inline bool operator==(const Path &other) const noexcept#

Equality comparison.

Parameters:

other – a Path to compare against *this for equality

Returns:

true if *this and other are equal; false otherwise

inline bool operator==(const std::string &other) const noexcept#

Equality comparison.

Parameters:

other – a std::string to compare against *this for equality

Returns:

true if *this and other are equal; false otherwise

inline bool operator==(const char *other) const noexcept#

Equality comparison.

Parameters:

other – a NUL-terminated char buffer to compare against *this for equality

Returns:

true if *this and other are equal; false otherwise (or if other is nullptr)

inline bool operator!=(const Path &other) const noexcept#

Inequality comparison.

Parameters:

other – a Path to compare against *this for inequality

Returns:

true if *this and other are not equal; false otherwise

inline bool operator!=(const std::string &other) const noexcept#

Inequality comparison.

Parameters:

other – a std::string to compare against *this for inequality

Returns:

true if *this and other are not equal; false otherwise

inline bool operator!=(const char *other) const noexcept#

Inequality comparison.

Parameters:

other – a NUL-terminated char buffer to compare against *this for inequality

Returns:

true if *this and other are not equal; false otherwise (or if other is nullptr)

inline size_t getLength() const noexcept#

Gets the length of the path.

Returns:

the length of the path string data in bytes

inline size_t length() const noexcept#

Gets the length of the path.

Returns:

the length of the path string data in bytes

inline size_t size() const noexcept#

Gets the length of the path.

Returns:

the length of the path string data in bytes

inline Path &clear()#

Clears current path.

Returns:

*this

inline bool isEmpty() const noexcept#

Checks if the path is an empty string.

Returns:

true if the path contains at least one character; false otherwise

inline bool empty() const noexcept#

Checks if the path is an empty string.

Returns:

true if the path contains at least one character; false otherwise

inline Path getFilename() const#

Returns the filename component of the path, or an empty path object if there is no filename.

Example: given C:/foo/bar.txt, this function would return bar.txt.

Returns:

The path object representing the filename

inline Path getExtension() const#

Returns the extension of the filename component of the path, including period (.), or an empty path object.

Example: given C:/foo/bar.txt, this function would return .txt.

Returns:

The path object representing the extension

inline Path getParent() const#

Returns the path to the parent directory, or an empty path object if there is no parent.

Example: given C:/foo/bar.txt, this function would return C:/foo.

Returns:

The path object representing the parent directory

inline Path getStem() const#

Returns the filename component of the path stripped of the extension, or an empty path object if there is no filename.

Example: given C:/foo/bar.txt, this function would return bar.

Returns:

The path object representing the stem

inline Path getRootName() const#

Returns the root name in the path.

Example: given C:/foo/bar.txt, this function would return C:. Example: given //server/share, this function would return //server.

Returns:

The path object representing the root name

inline Path getRelativePart() const#

Returns the relative part of the path (the part after optional root name and root directory).

Example: given C:/foo/bar.txt, this function would return foo/bar.txt. Example: given //server/share/foo.txt, this function would return share/foo.txt.

Returns:

The path objects representing the relative part of the path

inline Path getRootDirectory() const#

Returns the root directory if it’s present in the path.

Example: given C:/foo/bar.txt, this function would return /. Example: given foo/bar.txt, this function would return `` (empty Path).

Note

This function will only ever return an empty path or a forward slash.

Returns:

The path object representing the root directory

inline bool hasRootDirectory() const noexcept#

Checks if the path has a root directory.

Returns:

true if getRootDirectory() would return /; false if getRootDirectory() would return an empty string.

inline Path getRoot() const#

Returns the root of the path: the root name and root directory if they are present.

Example: given C:/foo/bar.txt, this function would return C:/.

Returns:

The path object representing the root of the path

inline Path concat(const Path &toAppend) const#

A helper function to append another path after *this and return as a new object.

Note

Unlike join(), this function concatenates two Path objects without a path separator between them.

Parameters:

toAppend – the Path to append to *this

Returns:

a new Path object that has *this appended with toAppend.

inline Path join(const Path &toJoin) const#

A helper function to append another path after *this with a separator if necessary and return as a new object.

Parameters:

toJoin – the Path object to append to *this

Returns:

a new Path object that has *this followed by a separator (if one is not already present at the end of *this or the beginning of toJoin), followed by toJoin

inline Path &operator/=(const Path &path)#

Appends a path to *this with a separator if necessary.

Note

Unlike join(), *this is modified by this function.

Parameters:

path – the Path to append to *this

Returns:

*this

inline Path &operator+=(const Path &path)#

Appends a path to *this without adding a separator.

Note

Unlike concat(), *this is modified by this function.

Parameters:

path – The Path to append to *this

Returns:

*this

inline Path &replaceExtension(const Path &newExtension)#

Replaces the current file extension with the given extension.

Parameters:

newExtension – the new extension to use

Returns:

*this

inline Path getAbsolute(const Path &root = Path()) const#

Normalizes *this as an absolute path and returns as a new Path object.

Note

If *this is already an absolute path as determined by isAbsolute(), root is ignored.

Warning

This function does NOT make an absolute path using the CWD as a root. You need to use carb::filesystem::IFileSystem to get the current working directory and pass it to this function if desired.

Parameters:

root – The root Path to prepend to *this

Returns:

A new Path object representing the constructed absolute path

inline Path getNormalized() const#

Returns the result of the normalization of the current path as a new path.

Example: given C:/foo/./bar/../bat.txt, this function would return C:/foo/bat.txt.

Returns:

A new Path object representing the normalized current path

inline Path &normalize()#

Normalizes current path in place.

Example: given C:/foo/./bar/../bat.txt, this function would change *this to contain C:/foo/bat.txt.

Note

Unlike getNormalized(), *this is modified by this function.

Returns:

*this

inline bool isAbsolute() const noexcept#

Checks if the current path is an absolute path.

Returns:

true if the current path is an absolute path; false otherwise.

inline bool isRelative() const#

Checks if the current path is a relative path.

Effectively, !isAbsolute().

Returns:

true if the current path is a relative path; false otherwise.

inline Path getRelative(const Path &base) const noexcept#

Returns current path made relative to a given base as a new Path object.

Note

The paths are not normalized prior to the operation.

Parameters:

base – the base path

Returns:

an empty path if it’s impossible to match roots (different root names, different states of being relative/absolute with a base path, not having a root directory while the base has it), otherwise a non-empty relative path

Public Static Attributes

static constexpr size_t npos = std::string::npos#

A special value depending on the context, such as “all remaining characters”.