Paths (C++)

group Geolib3PathUtils

All of these functions (which take as input an absolute scene graph location path) assume a properly normalized scene graph path:

  • no trailing slash ‘/’

  • no redundent internal separator (A//B, A/B/, A/./B and A/foo/../B all become A/B.)

Examples of normalized locations:

/root
/root/world/geo
/root/world/taco/a/b

Examples of un-normalised locations:

/root/
/root/world/
/root/world/../a
/root/world/taco//a/b

Functions

std::string NormalizeAbsPath(const std::string &locationPath)
std::string GetLocationParent(FnPlatform::StringView locationPath)

GetLocationParent('/root/world/geo') => '/root/world'
GetLocationParent('/root') => ''

Returns:

the parent scene graph location path for the given input e.g.

std::string GetLeafName(FnPlatform::StringView locationPath)

GetLeafName('/a/b/c') => 'c'

Returns:

the leaf for the given input e.g.

void GetLeafAndParent(std::string &parent, std::string &leaf, FnPlatform::StringView locationPath)
std::vector<std::string> GetLocationStack(FnPlatform::StringView locationPath, FnPlatform::StringView rootPath = FnPlatform::StringView())

Example:

GetLocationStack('/a/b/c') => ['/a','/a/b','/a/b/c']
GetLocationStack('/a/b/c/d/e', root='/a/b/c') => ['/a/b/c', '/a/b/c/d', '/a/b/c/d/e']
GetLocationStack('/a/b/c', root='/a/b/c') => ['/a/b/c']

See also

GetLocationStackStringView()

Parameters:

  • locationPath – The location path to be processed.

  • rootPath – An optional ‘root’ location from which to begin.

Returns:

Stack that contains the strings. If the input path is not normalized, or the root path is provided but is not an ancestor of the input path, an empty stack will be returned.

std::vector<FnPlatform::StringView> GetLocationStackStringView(FnPlatform::StringView locationPath, FnPlatform::StringView rootPath = FnPlatform::StringView())

Example:

GetLocationStackStringView('/a/b/c') => ['/a', '/a/b', '/a/b/c']
GetLocationStackStringView('/a/b/c/d', root='/a/b') => ['/a/b', '/a/b/c', '/a/b/c/d']
GetLocationStackStringView('/a/b/c', root='/a/b/c') => ['/a/b/c']

Warning

The return stack contains string views that reference the input string; it must never outlive the input location path.

Parameters:

  • locationPath – The location path to be processed.

  • rootPath – An optional ‘root’ location from which to begin.

Returns:

Stack that contains the string views. If the input path is not normalized, or the root path is provided but is not an ancestor of the input path, an empty stack will be returned.

bool IsAncestorOrEqual(FnPlatform::StringView locA, FnPlatform::StringView locB)

Example: 

IsAncestorOrEqual('/root/a','/root/a/b/c') => true
IsAncestorOrEqual('/root/a','/root/a') => true

Parameters:

  • locA – scene graph location A

  • locB – scene graph location B

Returns:

true if location A is an ancestor or equal of location B

bool IsAncestor(FnPlatform::StringView locA, FnPlatform::StringView locB)

Example

IsAncestor('/root/a','/root/a/b/c') => true
IsAncestor('/root/a','/root/a') => false
Parameters:

  • locA – scene graph location A

  • locB – scene graph location B

Returns:

true if location A is an ancestor of location B

std::string Join(FnPlatform::StringView locA, FnPlatform::StringView locB)
bool IsRelativePath(const std::string &path)
std::string RelativeToAbsPath(const std::string &rootPath, const std::string &path)

Example: 

RelativeToAbsPath('/root/world','../') => '/root'

Parameters:

  • rootPath – the path from which to generate the new absolute path

  • path – the relative path specifier.

Returns:

a new absolute path given the rootPath and path.

std::string NormalizedRelativePath(const std::string &rootpath, const std::string &path)

Given a rootpath, and either a relative or absolute path, create a normalized relative path.

Example: 

NormalizedRelativePath('/root','/root/world') -> 'world'
NormalizedRelativePath('/root','/root/world/geo') -> 'world/geo'
NormalizedRelativePath('/root','/root') -> ''
NormalizedRelativePath('/root','/notroot') -> EXCEPTION
NormalizedRelativePath('/root','a/b/c') -> 'a/b/c'

Note

This function will throw an exception if root is not ancestor or equal to path.

Parameters:

  • rootpath – the root path

  • path – the full path from which to generate the relative path.

Returns:

a normalized relative path

std::string RelativePath(const std::string &rootPath, const std::string &path)

Given two absolute paths, create a relative path from rootPath to path even if rootPath is not an ancestor of path).

Example: 

RelativePath('/root/world/geo', '/root/world/geo/a') -> 'a'
RelativePath('/root/world/geo/a', '/root/world/geo') -> '..'
RelativePath('/root/world/geo/a', '/root/world/geo/b') -> '../b'
RelativePath('/root/world/geo/a', '/root/world/geo/a') -> ''
RelativePath('/root/world/geo/a', '/root/world/cam/a') -> '../../cam/a'

Parameters:

  • rootPath – the root path

  • path – path to generate the relative path to.

Returns:

a relative path from rootPath to path

void FnMatch(FnMatchInfo &matchInfo, FnPlatform::StringView testpath, FnPlatform::StringView pattern)

Note

testpath and pattern should be absolute scene graph paths, normalized in the style of pystring::normpath_posix

Parameters:

  • matchInfo – instance of match info

  • testpath – scene graph path to be tested

  • pattern – pattern to match against.

void FnMatchIncludingAncestors(FnMatchInfo &matchInfo, FnPlatform::StringView testpath, FnPlatform::StringView pattern)

Note

testpath and pattern should be absolute scene graph paths, normalized in the style of pystring::normpath_posix

Parameters:

  • matchInfo – instance of match info

  • testpath – scene graph path to be tested

  • pattern – pattern to match against.

void ExactMatch(FnMatchInfo &matchInfo, FnPlatform::StringView testpath, FnPlatform::StringView pattern)

Note

testpath and pattern should be absolute scene graph paths, normalized in the style of pystring::normpath_posix

Parameters:

  • matchInfo – instance of match info

  • testpath – scene graph path to be tested

  • pattern – pattern to match against.

std::string MakeUniqueName(FnPlatform::StringView baseName, const std::set<std::string> &existingNames)
std::string MakeSafeIdentifier(FnPlatform::StringView identifier)
int Compare(FnPlatform::StringView pathA, FnPlatform::StringView pathB)

Compares two scene graph location paths.

Each path component of pathA is compared lexicographically with the corresponding component of pathB. The function assumes normalized, absolute paths (except for superfluous trailing slashes, which are ignored).

Parameters:

  • pathA – scene graph location path A

  • pathB – scene graph location path A

Returns:

a negative value if pathA sorts before pathB, zero if both paths compare equal, and a positive value if pathA sorts after pathB.

struct FnMatchInfo

Public Members

bool match
bool canMatchChildren