Common::Path Class Reference

#include <path.h>

Classes
struct	EqualTo
struct	Hash
struct	IgnoreCase_EqualTo
struct	IgnoreCase_Hash
struct	IgnoreCaseAndMac_EqualTo
struct	IgnoreCaseAndMac_Hash

Public Member Functions
	Path ()
	Path (const Path &path)
	Path (const char *str, char separator='/')
	Path (const String &str, char separator='/')
String	toString (char separator='/') const
void	clear ()
Path	getParent () const
Path	getLastComponent () const
String	baseName () const
int	numComponents () const
bool	operator== (const Path &x) const
bool	operator!= (const Path &x) const
bool	equals (const Path &x) const
bool	equalsIgnoreCase (const Path &x) const
bool	equalsIgnoreCaseAndMac (const Path &x) const
uint	hash () const
uint	hashIgnoreCase () const
uint	hashIgnoreCaseAndMac () const
bool	operator< (const Path &x) const
bool	empty () const
Path &	operator= (const Path &path)
Path &	operator= (const char *str)
Path &	operator= (const String &str)
void	set (const char *str, char separator='/')
Path &	appendInPlace (const Path &x)
Path &	appendInPlace (const String &str, char separator='/')
Path &	appendInPlace (const char *str, char separator='/')
WARN_UNUSED_RESULT Path	append (const Path &x) const
WARN_UNUSED_RESULT Path	append (const String &str, char separator='/') const
WARN_UNUSED_RESULT Path	append (const char *str, char separator='/') const
WARN_UNUSED_RESULT Path	appendComponent (const char *str) const
WARN_UNUSED_RESULT Path	appendComponent (const String &x) const
Path &	joinInPlace (const Path &x)
Path &	joinInPlace (const String &str, char separator='/')
Path &	joinInPlace (const char *str, char separator='/')
WARN_UNUSED_RESULT Path	join (const Path &x) const
WARN_UNUSED_RESULT Path	join (const String &str, char separator='/') const
WARN_UNUSED_RESULT Path	join (const char *str, char separator='/') const
Path &	removeTrailingSeparators ()
bool	isSeparatorTerminated () const
bool	isRelativeTo (const Common::Path &other) const
Path	relativeTo (const Common::Path &other) const
Path	punycodeDecode () const
Path	punycodeEncode () const
bool	punycodeNeedsEncode () const
void	toLowercase ()
void	toUppercase ()
bool	matchPattern (const Path &pattern) const
Path	normalize () const
StringArray	splitComponents () const
String	toConfig () const

Static Public Member Functions
static Path	joinComponents (StringArray::const_iterator begin, StringArray::const_iterator end)
static Path	joinComponents (const StringArray &c)
static Path	fromConfig (const String &value)
static Path	fromCommandLine (const String &value)

Static Public Attributes
static const char	kNoSeparator = '\x00'
static const char	kNativeSeparator = '/'

Detailed Description

Simple path class. Allows simple conversion to/from path strings with arbitrary directory separators, providing a common representation.

Internally, this is just a simple wrapper around a String, using "/" as a directory separator. It escapes it using "|" if / is used inside a path component.

Constructor & Destructor Documentation

Path() [1/4]

Common::Path::Path ( )

inline

Construct a new empty path.

Path() [2/4]

Common::Path::Path ( const Path &  path )

inline

Construct a copy of the given path.

Path() [3/4]

Common::Path::Path ( const char *  str, char  separator = '/'  )

inline

Construct a new path from the given NULL-terminated C string.

Parameters

str	A NULL-terminated C string representing a path, e.g. "foo/bar/baz"
separator	The directory separator used in the path string. Use kNoSeparator if there is no separator. Defaults to '/'.

Path() [4/4]

Common::Path::Path ( const String &  str, char  separator = '/'  )

inlineexplicit

Construct a new path from the given String. This is explicit to limit mixing strings and paths in the codebase.

