CUGL 2.3
Cornell University Game Library
Loading...
Searching...
No Matches
Functions | Variables
cugl::filetool Namespace Reference

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
pathThe 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
pathThe 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
pathThe 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
pathThe 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
pathsThe 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
pathsThe collection of paths to search
sizeThe 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
pathsThe 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
pathThe 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
pathThe file path name
filterThe 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
pathThe 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
pathThe 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
pathThe 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
pathThe 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
pathThe 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
pathThe 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
pathThe 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
pathThe 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
pathThe 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
pathThe 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
pathThe 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
pathThe 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
pathThe 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
pathThe 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
pathThe 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
pathThe 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
eltsThe strings to join
sizeThe 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
eltsThe 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
eltsThe 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
pathThe 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
pathThe file path name
readableWhether 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
pathThe file path name
readableWhether this file may be read
ownerOnlyWhether 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
pathThe 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
pathThe file path name
searchableWhether 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
pathThe file path name
searchableWhether this file may be excuted
ownerOnlyWhether 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
pathThe file path name
suffixThe 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
pathThe file path name
writableWhether 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
pathThe file path name
writableWhether this file may be written to
ownerOnlyWhether 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
pathThe 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
pathThe 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
pathThe 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
pathThe 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
pathThe file path name
Returns
the size of the partition named by this path name.

Variable Documentation

◆ path_sep

char cugl::filetool::path_sep
extern

The system-dependent path separator for this platform.