Functions
bool	is_file (const std::string path)

bool	is_dir (const std::string path)

bool	is_hidden (const std::string path)

bool	is_absolute (const std::string path)

bool	file_exists (const std::string path)

const std::string	file_vol (const std::string path)

size_t	file_size (const std::string path)

Uint64	file_timestamp (const std::string path)

const std::string	dir_name (const std::string path)

const std::string	base_name (const std::string path)

std::pair< std::string, std::string >	split_path (const std::string path)

std::vector< std::string >	fullsplit_path (const std::string path)

const std::string	base_prefix (const std::string path)

const std::string	base_suffix (const std::string path)

const std::string	set_suffix (const std::string path, const std::string suffix)

std::pair< std::string, std::string >	split_base (const std::string path)

const std::string	normalize_path (const std::string path)

const std::string	canonicalize_path (const std::string path)

const std::string	common_path (const std::initializer_list< std::string > paths)

const std::string	common_path (const std::vector< std::string > paths)

const std::string	common_path (const std::string *paths, size_t size)

const std::string	join_path (std::initializer_list< std::string > elts)

const std::string	join_path (std::vector< std::string > elts)

const std::string	join_path (const std::string *elts, size_t size)

bool	file_create (const std::string path)

bool	file_delete (const std::string path)

std::vector< std::string >	dir_contents (const std::string path)

std::vector< std::string >	dir_contents (const std::string path, const std::function< bool(const std::string file)> &filter)

bool	dir_create (const std::string path)

bool	dir_delete (const std::string path)

bool	is_readable (const std::string path)

bool	is_searchable (const std::string path)

bool	is_writable (const std::string path)

bool	set_readable (const std::string path, bool readable)

bool	set_readable (const std::string path, bool readable, bool ownerOnly)

bool	set_readonly (const std::string path)

bool	set_searchable (const std::string path, bool searchable)

bool	set_searchable (const std::string path, bool searchable, bool ownerOnly)

bool	set_writable (const std::string path, bool writable)

bool	set_writable (const std::string path, bool writable, bool ownerOnly)

size_t	vol_free_space (const std::string path)

size_t	vol_available_space (const std::string path)

size_t	vol_total_space (const std::string path)

Variables
char	path_sep

Detailed Description

Functions for file management.

This namespace provides several tools for querying and constructing file paths in an OS independent way. It is largely a collection of namespaced functions, much like the stringtool module. It is based off the the os.path module in Python.

Function Documentation

◆ base_name()

const std::string cugl::filetool::base_name ( const std::string path )

Returns the name of the leaf file of this path.

This value is the same as the second element returned by the function split_path. If the path names ends in a path separator, this will be ignored when determining the leaf.

Parameters

path	The file path name

Returns: the suffix for the leaf file of this path.

◆ base_prefix()

const std::string cugl::filetool::base_prefix ( const std::string path )

Returns the suffix for the leaf file of this path.

A suffix is any part of the file name after a final period. If there is no suffix, this function returns the empty string.

This value is the same as the second element returned by the function split_base.

Parameters

path	The file path name

Returns: the suffix for the leaf file of this path.

◆ base_suffix()

const std::string cugl::filetool::base_suffix ( const std::string path )

Returns the suffix for the leaf file of this path.

A suffix is any part of the file name after a final period. If there is no suffix, this function returns the empty string.

This value is the same as the second element returned by the function split_base.

Parameters

path	The file path name

Returns: the suffix for the leaf file of this path.

◆ canonicalize_path()

const std::string cugl::filetool::canonicalize_path ( const std::string path )

Returns the given path, canonicalized to the current platform

Canonicalization does everything that normalization does, plus it converts a relative path to its absolute equivalent. It replaces all path separators with the correct system-dependent versions. It also normalizes the path prefix (e.g. capitalizing drive letters on Windows and so on).

In addition, canonicalization removes all redundant directories (e.g. the directories . and ..). However, it does not expand links or shortcuts as is often the case with path canonicalization.

Parameters

path	The path to canonicalize.

Returns: the given path, canonicalized to the current platform

◆ common_path() [1/3]

const std::string cugl::filetool::common_path ( const std::initializer_list< std::string > paths )

Returns the common subpath of the given paths.

If there is no common prefix, or if the paths are a mixture of absolute and relative paths, then this function returns the empty string.

Parameters

paths The collection of paths to search

Returns: the common subpath of the given paths.