Parameters

str	A String representing a path, e.g. "foo/bar/baz"
separator	The directory separator used in the path string. Use kNoSeparator if there is no separator. Defaults to '/'.

Member Function Documentation

toString()

String Common::Path::toString

(

char

separator = '/'

)

const

Converts a path to a string using the given directory separator. Collisions in resulting path are checked and warned once.

Parameters

separator

The character used to separate directory names. kNoSeparator must not be used here. Defaults to '/'.

clear()

void Common::Path::clear ( )

inline

Clears the path object

getParent()

Path Common::Path::getParent

(

)

const

Returns the Path for the parent directory of this path.

Appending the getLastComponent() of a path to getParent() returns a path identical to the original path.

getLastComponent()

Path Common::Path::getLastComponent

(

)

const

Returns the last component of this path.

Appending the getLastComponent() of a path to getParent() returns a path identical to the original path.

baseName()

String Common::Path::baseName

(

)

const

Returns the last non-empty component of this path. Compared to getLastComponent(), baseName() doesn't return the trailing / if any.

numComponents()

int Common::Path::numComponents

(

)

const

Returns number of components in this path,

operator==()

bool Common::Path::operator== ( const Path &  x ) const

inline

Check whether this path is identical to path x.

operator!=()

bool Common::Path::operator!= ( const Path &  x ) const

inline

Check whether this path is different than path x.

equals()

bool Common::Path::equals ( const Path &  x ) const

inline

Check whether this path is identical to path x.

equalsIgnoreCase()

bool Common::Path::equalsIgnoreCase

(

const Path &

x

)

const

Check whether this path is identical to path x. Ignores case

equalsIgnoreCaseAndMac()

bool Common::Path::equalsIgnoreCaseAndMac

(

const Path &

x

)

const

Check whether this path is identical to path x. Ignores case, punycode and Mac path separator.

hash()

uint Common::Path::hash

(

)

const

Calculate a case sensitive hash of path

hashIgnoreCase()

uint Common::Path::hashIgnoreCase

(

)

const

Calculate a case insensitive hash of path

hashIgnoreCaseAndMac()

uint Common::Path::hashIgnoreCaseAndMac

(

)

const

Calculate a hash of path which is case insensitive. Ignores case, punycode and Mac path separator.

empty()

bool Common::Path::empty ( ) const

inline

Return if this path is empty

operator=() [1/3]

Path& Common::Path::operator= ( const Path &  path )

inline

Assign a given path to this path.

operator=() [2/3]

Path& Common::Path::operator= ( const char *  str )

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

operator=() [3/3]

Path& Common::Path::operator= ( const String &  str )

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

appendInPlace() [1/3]

Path& Common::Path::appendInPlace

(

const Path &

x

)

Appends the given path to this path (in-place). Does not automatically add a directory separator.

appendInPlace() [2/3]

Path& Common::Path::appendInPlace ( const String &  str, char  separator = '/'  )

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

appendInPlace() [3/3]

