Parse and compose filesystem paths for windows and posix. More...

#include <Path.h>

Classes
struct	ParsedView
	Holds the various parsed components of a path. More...

struct	Posix

struct	Windows

Public Types
enum	Type { AsPosix , AsWindows , AsNative = AsPosix }
	Path type (windows or posix) More...

Static Public Member Functions
static bool	join (String &output, Span< const StringView > inputs, StringView separator=SeparatorStringView(), bool skipEmpty=false)
	Joins multiple StringView with a Separator into an output String.

static bool	parseNameExtension (const StringView input, StringView &name, StringView &extension)
	Splits a StringView of type "name.ext" into "name" and "ext".

static bool	parse (StringView input, Path::ParsedView &pathView, Type type)
	Splits a Posix or Windows path into a ParsedView.

static StringView	dirname (StringView input, Type type, int repeat=0)
	Returns the directory name of a path.

static StringView	basename (StringView input, Type type)
	Returns the base name of a path.

static StringView	basename (StringView input, StringView suffix)
	Returns the base name of a path.

static bool	isAbsolute (StringView input, Type type)
	Checks if a path is absolute.

static constexpr StringView	SeparatorStringView ()
	Path separator StringView for current platform.

template<int numComponents = 64>
static bool	normalize (String &output, StringView view, Type type)
	Resolves all `..` to output a normalized path String.

static bool	normalize (String &output, StringView view, Type type, Span< StringView > components)
	Resolves all `..` to output a normalized path String (allows custom span of components)

static bool	relativeFromTo (StringView source, StringView destination, String &output, Type type, Type outputType=AsNative)
	Get relative path that appended to `source` resolves to `destination`.

static bool	append (String &output, Span< const StringView > paths, Type inputType)
	Append to an existing path a series of StringView with a separator.

static bool	endsWithSeparator (StringView path)
	Check if the path ends with a Windows or Posix separator.

static StringView	removeStartingSeparator (StringView path)
	Return a path without its (potential) starting separator.

static bool	normalizeUNCAndTrimQuotes (String &outputPath, StringView fileLocation, Type type, Span< StringView > components)
	An extended Path::normalize handling a bug with incorrect FILE backslash escape on Windows when using UNC Paths, and also removing quote characters '"' added when passing such paths to compiler command line.

Static Public Attributes
static constexpr char	Separator = '/'
	Path separator char for current platform.

Detailed Description

Parse and compose filesystem paths for windows and posix.

Member Enumeration Documentation

◆ Type

enum SC::Path::Type

Path type (windows or posix)

Member Function Documentation

◆ append()

static bool SC::Path::append	(	String &	output,
		Span< const StringView >	paths,
		Type	inputType )

staticnodiscard

Append to an existing path a series of StringView with a separator.

Parameters

[out]	output	The destination string containing the existing path, that will be extended
[in]	paths	The path components to join, appended to `output`
[in]	inputType	Specify to append as Windows or Posix path components

Returns: true if the output path can joined properly

◆ basename() [1/2]

static StringView SC::Path::basename	(	StringView	input,
		StringView	suffix )

staticnodiscard

Returns the base name of a path.

Suffix is stripped if existing. Trailing separators are ignored.

For example:

Path::basename("/a/basename.html", ".html") == "basename";

SC::Path::basename

static StringView basename(StringView input, Type type)

Returns the base name of a path.

Parameters

[in]	input	The StringView with path to be parsed. Trailing separators are ignored.
[in]	suffix	The StringView extension (or suffix in general) to strip if existing.

Returns: Substring of input holding the base name

◆ basename() [2/2]

static StringView SC::Path::basename	(	StringView	input,
		Type	type )

staticnodiscard

Returns the base name of a path.

Trailing separators are ignored.

For example:

Path::basename("/a/basename", Path::AsPosix) == "basename";

Path::basename("/a/basename//", Path::AsPosix) == "basename";

Parameters

[in]	input	The StringView with path to be parsed. Trailing separators are ignored.
[in]	type	Specify to parse as Windows or Posix path

Returns: Substring of input holding the base name

◆ dirname()

static StringView SC::Path::dirname	(	StringView	input,
		Type	type,
		int	repeat = 0 )

staticnodiscard

