E-MailRelay

Public Types | Public Member Functions | Static Public Member Functions | List of all members
G::Path Class Reference

A Path object represents a file system path. More...

`#include <gpath.h>`

## Public Types
using | value_type = char
using | string_type = std::string
using | iopath_char_type = char

## Public Member Functions
| Path () noexcept(noexcept(std::string()))
| Default constructor for a zero-length path. More...
| Path (const std::string &path)
| Implicit constructor from a string. More...
| Path (std::string_view path)
| Implicit constructor from a string view. More...
| Path (const char *path)
| Implicit constructor from a c string. More...
| Path (const Path &path, const std::string &tail)
| Constructor with an implicit pathAppend(). More...
| Path (const Path &path, const std::string &tail_1, const std::string &tail_2)
| Constructor with two implicit pathAppend()s. More...
| Path (const Path &path, const std::string &tail_1, const std::string &tail_2, const std::string &tail_3)
| Constructor with three implicit pathAppend()s. More...
bool | empty () const noexcept
| Returns true if the path is empty. More...
std::string | str () const
| Returns the path string. More...
const iopath_char_type * | iopath () const
| Returns the path's string with a type that is suitable for initialising std::fstreams. More...
const value_type * | cstr () const noexcept
| Returns the path's c-string. More...
bool | simple () const
| Returns true if the path has a single component (ignoring "." parts), ie. More...
std::string | basename () const
| Returns the rightmost part of the path, ignoring "." parts. More...
Path | dirname () const
| Returns the path without the rightmost part, ignoring "." parts. More...
std::string | extension () const
| Returns the path's basename extension, ie. More...
Path | withExtension (const std::string &ext) const
| Returns the path with the new basename extension. More...
Path | withoutExtension () const
| Returns a path without the basename extension, if any. More...
Path | withoutRoot () const
| Returns a path without the root part. More...
bool | isRoot () const noexcept
| Returns true if the path is a root, like "/", "c:", "c:/", "\\server\volume" etc. More...
bool | isAbsolute () const noexcept
| Returns !isRelative(). More...
bool | isRelative () const noexcept
| Returns true if the path is a relative path or empty(). More...
Path & | pathAppend (const std::string &tail)
| Appends a filename or a relative path to this path. More...
bool | replace (const std::string_view &from, const std::string_view &to, bool ex_root=false)
| Replaces the first occurrence of 'from' with 'to', optionally excluding the root part. More...
StringArray | split () const
| Spits the path into a list of component parts (ignoring "." parts unless the whole path is "."). More...
Path | collapsed () const
| Returns the path with "foo/.." and "." parts removed, so far as is possible without changing the meaning of the path. More...
void | swap (Path &other) noexcept
| Swaps this with other. More...
bool | operator== (const Path &path) const noexcept(noexcept(std::string().compare(std::string())))
| Comparison operator. More...
bool | operator!= (const Path &path) const noexcept(noexcept(std::string().compare(std::string())))
| Comparison operator. More...

## Static Public Member Functions
static Path | join (const StringArray &parts)
| Builds a path from a set of parts. More...
static Path | join (const Path &p1, const Path &p2)
| Joins two paths together. The second should be a relative path. More...
static Path | difference (const Path &p1, const Path &p2)
| Returns the relative path from p1 to p2. More...
static Path | nullDevice ()
| Returns the path of the "/dev/null" special file, or equivalent. More...
static void | setPosixStyle ()
| Sets posix mode for testing purposes. More...
static void | setWindowsStyle ()
| Sets windows mode for testing purposes. More...
static bool | less (const Path &a, const Path &b)
| Compares two paths, with simple eight-bit lexicographical comparisons of each path component. More...

## Detailed Description

A Path object represents a file system path.

The class is concerned with path syntax, not file system i/o.

A full path is made up of a root, a set of directories, and a filename. The posix root is just a forward slash, but on Windows the root can be complex, possibly including non-splitting separator characters. The filename may have an extension part, which is to the right of the right-most dot.

The path separator is used between directories and filename, but only between the root and the first directory if the root does not itself end in a separator character.

A windows drive-letter root may end with a separator character or not; if there is no separator character at the end of the drive-letter root then the path is relative to the drive's current working directory.

Path components of "." are ignored by simple(), basename(), and dirname(). Path components of ".." are retained but can be eliminated if they are collapsed(). Path components of "." are eliminated by split(), except in the degenerate case.

This class is agnostic on the choice of UTF-8 or eight-bit characters since the delimiters are all seven-bit ascii. Wide characters are not used, following "utf8everywhere.org" rather than std::filesystem::path (but see G_ANSI as a temporary deprecated feature).