◆ common_path() [2/3]

const std::string cugl::filetool::common_path	(	const std::string *	paths,
		size_t	size
	)

Returns the common subpath of the given paths.

If there is no common prefix, or if the paths are a mixture of absolute and relative paths, then this function returns the empty string.

Parameters

paths	The collection of paths to search
size	The number of elements in the arrray

Returns: the common subpath of the given paths.

◆ common_path() [3/3]

const std::string cugl::filetool::common_path ( const std::vector< std::string > paths )

Returns the common subpath of the given paths.

If there is no common prefix, or if the paths are a mixture of absolute and relative paths, then this function returns the empty string.

Parameters

paths The collection of paths to search

Returns: the common subpath of the given paths.

◆ dir_contents() [1/2]

std::vector<std::string> cugl::filetool::dir_contents ( const std::string path )

Returns a list of strings naming the files and directories in this path

This function assumes that this path name denotes a valid directory. If it does not, the list will be empty.

Parameters

path	The file path name

Returns: a list of strings naming the files and directories in this path

◆ dir_contents() [2/2]

std::vector<std::string> cugl::filetool::dir_contents	(	const std::string	path,
		const std::function< bool(const std::string file)> &	filter
	)

Returns a filtered list of strings naming the files and directories in this path

This function assumes that this path name denotes a valid directory. If it does not, the list will be empty.

The filter will be given the normalized version of each file in the directory. If the directory is specified by an absolute path, each file will be as well.

Parameters

path	The file path name
filter	The filter to apply to file names

Returns: a filtered list of strings naming the files and directories in this path

◆ dir_create()

bool cugl::filetool::dir_create ( const std::string path )

Creates the directory named by this path name.

This function succeeds if and only if a file or directory with this name does not yet exist.

This function will fail if the path name is relative. Relative path names refer to the asset directory, which is a read-only directory.

Parameters

path	The file path name

Returns: true if the directory was successfully created.

◆ dir_delete()

bool cugl::filetool::dir_delete ( const std::string path )

Deletes the directory denoted by this path name.

This function will fail if the file is not a directory or if it does not yet exist.

This function will fail if the file is not a regular file or if it does not yet exist. In addition, it will fail if the path name is relative. Relative path names refer to the asset directory, which is a read-only directory.

Parameters

path	The file path name

Returns: true if the directory was successfully deleted.

◆ dir_name()

const std::string cugl::filetool::dir_name ( const std::string path )

Returns the path name of the parent directory for this file.

This value is the same as the first element returned by the function split_path. If path is a relative reference to a file with no parent directory then this function will return the empty string.

Parameters

path	The file path name

Returns: the suffix for the leaf file of this path.

◆ file_create()

bool cugl::filetool::file_create ( const std::string path )

Creates a new, empty file named by this path name

This function succeeds if and only if a file with this name does not yet exist. The file will be an empty, regular file.

This function will fail if the path name is relative. Relative path names refer to the asset directory, which is a read-only directory.

Parameters

path	The file path name

Returns: true if the file was successfully created.

◆ file_delete()

bool cugl::filetool::file_delete ( const std::string path )

Deletes the file denoted by this path name.

This function will fail if the file is not a regular file or if it does not yet exist. In addition, it will fail if the path name is relative. Relative path names refer to the asset directory, which is a read-only directory.

Parameters

path	The file path name

Returns: true if the file was successfully deleted.

◆ file_exists()

bool cugl::filetool::file_exists ( const std::string path )

Returns true if the file or directory denoted by this path name exists.

This function will return false is the file does not exist. If the path is a relative path, this function will use the asset directory as the working directory.

Parameters

path	The file path name

Returns: true if the file or directory denoted by this path name exists.

◆ file_size()

size_t cugl::filetool::file_size ( const std::string path )

Returns the length of the file denoted by this path name.

The value is measured in bytes. This function returns 0 if there is no file at the given path name. If the path is a relative path, this function will use the asset directory as the working directory.

Parameters

path	The file path name

Returns: the length of the file denoted by this path name.

◆ file_timestamp()

Uint64 cugl::filetool::file_timestamp ( const std::string path )

Returns the time that the file for this path name was last modified.

The value is in seconds since the last epoch (e.g. January 1, 1970 on Unix systems). This function returns 0 if there is no file at the given path name. If the path is a relative path, this function will use the asset directory as the working directory.

Parameters

path	The file path name