Returns the directory name of a path.

Trailing separators are ignored.

For example:

Path::dirname("/dirname/basename", Path::AsPosix) == "/dirname";
Path::dirname("/dirname/basename//", Path::AsPosix) == "/dirname";
Path::dirname("C:\\dirname\\basename", Path::AsWindows) == "C:\\dirname";
Path::dirname("\\dirname\\basename\\\\", Path::AsWindows) == "\\dirname";

Parameters

[in]	input	The StringView with path to be parsed. Trailing separators are ignored.
[in]	type	Specify to parse as Windows or Posix path
	repeat	how many directory levels should be removed `dirname("/1/2/3/4", repeat=1) == "/1/2"`

Returns: Substring of input holding the directory name

◆ endsWithSeparator()

static bool SC::Path::endsWithSeparator ( StringView path )

staticnodiscard

Check if the path ends with a Windows or Posix separator.

Parameters

path	The path to check

Returns: true if path ends with a separator

◆ isAbsolute()

static bool SC::Path::isAbsolute	(	StringView	input,
		Type	type )

staticnodiscard

Checks if a path is absolute.

For example:

Path::isAbsolute("/dirname/basename", Path::AsPosix) == true;        // Posix Absolute
Path::isAbsolute("./dirname/basename", Path::AsPosix) == false;      // Posix Relative
Path::isAbsolute("C:\\dirname\\basename", Path::AsWindows) == true;  // Windows with Drive
Path::isAbsolute("\\\\server\\dir", Path::AsWindows) == true;        // Windows with Network
Path::isAbsolute("\\\\?\\C:\\server\\dir", Path::AsWindows) == true; // Windows with Long
Path::isAbsolute("..\\dirname\\basename", Path::AsWindows) == false; // Windows relative

Parameters

[in]	input	The StringView with path to be parsed. Trailing separators are ignored.
[in]	type	Specify to parse as Windows or Posix path

Returns: true if input is absolute

◆ join()

static bool SC::Path::join	(	String &	output,
		Span< const StringView >	inputs,
		StringView	separator = SeparatorStringView(),
		bool	skipEmpty = false )

staticnodiscard

Joins multiple StringView with a Separator into an output String.

Parameters

