#include <evo/filepath.h>

Detailed Description

File and directory path helpers.

This has helpers for parsing and joining file path components in various ways
See also: File, Directory, get_cwd(), get_abspath()

Helpers

Static Public Member Functions
static bool	abs (const SubString &path, bool strict=true)
	Check whether path is an absolute path. More...

static SubString	dirpath (const SubString &path)
	Get directory path from path. More...

static SubString	drive (const SubString &path)
	Get Windows drive from path. More...

static SubString	filename (const SubString &path)
	Get filename from path. More...

static SubString	filename_base (const SubString &path)
	Get base filename from path, which is the filename without the extension. More...

static SubString	filename_ext (const SubString &path)
	Get file extension from filename in path. More...

static bool	hasdrive (const SubString &path)
	Check whether given path has a drive component. More...

static String &	join (String &basepath, const SubString &addpath)
	Join two paths together. More...

static String &	join_all (String &out, const SubString &drive, const SubString &dirpath, const SubString &filename)
	Join drive, dirpath, and filename components and write to output string. More...

static String &	join_all (String &out, const SubString &drive, const SubString &dirpath, const SubString &basename, const SubString &ext)
	Join drive, dirpath, and filename components and write to output string. More...

static String &	join_dirpath (String &out, const SubString &dirpath, const SubString &filename)
	Join dirpath and filename and write to output string. More...

static String &	join_drive (String &out, const SubString &drive, const SubString &dirpath)
	Join drive and dirpath and write to output string. More...

static String &	join_filename (String &out, const SubString &basename, const SubString &ext)
	Join file base name and extension components and write to output string. More...

template<class T >
static String &	join_list (String &out, const T &list)
	Join list of path components. More...

static String &	normalize (String &outpath, const SubString &path)
	Normalize path and remove redundant components. More...

static String &	normalize_case (String &outpath, const SubString &path)
	Normalize path case. More...

static void	split_all (SubString &drive, SubString &dirpath, SubString &filename, const SubString &path)
	Split input path into drive, dirpath, and filename components. More...

static void	split_all (SubString &drive, SubString &dirpath, SubString &basename, SubString &ext, const SubString &path)
	Split input path into drive, dirpath, file basename, and file extension components. More...

static SubString	split_dirpath (SubString &outfilename, const SubString &path)
	Get directory path from path. More...

static SubString	split_drive (SubString &outpath, const SubString &path)
	Get Windows drive and remaining path from path. More...

static SubString	split_filename (SubString &ext, const SubString &filename)
	Split filename into base name and extension. More...

template<class T >
static T &	split_list (T &list, const SubString &path)
	Split path into list of components. More...

static bool	validate (const SubString &path, bool strict=true)
	Validate whether path is valid. More...

static bool	validate_filename (const SubString &filename, bool strict=true)
	Validate whether filename is valid. More...

Static Public Attributes
static const char	PATH_DELIM = PATH_DELIM_POSIX
	Path delimiter char for current OS. More...

static const char	PATH_DELIM_POSIX = '/'
	Path delimiter char for Linux/Unix systems. More...

static const char	PATH_DELIM_WIN32 = '\\'
	Path delimiter char for Windows systems. More...

Member Function Documentation

◆ abs()

static bool abs	(	const SubString &	path,
		bool	strict = `true`
	)

inlinestatic

Check whether path is an absolute path.

Linux/Unix: Path is absolute if it begins with a slash
Windows: Path is absolute if it begins with a backslash, or a drive letter followed by a colon then followed by a backslash (backslash optional if strict=false)
- A network (UNC) path beginning with a double-backslash is considered an absolute path
- Note that a drive letter without a backslash (ex: c:foo\bar) is relative to the current dir on that drive so is not absolute, unless strict=false
- This recognizes both slashes and backslashes as path delimiters, though Windows itself only supports backslashes – see normalize_case() to correct

Parameters

path	Path to check
strict	Whether to use strict mode (only used in Windows): false to consider a relative path with a drive as an absolute path (ex: `c:foo`)

Returns: Whether path is absolute

◆ dirpath()

static SubString dirpath ( const SubString & path )

inlinestatic

Get directory path from path.

The directory path is everything up to the the last PATH_DELIM occurrence, or null if no PATH_DELIM found
- The last PATH_DELIM is only included in the result if it's also the first occurence in an absolute path
  - Linux/Unix example: /
  - Windows example: C:\ or \
- Windows: This recognizes both slashes and backslashes as path delimiters, though Windows itself only supports backslashes – see normalize_case() to correct
Similar: split_dirpath()

Parameters

path	Path to extract directory path from

Returns: Directory path from path, null

◆ drive()

