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”.