Most file operations should be handled in o/s-aware source (see G::File, G::Environment, G::Process etc) so that the Path character encoding is opaque. However, std::fstream objects can be initialised directly by using G::Path::iopath().

Both posix and windows behaviours are available at run-time; the default behaviour is the native behaviour, but this can be overridden, typically for testing purposes.

The posix path separator character is the forward-slash; on Windows it is a back-slash, but with all forward-slashes converted to back-slashes immediately on input.

See also
  G::File, G::Directory

Definition at line 81 of file gpath.h.

## Member Typedef Documentation

## ◆ iopath_char_type

using G::Path::iopath_char_type = char

Definition at line 89 of file gpath.h.

## ◆ string_type

using G::Path::string_type = std::string

Definition at line 85 of file gpath.h.

## ◆ value_type

using G::Path::value_type = char

Definition at line 84 of file gpath.h.

## Constructor & Destructor Documentation

## ◆ Path() [1/7]

G::Path::Path | ( |  | ) |
| default noexcept

Default constructor for a zero-length path.

Postcondition: empty()

## ◆ Path() [2/7]

G::Path::Path | ( | const std::string & | path | ) |

Implicit constructor from a string.

Definition at line 267 of file gpath.cpp.

## ◆ Path() [3/7]

G::Path::Path | ( | std::string_view | path | ) |

Implicit constructor from a string view.

Definition at line 279 of file gpath.cpp.

## ◆ Path() [4/7]

G::Path::Path | ( | const char * | path | ) |

Implicit constructor from a c string.

Definition at line 273 of file gpath.cpp.

## ◆ Path() [5/7]

G::Path::Path | ( | const Path & | path,
|  | const std::string & | tail
| ) |  |

Constructor with an implicit pathAppend().

Definition at line 285 of file gpath.cpp.

## ◆ Path() [6/7]

G::Path::Path | ( | const Path & | path,
|  | const std::string & | tail_1,
|  | const std::string & | tail_2
| ) |  |

Constructor with two implicit pathAppend()s.

Definition at line 293 of file gpath.cpp.

## ◆ Path() [7/7]

G::Path::Path | ( | const Path & | path,
|  | const std::string & | tail_1,
|  | const std::string & | tail_2,
|  | const std::string & | tail_3
| ) |  |

Constructor with three implicit pathAppend()s.

Definition at line 303 of file gpath.cpp.

## Member Function Documentation

## ◆ basename()

std::string G::Path::basename | ( |  | ) | const

Returns the rightmost part of the path, ignoring "." parts.

For a directory path this may be "..", but see also collapsed().

Definition at line 339 of file gpath.cpp.

## ◆ collapsed()

G::Path G::Path::collapsed | ( |  | ) | const

Returns the path with "foo/.." and "." parts removed, so far as is possible without changing the meaning of the path.

Parts like "../foo" at the beginning of the path, or immediately following the root, are not removed.

Definition at line 459 of file gpath.cpp.

## ◆ cstr()

const char * G::Path::cstr | ( |  | ) | const
| inline noexcept

Returns the path's c-string.

Typically used by o/s-aware code such as G::File.

Definition at line 249 of file gpath.h.

## ◆ difference()

G::Path G::Path::difference | ( | const Path & | p1,
|  | const Path & | p2
| ) |  |
| static

Returns the relative path from p1 to p2.

Returns the empty path if p2 is not under p1. Returns "." if p1 and p2 are the same. Input paths are collapsed(). Empty input paths are treated as ".".

Definition at line 525 of file gpath.cpp.

## ◆ dirname()

G::Path G::Path::dirname | ( |  | ) | const

Returns the path without the rightmost part, ignoring "." parts.

For simple() paths the empty path is returned.

Definition at line 347 of file gpath.cpp.

## ◆ empty()

bool G::Path::empty | ( |  | ) | const
| inline noexcept

Returns true if the path is empty.

Definition at line 237 of file gpath.h.

## ◆ extension()

std::string G::Path::extension | ( |  | ) | const

Returns the path's basename extension, ie.

anything after the rightmost dot. Returns the zero-length string if there is none.

Definition at line 411 of file gpath.cpp.

## ◆ iopath()

const G::Path::iopath_char_type * G::Path::iopath | ( |  | ) | const
| inline

Returns the path's string with a type that is suitable for initialising std::fstreams.

Definition at line 255 of file gpath.h.

## ◆ isAbsolute()

bool G::Path::isAbsolute | ( |  | ) | const
| noexcept

Returns !isRelative().

Definition at line 329 of file gpath.cpp.