Returns: the time that the file for this path name was last modified.

◆ file_vol()

const std::string cugl::filetool::file_vol ( const std::string path )

Returns the volume prefix for this path name.

There does not have to be a valid file at the given path name for this function to return a value. If the path name is a relative one, it will return the volume of the asset directory. On some platforms (particularly Android) this may return the empty string.

Parameters

path	The file path name

Returns: the volume prefix for this path.

◆ fullsplit_path()

std::vector<std::string> cugl::filetool::fullsplit_path ( const std::string path )

Returns the path name broken up into individual elements.

The last element of the vector will be be the leaf file of the path name. All other elements (if they exist) will be directories in the path name. If the path name is absolute then the first element of the vector will include the volume.

Parameters

path	The file path name

Returns: the pair of a leaf file and its parent directory.

◆ is_absolute()

bool cugl::filetool::is_absolute ( const std::string path )

Returns true if this path name is absolute.

An absolute path name has an explicit volume and path from the volume. This function does not require that the file exist. It only checks the naming convention of the file referenced by this path.

Returns: true if this path name is absolute.

◆ is_dir()

bool cugl::filetool::is_dir ( const std::string path )

Returns true if the file denoted by this path name is a directory.

This function will return false is the file does not exist. If the path is a relative path, this function will use the asset directory as the working directory.

Parameters

path	The file path name

Returns: true if the file denoted by this path name is a directory.

◆ is_file()

bool cugl::filetool::is_file ( const std::string path )

Returns true if the file denoted by this path name is a normal file.

This function will return false is the file does not exist. If the path is a relative path, this function will use the asset directory as the working directory.

Parameters

path	The file path name

Returns: true if the file denoted by this path name is a normal file.

◆ is_hidden()

bool cugl::filetool::is_hidden ( const std::string path )

Returns true if the file named by this path name is a hidden file (starts with .).

This function does not require that the file exist. It only checks the naming convention of the file referenced by this path.

Parameters

path	The file path name

Returns: true if the file named by this path name is a hidden file.

◆ is_readable()

bool cugl::filetool::is_readable ( const std::string path )

Returns true if the application can read the file for this path name.

This function uses the access() POSIX function. Therefore, it does not assume that this application is the file owner, and correctly determines the file access.

If there is no file at the given path, this function returns false. If path name is relative it is assumes it is in the asset directory.

Parameters

path	The file path name

Returns: true if the application can read the file for this path name.

◆ is_searchable()

bool cugl::filetool::is_searchable ( const std::string path )

Returns true if the application can execute the file for this path name.

Note that the only form of file execution supported by CUGL is searching a directory.

This function uses the access() POSIX function. Therefore, it does not assume that this application is the file owner, and correctly determines the file access.

If there is no file at the given path, this function returns false. If path name is relative it is assumes it is in the asset directory.

Parameters

path	The file path name

Returns: true if the application can execute the file for this path name.

◆ is_writable()

bool cugl::filetool::is_writable ( const std::string path )

Returns true if the application can modify the file for this path name.

This function uses the access() POSIX function. Therefore, it does not assume that this application is the file owner, and correctly determines the file access.

If there is no file at the given path, this function returns false. If path name is relative it is assumes it is in the asset directory.

Parameters

path	The file path name

Returns: true if the application can modify the file for this path name.

◆ join_path() [1/3]

const std::string cugl::filetool::join_path	(	const std::string *	elts,
		size_t	size
	)

Returns a path that is the concatentation of elts.

The path elements will be concatenated using the platform-specific separator. To create an absolute path the first element should include the volume.

The path returned will not be normalized. Call normalize_path if any additional normalization is necessary.

Parameters

elts	The strings to join
size	The number of items in elts.

Returns: a string that is the concatentation of elts.

◆ join_path() [2/3]

const std::string cugl::filetool::join_path ( std::initializer_list< std::string > elts )

Returns a path that is the concatentation of elts.

The path elements will be concatenated using the platform-specific separator. To create an absolute path the first element should include the volume.

The path returned will not be normalized. Call normalize_path if any additional normalization is necessary.

Parameters

elts	The strings to join

Returns: a string that is the concatentation of elts.

◆ join_path() [3/3]

const std::string cugl::filetool::join_path ( std::vector< std::string > elts )

Returns a path that is the concatentation of elts.

The path elements will be concatenated using the platform-specific separator. To create an absolute path the first element should include the volume.

