E-MailRelay
Public Member Functions | Static Public Member Functions | Friends | List of all members
G::Path Class Reference

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

#include <gpath.h>

Public Member Functions

 Path ()
 Default constructor for a zero-length path. More...
 
 Path (const std::string &path)
 Implicit constructor from a string. More...
 
 Path (const char *path)
 Implicit constructor from a c-style 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...
 
 Path (std::initializer_list< std::string >)
 Constructor with implicit pathAppend()s. More...
 
std::size_t size () const noexcept
 Returns the length of the path string. More...
 
bool empty () const noexcept
 Returns true if size() is zero. More...
 
std::string str () const
 Returns the path string. More...
 
const char * cstr () const noexcept
 Returns the path 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...
 
bool isAbsolute () const
 Returns !isRelative(). More...
 
bool isRelative () const
 Returns true if the path is a relative path or empty(). More...
 
void pathAppend (const std::string &tail)
 Appends a filename or a relative path to this path. 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
 Comparison operator. More...
 
bool operator!= (const Path &path) const
 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...
 

Friends

class G::PathImp
 

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.

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 71 of file gpath.h.

Constructor & Destructor Documentation

◆ Path() [1/7]

G::Path::Path ( )
default

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 260 of file gpath.cpp.

◆ Path() [3/7]

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

Implicit constructor from a c-style string.

Definition at line 266 of file gpath.cpp.

◆ Path() [4/7]

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

Constructor with an implicit pathAppend().

Definition at line 272 of file gpath.cpp.

◆ Path() [5/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 279 of file gpath.cpp.

◆ Path() [6/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 287 of file gpath.cpp.

◆ Path() [7/7]

G::Path::Path ( std::initializer_list< std::string >  args)

Constructor with implicit pathAppend()s.

(Recall that this overload will be strongly preferred when using curly-brace initialisation.)

Definition at line 297 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 328 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 433 of file gpath.cpp.

◆ cstr()

const char * G::Path::cstr ( ) const
inlinenoexcept

Returns the path string.

Definition at line 221 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 493 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 336 of file gpath.cpp.

◆ empty()

bool G::Path::empty ( ) const
inlinenoexcept

Returns true if size() is zero.

Definition at line 203 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 391 of file gpath.cpp.

◆ isAbsolute()

bool G::Path::isAbsolute ( ) const

Returns !isRelative().

Definition at line 318 of file gpath.cpp.

◆ isRelative()

bool G::Path::isRelative ( ) const

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

Definition at line 323 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 414 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 408 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 483 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 308 of file gpath.cpp.

◆ operator!=()

bool G::Path::operator!= ( const Path path) const

Comparison operator.

Definition at line 467 of file gpath.cpp.

◆ operator==()

bool G::Path::operator== ( const Path path) const

Comparison operator.

Definition at line 462 of file gpath.cpp.

◆ pathAppend()

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

Appends a filename or a relative path to this path.

Definition at line 375 of file gpath.cpp.

◆ setPosixStyle()

void G::Path::setPosixStyle ( )
static

Sets posix mode for testing purposes.

Definition at line 247 of file gpath.cpp.

◆ setWindowsStyle()

void G::Path::setWindowsStyle ( )
static

Sets windows mode for testing purposes.

Definition at line 252 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 313 of file gpath.cpp.

◆ size()

std::size_t G::Path::size ( ) const
inlinenoexcept

Returns the length of the path string.

Definition at line 209 of file gpath.h.

◆ 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 400 of file gpath.cpp.

◆ str()

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

Returns the path string.

Definition at line 215 of file gpath.h.

◆ swap()

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

Swaps this with other.

Definition at line 472 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 364 of file gpath.cpp.

◆ withoutExtension()

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

Returns a path without the basename extension, if any.

As a special case, a basename() that starts with a dot is replaced by a single dot. Prefer withExtension() where appropriate to avoid this.

Definition at line 346 of file gpath.cpp.

Friends And Related Function Documentation

◆ G::PathImp

friend class G::PathImp
friend

Definition at line 198 of file gpath.h.


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