Path& Common::Path::appendInPlace	(	const char *	str,
		char	separator = '/'
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

append() [1/3]

WARN_UNUSED_RESULT Path Common::Path::append ( const Path &  x ) const

inline

Returns this path with the given path appended (out-of-place). Does not automatically add a directory separator.

append() [2/3]

WARN_UNUSED_RESULT Path Common::Path::append ( const String &  str, char  separator = '/'  ) const

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

append() [3/3]

WARN_UNUSED_RESULT Path Common::Path::append ( const char *  str, char  separator = '/'  ) const

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

appendComponent() [1/2]

WARN_UNUSED_RESULT Path Common::Path::appendComponent

(

const char *

str

)

const

Appends exactly one component, without any separators and prepends a separator if necessarry

appendComponent() [2/2]

WARN_UNUSED_RESULT Path Common::Path::appendComponent ( const String &  x ) const

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

joinInPlace() [1/3]

Path& Common::Path::joinInPlace

(

const Path &

x

)

Joins the given path to this path (in-place). Automatically adds a directory separator.

joinInPlace() [2/3]

Path& Common::Path::joinInPlace ( const String &  str, char  separator = '/'  )

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

joinInPlace() [3/3]

Path& Common::Path::joinInPlace	(	const char *	str,
		char	separator = '/'
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

join() [1/3]

WARN_UNUSED_RESULT Path Common::Path::join ( const Path &  x ) const

inline

Returns this path joined with the given path (out-of-place). Automatically adds a directory separator.

join() [2/3]

WARN_UNUSED_RESULT Path Common::Path::join ( const String &  str, char  separator = '/'  ) const

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

join() [3/3]

WARN_UNUSED_RESULT Path Common::Path::join ( const char *  str, char  separator = '/'  ) const

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

removeTrailingSeparators()

Path& Common::Path::removeTrailingSeparators

(

)

Removes the trainling separators if any in this path (in-place).

isSeparatorTerminated()

bool Common::Path::isSeparatorTerminated ( ) const

inline

Returns whether this path ends with a separator

isRelativeTo()

bool Common::Path::isRelativeTo ( const Common::Path &  other ) const

inline

Returns whether this path begins with other path

relativeTo()

Path Common::Path::relativeTo

(

const Common::Path &

other

)

const

Returns a new path relative to the other one. Returns a copy this if it wasn't relative to.

punycodeDecode()

Path Common::Path::punycodeDecode

(

)

const

Convert path from Punycode

punycodeEncode()

Path Common::Path::punycodeEncode

(

)

const

Convert path to Punycode

punycodeNeedsEncode()

bool Common::Path::punycodeNeedsEncode

(

)

const

Returns whether the path will need to be Punycoded

toLowercase()

void Common::Path::toLowercase ( )

inline

Convert all characters in the path to lowercase.

Be aware that this only affects the case of ASCII characters. All other characters will not be touched at all.

toUppercase()

void Common::Path::toUppercase ( )

inline

Convert all characters in the path to uppercase.

Be aware that this only affects the case of ASCII characters. All other characters will not be touched at all.

matchPattern()

bool Common::Path::matchPattern

(

const Path &

pattern

)

const

Check pattern match similar matchString

normalize()

Path Common::Path::normalize

(

)

const

Normalize path to a canonical form. In particular:

• trailing separators are removed: /foo/bar/ -> /foo/bar
• double separators (= empty components) are removed: /foo//bar -> /foo/bar
• dot components are removed: /foo/./bar -> /foo/bar
• double dot components are removed: /foo/baz/../bar -> /foo/bar

Returns

the normalized path

splitComponents()

StringArray Common::Path::splitComponents

(

)

const

Splits into path components. After every component except last there is an implied separator. First component is empty if path starts with a separator. Last component is empty if the path ends with a separator. Other components may be empty if 2 separots follow each other

joinComponents()

static Path Common::Path::joinComponents ( StringArray::const_iterator  begin, StringArray::const_iterator  end  )

static

Opposite of splitComponents

toConfig()

String Common::Path::toConfig

(

)

const

Use by ConfigManager to store a path in a protected fashion All components are punyencoded and / is used as a delimiter for all platforms Under Windows don't encode when it's not needed and make use of \ separator in this case

fromConfig()

static Path Common::Path::fromConfig ( const String &  value )

static

Used by ConfigManager to parse a configuration value in a backwards compatible way

fromCommandLine()

static Path Common::Path::fromCommandLine ( const String &  value )

static

Creates a path from a string given by the user

Member Data Documentation

kNoSeparator

const char Common::Path::kNoSeparator = '\x00'

static

A separator to use when building path conataining only base names This must not be used with toString(), use baseName() instead.

kNativeSeparator

const char Common::Path::kNativeSeparator = '/'

static

The platform native separator. This is used when accessing files on disk

---

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

• common/path.h