The path returned will not be normalized. Call normalize_path if any additional normalization is necessary.

Parameters

elts	The strings to join

Returns: a string that is the concatentation of elts.

◆ normalize_path()

const std::string cugl::filetool::normalize_path ( const std::string path )

Returns the given path, normalized to the current platform

Normalization replaces all path separators with the correct system- dependent versions. If the path is absolute, it also normalizes the path prefix (e.g. capitalizing drive letters on Windows and so on).

In addition, normalization removes all redundant directories (e.g. the directories . and ..). However, it does not expand links or shortcuts. Furthermore, this function does not convert a relative path into an absolute one. Since the asset directory is not well-defined on all platforms, it is not always possible to perform such a conversion.

In order for normalization to be successful, the path name must be mutliplatform safe. That means no use of colon (:), slash (), or backslash (/) in file names.

Parameters

path	The file path name

Returns: the given path, normalized to the current platform

◆ set_readable() [1/2]

bool cugl::filetool::set_readable	(	const std::string	path,
		bool	readable
	)

Sets the owner's read permission for this path name.

The owner may or may not be this application. The function will return false if the application does not have permission for this change.

If there is no file at the given path, this function returns false. This function will also fail if the path name is relative. Relative path names refer to the asset directory, which is a read-only directory.

Parameters

path	The file path name
readable	Whether the owner may read this file

Returns: true if the file permissions where successfully changed.

◆ set_readable() [2/2]

bool cugl::filetool::set_readable	(	const std::string	path,
		bool	readable,
		bool	ownerOnly
	)

Sets the owner's or everybody's read permission for this path name.

The owner may or may not be this application. The function will return false if the application does not have permission for this change.

If there is no file at the given path, this function returns false. This function will also fail if the path name is relative. Relative path names refer to the asset directory, which is a read-only directory.

Parameters

path	The file path name
readable	Whether this file may be read
ownerOnly	Whether to apply this change only to the owner

Returns: true if the file permissions where successfully changed.

◆ set_readonly()

bool cugl::filetool::set_readonly ( const std::string path )

Marks this file or directory so that only read operations are allowed.

The owner may or may not be this application. The function will return false if the application does not have permission for this change.

If there is no file at the given path, this function returns false. This function will also fail if the path name is relative. Relative path names refer to the asset directory, which is a read-only directory.

Parameters

path	The file path name

Returns: true if the file permissions where successfully changed.

◆ set_searchable() [1/2]

bool cugl::filetool::set_searchable	(	const std::string	path,
		bool	searchable
	)

Sets the owner's execution permission for this path name.

Note that the only form of file execution supported by CUGL is searching a directory.

The owner may or may not be this application. The function will return false if the application does not have permission for this change.

If there is no file at the given path, this function returns false. This function will also fail if the path name is relative. Relative path names refer to the asset directory, which is a read-only directory.

Parameters

path	The file path name
searchable	Whether the owner may execute (search) this file

Returns: true if the file permissions where successfully changed.

◆ set_searchable() [2/2]

bool cugl::filetool::set_searchable	(	const std::string	path,
		bool	searchable,
		bool	ownerOnly
	)

Sets the owner's or everybody's execution permission for this path name.

Note that the only form of file execution supported by CUGL is searching a directory.

The owner may or may not be this application. The function will return false if the application does not have permission for this change.

If there is no file at the given path, this function returns false. This function will also fail if the path name is relative. Relative path names refer to the asset directory, which is a read-only directory.

Parameters

path	The file path name
searchable	Whether this file may be excuted
ownerOnly	Whether to apply this change only to the owner

Returns: true if the file permissions where successfully changed.

◆ set_suffix()

const std::string cugl::filetool::set_suffix	(	const std::string	path,
		const std::string	suffix
	)

Returns a copy of the path name with the given suffix.

A suffix is any part of the file name after a final period. If there is already a suffix in the path name, this function will replace it with the new one.

This function only affects the path name. It does not affect any file associated with the path name.

Parameters

path	The file path name
suffix	The suffix to test

Returns: a copy of the path name with the given suffix.

◆ set_writable() [1/2]

bool cugl::filetool::set_writable	(	const std::string	path,
		bool	writable
	)

Sets the owner's write permission for this path name.

The owner may or may not be this application. The function will return false if the application does not have permission for this change.

If there is no file at the given path, this function returns false. This function will also fail if the path name is relative. Relative path names refer to the asset directory, which is a read-only directory.

