CUGL 2.3
Cornell University Game Library
|
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 |
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.
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.
path | The file path name |
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
.
path | The file path name |
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
.
path | The file path name |
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.
path | The path to canonicalize. |
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.
paths | The collection of paths to search |
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.
paths | The collection of paths to search |
size | The number of elements in the arrray |
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.
paths | The collection of paths to search |
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.
path | The file path name |
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.
path | The file path name |
filter | The filter to apply to file names |
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.
path | The file path name |
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.
path | The file path 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.
path | The file path name |
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.
path | The file path name |
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.
path | The file path name |
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.
path | The file path name |
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.
path | The file path name |
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.
path | The file path name |
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.
path | The file path name |
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.
path | The file path name |
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.
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.
path | The file path name |
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.
path | The file path name |
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.
path | The file path name |
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.
path | The file path name |
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.
path | The file path name |
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.
path | The file path name |
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.
elts | The strings to join |
size | The number of items in elts. |
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.
elts | The strings to join |
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.
elts | The strings to join |
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.
path | The file path name |
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.
path | The file path name |
readable | Whether the owner may read this file |
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.
path | The file path name |
readable | Whether this file may be read |
ownerOnly | Whether to apply this change only to the owner |
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.
path | The file path name |
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.
path | The file path name |
searchable | Whether the owner may execute (search) this file |
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.
path | The file path name |
searchable | Whether this file may be excuted |
ownerOnly | Whether to apply this change only to the owner |
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.
path | The file path name |
suffix | The suffix to test |
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.
path | The file path name |
writable | Whether the owner may write to this file |
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.
path | The file path name |
writable | Whether this file may be written to |
ownerOnly | Whether to apply this change only to the owner |
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.
path | The file path name |
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.
path | The file path name |
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.
path | The file path name |
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.
path | The file path name |
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.
path | The file path name |
|
extern |
The system-dependent path separator for this platform.