## ◆ isRelative()

bool G::Path::isRelative | ( |  | ) | const
| noexcept

Returns true if the path is a relative path or empty().

Definition at line 334 of file gpath.cpp.

## ◆ isRoot()

bool G::Path::isRoot | ( |  | ) | const
| noexcept

Returns true if the path is a root, like "/", "c:", "c:/", "\\server\volume" etc.

Definition at line 324 of file gpath.cpp.

## ◆ join() [1/2]

G::Path G::Path::join | ( | const Path & | p1,
|  | const Path & | p2
| ) |  |
| static

Joins two paths together. The second should be a relative path.

Definition at line 440 of file gpath.cpp.

## ◆ join() [2/2]

G::Path G::Path::join | ( | const StringArray & | parts | ) |
| static

Builds a path from a set of parts.

Note that part boundaries are not necessarily preserved once they have been join()ed into a path.

Definition at line 434 of file gpath.cpp.

## ◆ less()

bool G::Path::less | ( | const Path & | a,
|  | const Path & | b
| ) |  |
| static

Compares two paths, with simple eight-bit lexicographical comparisons of each path component.

This is slightly different from a lexicographical comparison of the compete strings (eg. "a/b" compared to "a./b"), and it is not suitable for UTF-8 paths.

Definition at line 513 of file gpath.cpp.

## ◆ nullDevice()

G::Path G::Path::nullDevice | ( |  | ) |
| static

Returns the path of the "/dev/null" special file, or equivalent.

Definition at line 314 of file gpath.cpp.

## ◆ operator!=()

bool G::Path::operator!= | ( | const Path & | path | ) | const
| noexcept

Comparison operator.

Definition at line 501 of file gpath.cpp.

## ◆ operator==()

bool G::Path::operator== | ( | const Path & | path | ) | const
| noexcept

Comparison operator.

Definition at line 496 of file gpath.cpp.

## ◆ pathAppend()

G::Path & G::Path::pathAppend | ( | const std::string & | tail | ) |

Appends a filename or a relative path to this path.

Definition at line 404 of file gpath.cpp.

## ◆ replace()

bool G::Path::replace | ( | const std::string_view & | from,
|  | const std::string_view & | to,
|  | bool | ex_root = `false`
| ) |  |

Replaces the first occurrence of 'from' with 'to', optionally excluding the root part.

Returns true if replaced.

Definition at line 420 of file gpath.cpp.

## ◆ setPosixStyle()

void G::Path::setPosixStyle | ( |  | ) |
| static

Sets posix mode for testing purposes.

Definition at line 251 of file gpath.cpp.

## ◆ setWindowsStyle()

void G::Path::setWindowsStyle | ( |  | ) |
| static

Sets windows mode for testing purposes.

Definition at line 258 of file gpath.cpp.

## ◆ simple()

bool G::Path::simple | ( |  | ) | const

Returns true if the path has a single component (ignoring "." parts), ie.

the dirname() is empty.

Definition at line 319 of file gpath.cpp.

## ◆ split()

G::StringArray G::Path::split | ( |  | ) | const

Spits the path into a list of component parts (ignoring "." parts unless the whole path is ".").

Definition at line 426 of file gpath.cpp.

## ◆ str()

std::string G::Path::str | ( |  | ) | const
| inline

Returns the path string.

Definition at line 243 of file gpath.h.

## ◆ swap()

void G::Path::swap | ( | Path & | other | ) |
| noexcept

Swaps this with other.

Definition at line 506 of file gpath.cpp.

## ◆ withExtension()

G::Path G::Path::withExtension | ( | const std::string & | ext | ) | const

Returns the path with the new basename extension.

Any previous extension is replaced. The extension should not normally have a leading dot and it should not be the empty string.

Definition at line 375 of file gpath.cpp.

## ◆ withoutExtension()

G::Path G::Path::withoutExtension | ( |  | ) | const

Returns a path without the basename extension, if any.

Returns this path if there is no dot in the basename. As a special case, a basename() like ".foo" ends up as "."; prefer withExtension() where appropriate to avoid this.

Definition at line 357 of file gpath.cpp.

## ◆ withoutRoot()

G::Path G::Path::withoutRoot | ( |  | ) | const

Returns a path without the root part.

This has no effect if the path isRelative().

Definition at line 387 of file gpath.cpp.

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

- /tmp/slackdce/slackrepo.HKsbdz/build_emailrelay/emailrelay-2.6/src/glib/gpath.h
- /tmp/slackdce/slackrepo.HKsbdz/build_emailrelay/emailrelay-2.6/src/glib/gpath.cpp