Parameters

path	The file path name
writable	Whether the owner may write to this file

Returns: true if the file permissions where successfully changed.

◆ set_writable() [2/2]

bool cugl::filetool::set_writable	(	const std::string	path,
		bool	writable,
		bool	ownerOnly
	)

Sets the owner's or everybody's write permission for this path name.

The owner may or may not be this application. The function will return false if the application does not have permission for this change.

If there is no file at the given path, this function returns false. This function will also fail if the path name is relative. Relative path names refer to the asset directory, which is a read-only directory.

Parameters

path	The file path name
writable	Whether this file may be written to
ownerOnly	Whether to apply this change only to the owner

Returns: true if the file permissions where successfully changed.

◆ split_base()

std::pair<std::string, std::string> cugl::filetool::split_base ( const std::string path )

Returns a pair of the prefix and suffix of the leaf file of the path.

A suffix is any part of the file name after a final period. If the path name contains any directories other than the base file, they are ignored.

Parameters

path	The file path name

Returns: a pair of the prefix and suffix of the leaf file of the path.

◆ split_path()

std::pair<std::string, std::string> cugl::filetool::split_path ( const std::string path )

Returns the pair of a leaf file and its parent directory.

The parent directory will be the first element of the pair. If path is a relative reference to a file with no parent directory then the first element will be the empty string. If the path names ends in a path separator, this will be ignored when determining the leaf.

Parameters

path	The file path name

Returns: the pair of a leaf file and its parent directory.

◆ vol_available_space()

size_t cugl::filetool::vol_available_space ( const std::string path )

Returns the number of available bytes in the partition for this path name.

The value is for the partition containing the given file or directory. If the path name is relative, it assumes that the path name is in the asset directory.

If the path name does not refer to a proper volume, this function will return 0. On some platforms (e.g. Android) the asset directory is not a proper volume and this function will return 0.

This function is similar to vol_free_space except that it measures the number of bytes available for unpriviledged users.

Parameters

path	The file path name

Returns: the number of available bytes in the partition for this path name.

◆ vol_free_space()

size_t cugl::filetool::vol_free_space ( const std::string path )

Returns the number of unallocated bytes in the partition for this path name.

The value is for the partition containing the given file or directory. If the path name is relative, it assumes that the path name is in the asset directory.

If the path name does not refer to a proper volume, this function will return 0. On some platforms (e.g. Android) the asset directory is not a proper volume and this function will return 0.

Parameters

path	The file path name

Returns: the number of unallocated bytes in the partition for this path name.

◆ vol_total_space()

size_t cugl::filetool::vol_total_space ( const std::string path )

Returns the size of the partition named by this path name.

The value is for the partition containing the given file or directory. If the path name is relative, it assumes that the path name is in the asset directory.

If the path name does not refer to a proper volume, this function will return 0. On some platforms (e.g. Android) the asset directory is not a proper volume and this function will return 0.

Parameters

path	The file path name

Returns: the size of the partition named by this path name.

Variable Documentation

◆ path_sep

char cugl::filetool::path_sep

The system-dependent path separator for this platform.

Functions

Variables

Detailed Description

Function Documentation

◆ base_name()

◆ base_prefix()

◆ base_suffix()

◆ canonicalize_path()

◆ common_path() [1/3]

◆ common_path() [2/3]

◆ common_path() [3/3]

◆ dir_contents() [1/2]

◆ dir_contents() [2/2]

◆ dir_create()

◆ dir_delete()

◆ dir_name()

◆ file_create()

◆ file_delete()

◆ file_exists()

◆ file_size()

◆ file_timestamp()

◆ file_vol()

◆ fullsplit_path()

◆ is_absolute()

◆ is_dir()

◆ is_file()

◆ is_hidden()

◆ is_readable()

◆ is_searchable()

◆ is_writable()

◆ join_path() [1/3]

◆ join_path() [2/3]

◆ join_path() [3/3]

◆ normalize_path()

◆ set_readable() [1/2]

◆ set_readable() [2/2]

◆ set_readonly()

◆ set_searchable() [1/2]

◆ set_searchable() [2/2]

◆ set_suffix()

◆ set_writable() [1/2]

◆ set_writable() [2/2]

◆ split_base()

◆ split_path()

◆ vol_available_space()

◆ vol_free_space()

◆ vol_total_space()

Variable Documentation

◆ path_sep