[out]	output	The output string receiving the path
[in]	inputs	The input paths to join
[in]	separator	The separator to use. By default `/` on Posix and `\` on Windows
[in]	skipEmpty	If true will skip empty entries in `inputs` Span

Returns: true if the Path was successfully joined

◆ normalize() [1/2]

template<int numComponents = 64>

static bool SC::Path::normalize	(	String &	output,
		StringView	view,
		Type	type )

inlinestaticnodiscard

Resolves all .. to output a normalized path String.

For example:

Path::normalize("/Users/SC/../Documents/", &path, Path::AsPosix);

SC_RELEASE_ASSERT(path == "/Users/Documents");

SC::Path::normalize

static bool normalize(String &output, StringView view, Type type)

Resolves all .. to output a normalized path String.

Definition Path.h:199

Parameters

[out]	output	Reference to String that will receive the normalized Path
	view	The path to be normalized (but it should not be a view() of the output String)
	type	Specify to parse as Windows or Posix path

Returns: true if the Path was successfully parsed and normalized

◆ normalize() [2/2]

static bool SC::Path::normalize	(	String &	output,
		StringView	view,
		Type	type,
		Span< StringView >	components )

staticnodiscard

Resolves all .. to output a normalized path String (allows custom span of components)

◆ normalizeUNCAndTrimQuotes()

static bool SC::Path::normalizeUNCAndTrimQuotes	(	String &	outputPath,
		StringView	fileLocation,
		Type	type,
		Span< StringView >	components )

staticnodiscard

An extended Path::normalize handling a bug with incorrect FILE backslash escape on Windows when using UNC Paths, and also removing quote characters '"' added when passing such paths to compiler command line.

◆ parse()

static bool SC::Path::parse	(	StringView	input,
		Path::ParsedView &	pathView,
		Type	type )

staticnodiscard

Splits a Posix or Windows path into a ParsedView.

Parameters

[in]	input	The StringView with path to be parsed
[out]	pathView	The output parsed ParsedView with all components of path
[in]	type	Specify to parse as Windows or Posix path

Returns: true if path was parsed successfully

◆ parseNameExtension()

static bool SC::Path::parseNameExtension	(	const StringView	input,
		StringView &	name,
		StringView &	extension )

staticnodiscard

Splits a StringView of type "name.ext" into "name" and "ext".

Parameters

[in]	input	An input path coded as UTF8 sequence (ex. "name.ext")
[out]	name	Output string holding name ("name" in "name.ext")
[out]	extension	Output string holding extension ("ext" in "name.ext")

Returns: false if both name and extension will be empty after trying to parse them

Example:

    SC_TEST_EXPECT(Path::parseNameExtension("name.ext", name, ext));
    SC_TEST_EXPECT(name == "name");
    SC_TEST_EXPECT(ext == "ext");
 
    SC_TEST_EXPECT(!Path::parseNameExtension("", name, ext));
    SC_TEST_EXPECT(name.isEmpty());
    SC_TEST_EXPECT(ext.isEmpty());
 
    SC_TEST_EXPECT(!Path::parseNameExtension(".", name, ext));
    SC_TEST_EXPECT(name.isEmpty());
    SC_TEST_EXPECT(ext.isEmpty());
 
    SC_TEST_EXPECT(Path::parseNameExtension(".ext", name, ext));
    SC_TEST_EXPECT(name.isEmpty());
    SC_TEST_EXPECT(ext == "ext");
 
    SC_TEST_EXPECT(Path::parseNameExtension("name.", name, ext));
    SC_TEST_EXPECT(name == "name");
    SC_TEST_EXPECT(ext.isEmpty());
 
    SC_TEST_EXPECT(Path::parseNameExtension("name.name.ext", name, ext));
    SC_TEST_EXPECT(name == "name.name");
    SC_TEST_EXPECT(ext == "ext");
 
    SC_TEST_EXPECT(Path::parseNameExtension("name..", name, ext));
    SC_TEST_EXPECT(name == "name.");
    SC_TEST_EXPECT(ext.isEmpty());

◆ relativeFromTo()

static bool SC::Path::relativeFromTo	(	StringView	source,
		StringView	destination,
		String &	output,
		Type	type,
		Type	outputType = AsNative )

staticnodiscard

Get relative path that appended to source resolves to destination.

For example:

Path::relativeFromTo("/a/b/1/2/3", "/a/b/d/e", path, Path::AsPosix, Path::AsPosix);

SC_TEST_ASSERT(path == "../../../d/e");

SC::Path::relativeFromTo

static bool relativeFromTo(StringView source, StringView destination, String &output, Type type, Type outputType=AsNative)

Get relative path that appended to source resolves to destination.

Parameters

[in]	source	The source Path
[in]	destination	The destination Path
[out]	output	The output relative path computed that transforms source into destination
[in]	type	Specify to parse as Windows or Posix path
[in]	outputType	Specify if the output relative path should be formatted as a Posix or Windows path

Returns: true if source and destination paths can be properly parsed as absolute paths

◆ removeStartingSeparator()

static StringView SC::Path::removeStartingSeparator ( StringView path )

staticnodiscard

Return a path without its (potential) starting separator.

Parameters

path	The path to use

Returns: A StringView without its initial separator

◆ SeparatorStringView()

static constexpr StringView SC::Path::SeparatorStringView ( )

inlinestaticnodiscardconstexpr

Path separator StringView for current platform.

Member Data Documentation

◆ Separator

char SC::Path::Separator = '/'

staticconstexpr

Path separator char for current platform.

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

Path.h

Classes

Public Types

Static Public Member Functions

Static Public Attributes

Detailed Description

Member Enumeration Documentation

◆ Type

Member Function Documentation

◆ append()

◆ basename() [1/2]

◆ basename() [2/2]

◆ dirname()

◆ endsWithSeparator()

◆ isAbsolute()

◆ join()

◆ normalize() [1/2]

◆ normalize() [2/2]

◆ normalizeUNCAndTrimQuotes()

◆ parse()

◆ parseNameExtension()

◆ relativeFromTo()

◆ removeStartingSeparator()

◆ SeparatorStringView()

Member Data Documentation

◆ Separator