static SubString drive ( const SubString & path )

inlinestatic

Get Windows drive from path.

Windows: This gets the drive or network share (if UNC) from path, if specified
- This recognizes both slashes and backslashes as path delimiters, though Windows only supports backslashes – see normalize_case()
- If path contains a drive (drive letter and colon) then the drive letter and colon are included with the result
- If path is a network share (UNC) path then host and share name (everything up to, but not including, the fourth backslash) are all considered the "drive"
  - Network share prefix can be slashes (//) or backslashes (\\), but not a mixture of both
- Examples:
  - For c:\foo the drive is c:
  - For c:foo the drive is c:
  - For \\host\share\foo the drive is \\host\share
  - For \foo or foo the drive is null
Similar: split_drive()

Parameters

path	Path to extract drive from

Returns: Drive or network host (if UNC) from path, null if not specified in path – always null outside of Windows

◆ filename()

static SubString filename ( const SubString & path )

inlinestatic

Get filename from path.

If path ends with a PATH_DELIM (or colon in Windows) then the returned filename will be empty
- Windows: This recognizes both slashes and backslashes as path delimiters, though Windows itself only supports backslashes – see normalize_case() to correct
Similar: split_filename()

Parameters

path	Path to extract filename from

Returns: Filename from path, same as path if no path delimiter found

◆ filename_base()

static SubString filename_base ( const SubString & path )

inlinestatic

Get base filename from path, which is the filename without the extension.

This effectively uses filename() to get the filename from path, then splits on the last '.' to get the base filename
- If the filename starts with a '.' then this is considered part of the base filename (not used to split base/extension)
If path ends with a PATH_DELIM (or colon in Windows) then the filename is empty and the base filename will also be empty
- Windows: This recognizes both slashes and backslashes as path delimiters, though Windows itself only supports backslashes – see normalize_case() to correct
See also: filename_ext()

Parameters

path	Path or filename to extract base filename from

Returns: Base filename from path, null if path is null

◆ filename_ext()

static SubString filename_ext ( const SubString & path )

inlinestatic

Get file extension from filename in path.

This effectively uses filename() to get the filename from path, then splits on the last '.' to get the file extension
If path ends with a PATH_DELIM (or colon in Windows) then the filename is empty and the extension will be null
- Windows: This recognizes both slashes and backslashes as path delimiters, though Windows itself only supports backslashes – see normalize_case() to correct
See also: filename_base()

Parameters

path	Path or filename to extract file extension from

Returns: File extension from path, null if no extension found, empty if filename ends with a '.'

◆ hasdrive()

static bool hasdrive ( const SubString & path )

inlinestatic

Check whether given path has a drive component.

Windows: Path is a drive when it starts with a drive letter followed by a colon, or if a network share (UNC) path that starts with a double-backslash or double slash
Linux/Unix: Always false

Parameters

path	Path to check

Returns: Whether path has a drive

◆ join()

static String& join	(	String &	basepath,
		const SubString &	addpath
	)

inlinestatic

Join two paths together.

This joins paths by appending addpath to path, but if addpath is an absolute path then it places the current path
Windows:
- If addpath has a drive letter then it replaces path, even if not absolute
  - Example: c:foo is relative to current dir on drive C: while c:\foo is an absolute path – either one replaces path
- A network (UNC) path beginning with a double-backslash is considered an absolute path
- A path beginning with a backslash is considered absolute, though it's relative to the current drive

Parameters

basepath	Starting path to join to
addpath	Additional path to join, appended to path if relative, replaces path if absolute (Windows: or if includes driver letter)

Returns: Reference to path

◆ join_all() [1/2]

static String& join_all	(	String &	out,
		const SubString &	drive,
		const SubString &	dirpath,
		const SubString &	filename
	)

inlinestatic

Join drive, dirpath, and filename components and write to output string.

Reverse with: split_all(SubString&,SubString&,SubString&,const SubString&)

Parameters

out	Output string to write to (appended) [in/out]
drive	Drive to join
dirpath	Directory path to join
filename	Filename to join

Returns: Reference to out

◆ join_all() [2/2]

static String& join_all	(	String &	out,
		const SubString &	drive,
		const SubString &	dirpath,
		const SubString &	basename,
		const SubString &	ext
	)

inlinestatic

Join drive, dirpath, and filename components and write to output string.

Reverse with: split_all(SubString&,SubString&,SubString&,SubString&,const SubString&)

Parameters

out	Output string to write to (appended) [in/out]
drive	Drive to join
dirpath	Directory path to join
basename	File base name to join
ext	File extension to join

Returns: Reference to out

◆ join_dirpath()

static String& join_dirpath	(	String &	out,
		const SubString &	dirpath,
		const SubString &	filename
	)

inlinestatic

Join dirpath and filename and write to output string.

Reverse with: split_dirpath()

Parameters

out	Output string to write to (appended) [in/out]
dirpath	Directory path to join
filename	Filename to join

Returns: Reference to out

◆ join_drive()

static String& join_drive	(	String &	out,
		const SubString &	drive,
		const SubString &	dirpath
	)

inlinestatic

Join drive and dirpath and write to output string.

Reverse with: split_drive()

Parameters

out	Output string to write to (appended) [in/out]
drive	Drive to join
dirpath	Directory path to join

Returns: Reference to out

◆ join_filename()

static String& join_filename	(	String &	out,
		const SubString &	basename,
		const SubString &	ext
	)

inlinestatic

Join file base name and extension components and write to output string.

Reverse with: split_filename()

Parameters

out	Output string to write to (appended) [in/out]
basename	File base name to join
ext	File extension to join

Returns: Reference to out

◆ join_list()

static String& join_list	(	String &	out,
		const T &	list
	)

inlinestatic

Join list of path components.

Reverse with: split_list()

Parameters

out	Output string to write to (appended) [in/out]
list	List of path components

Returns: Reference to out

◆ normalize()

static String& normalize	(	String &	outpath,
		const SubString &	path
	)

inlinestatic

Normalize path and remove redundant components.

This reads the input path, normallizes it, and returns an output path
This removes empty components (dup delims) and "." components and resolves ".." components
Normalizing a relative path keeps it from referencing parent directories and is useful for security reasons, though this may not be what you want

Parameters

outpath	Replaced with the resulting output path [out]
path	Input path to normalize – ok if this is the object same as `outpath`

Returns: Reference to outpath

◆ normalize_case()

static String& normalize_case	(	String &	outpath,
		const SubString &	path
	)

inlinestatic

Normalize path case.

Linux/Unix: This copies the input path as-is
Windows: This converts input path ASCII letters to lowercase, and also converts Unix-style slashes to backslashes

Parameters

outpath	Replaced with the resulting output path [out]
path	Input path to normalize case – ok if this is the object same as `outpath`

Returns: Reference to outpath

◆ split_all() [1/2]

static void split_all	(	SubString &	drive,
		SubString &	dirpath,
		SubString &	filename,
		const SubString &	path
	)

inlinestatic

Split input path into drive, dirpath, and filename components.

This calls split_drive() and split_dirpath()

Parameters

drive	Stores drive from input `path`, without the rest of the path
dirpath	Stores directory path from input `path`, without drive or filename
filename	Stores filename from `path`, without directory path
path	Input path to split

◆ split_all() [2/2]

static void split_all	(	SubString &	drive,
		SubString &	dirpath,
		SubString &	basename,
		SubString &	ext,
		const SubString &	path
	)

inlinestatic

Split input path into drive, dirpath, file basename, and file extension components.

This calls split_drive(), split_dirpath(), and split_filename()

Parameters

drive	Stores drive from input `path`, without the rest of the path
dirpath	Stores directory path from input `path`, without drive or filename
basename	Stores file base name from filename in `path`, without file extension or path
ext	Stores file extension from filename in `path`, without base name or path
path	Input path to split

◆ split_dirpath()

static SubString split_dirpath	(	SubString &	outfilename,
		const SubString &	path
	)

inlinestatic

Get directory path from path.

The directory path is everything up to the the last PATH_DELIM occurrence, or null if no PATH_DELIM found
- The last PATH_DELIM is only included in the result if it's also the first occurence in an absolute path
  - Linux/Unix example: /
  - Windows example: C:\ or \
- Windows: This recognizes both slashes and backslashes as path delimiters, though Windows itself only supports backslashes – see normalize_case() to correct
Reverse with: join_dirpath()
See also: dirpath()

Parameters

outfilename	Stores filename from path, empty if no filename, null if path is null
path	Path to extract directory path from

Returns: Directory path from path, null if path is null

◆ split_drive()

static SubString split_drive	(	SubString &	outpath,
		const SubString &	path
	)

inlinestatic

Get Windows drive and remaining path from path.

This works the same as drive(const SubString&) but also sets the remaining path in outpath
In all cases, concatenating drive and outpath will be the same as the input path
Reverse with: join_drive()
See also: drive()

Parameters

outpath	Stores remaining path after drive – always same as `path` if not Windows [out]
path	Path to extract drive

Returns: Drive or network host (if UNC) from path, null if not specified in path – always null if not Windows

◆ split_filename()

static SubString split_filename	(	SubString &	ext,
		const SubString &	filename
	)

inlinestatic

Split filename into base name and extension.

This assumes input filename is not a path, call filename() to get filename from path
This is more efficient than calling filename_base() and filename_ext() separately
If the filename starts with a '.' then this is considered part of the base name
Reverse with: join_filename()
See also: filename()

Parameters

ext	Stores file extension, set to null if no extension [out]
filename	Input filename to split

Returns: Base name, null if path is null

◆ split_list()

static T& split_list	(	T &	list,
		const SubString &	path
	)

inlinestatic

Split path into list of components.

For an absolute path, the first component will be a path delimiter – use abs() to check this
Windows: The first component will also include the drive or network share, if applicable, along with the path delimiter if an absolute path
- Note that this is different from split_drive(), which does not combine the drive and path delim for absolute paths
- Use hasdrive() to check if first component has a drive or network share
- Use abs() with strict=false to check if it's an absolute path
Reverse with: join_list()

Parameters

list	Stores path components (cleared first), set to null if path is null
path	Path to split

Returns: Reference to list

◆ validate()

static bool validate	(	const SubString &	path,
		bool	strict = `true`
	)

inlinestatic

Validate whether path is valid.

Path is invalid if it contains any invalid characters
Non-ASCII UTF-8 characters are considered valid
Linux/Unix:
- Paths containing an ASCII null character are invalid
- Strict mode also considers unprintable characters invalid (ASCII codes before space char)
Windows:
- Unprintable characters are invalid (ASCII codes before space char), as well as reserved characters: <>:"/|?*
- Colon : is valid after the drive letter (for absolute path), but otherwise invalid
- A directory or file name ending with a space or period is considered invalid, unless it's "." or ".."
- Strict mode also considers special reserved filenames as invalid (with or without an extension):
  - CON, PRN, AUX, NUL
  - COM1, COM2, COM3, COM4, COM5, COM6, COM7, COM8, COM9
  - LPT1, LPT2, LPT3, LPT4, LPT5, LPT6, LPT7, LPT8, LPT9
- You may want to normalize_case() first to fix some things that would fail validation

Parameters

path	Path to validate
strict	Whether to enable additional checks for strict mode

Returns: Whether path is valid

◆ validate_filename()

static bool validate_filename	(	const SubString &	filename,
		bool	strict = `true`
	)

inlinestatic

Validate whether filename is valid.

Filename is invalid if it contains any invalid characters
Non-ASCII UTF-8 characters are considered valid
This is different from a file path – path delimiters are not valid in a filename
Linux/Unix:
- Filenames containing an ASCII null character or slash are invalid
- Strict mode also considers unprintable characters invalid (ASCII codes before space char)
Windows:
- Unprintable characters are invalid (ASCII codes before space char), as well as reserved characters: <>:"/|?*
- A drive letter with a colon is not a valid filename
- A filename ending with a space or period is considered invalid, unless it's "." or ".."
- Strict mode also considers special reserved filenames as invalid (with or without an extension):
  - CON, PRN, AUX, NUL
  - COM1, COM2, COM3, COM4, COM5, COM6, COM7, COM8, COM9
  - LPT1, LPT2, LPT3, LPT4, LPT5, LPT6, LPT7, LPT8, LPT9
- You may want to normalize_case() first to fix some things that would fail validation

Parameters

filename	Filename to validate
strict	Whether to enable additional checks for strict mode

Returns: Whether filename is valid

Member Data Documentation

◆ PATH_DELIM

const char PATH_DELIM = PATH_DELIM_POSIX

static

Path delimiter char for current OS.

◆ PATH_DELIM_POSIX

const char PATH_DELIM_POSIX = '/'

static

Path delimiter char for Linux/Unix systems.

◆ PATH_DELIM_WIN32

const char PATH_DELIM_WIN32 = '\\'

static

Path delimiter char for Windows systems.

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

evo/filepath.h

Detailed Description

Static Public Member Functions

Static Public Attributes

Member Function Documentation

◆ abs()

◆ dirpath()

◆ drive()

◆ filename()

◆ filename_base()

◆ filename_ext()

◆ hasdrive()

◆ join()

◆ join_all() [1/2]

◆ join_all() [2/2]

◆ join_dirpath()

◆ join_drive()

◆ join_filename()

◆ join_list()

◆ normalize()

◆ normalize_case()

◆ split_all() [1/2]

◆ split_all() [2/2]

◆ split_dirpath()

◆ split_drive()

◆ split_filename()

◆ split_list()

◆ validate()

◆ validate_filename()

Member Data Documentation

◆ PATH_DELIM

◆ PATH_DELIM_POSIX

◆ PATH_DELIM_WIN32