HDK
|
Platform-independent utilities for manipulating file names, files, directories, and other file system miscellany. More...
Classes | |
class | IOProxy |
class | IOFile |
class | IOVecOutput |
class | IOMemReader |
IOProxy subclass for reading that wraps an cspan<char>. More... | |
Functions | |
OIIO_UTIL_API std::string | filename (string_view filepath) noexcept |
OIIO_UTIL_API std::string | extension (string_view filepath, bool include_dot=true) noexcept |
OIIO_UTIL_API std::string | parent_path (string_view filepath) noexcept |
OIIO_UTIL_API std::string | replace_extension (const std::string &filepath, const std::string &new_extension) noexcept |
OIIO_UTIL_API std::string | generic_filepath (string_view filepath) noexcept |
OIIO_UTIL_API std::vector < std::string > | searchpath_split (string_view searchpath, bool validonly=false) |
void | searchpath_split (string_view searchpath, std::vector< std::string > &dirs, bool validonly=false) |
OIIO_UTIL_API std::string | searchpath_find (const std::string &filename, const std::vector< std::string > &dirs, bool testcwd=true, bool recursive=false) |
OIIO_UTIL_API std::string | find_program (string_view program) |
OIIO_UTIL_API bool | get_directory_entries (const std::string &dirname, std::vector< std::string > &filenames, bool recursive=false, const std::string &filter_regex=std::string()) |
OIIO_UTIL_API bool | path_is_absolute (string_view path, bool dot_is_absolute=false) |
OIIO_UTIL_API bool | exists (string_view path) noexcept |
OIIO_UTIL_API bool | is_directory (string_view path) noexcept |
OIIO_UTIL_API bool | is_regular (string_view path) noexcept |
OIIO_UTIL_API bool | is_executable (string_view path) noexcept |
OIIO_UTIL_API bool | create_directory (string_view path, std::string &err) |
bool | create_directory (string_view path) |
OIIO_UTIL_API bool | copy (string_view from, string_view to, std::string &err) |
bool | copy (string_view from, string_view to) |
OIIO_UTIL_API bool | rename (string_view from, string_view to, std::string &err) |
bool | rename (string_view from, string_view to) |
OIIO_UTIL_API bool | remove (string_view path, std::string &err) |
bool | remove (string_view path) |
OIIO_UTIL_API unsigned long long | remove_all (string_view path, std::string &err) |
unsigned long long | remove_all (string_view path) |
OIIO_UTIL_API std::string | temp_directory_path () |
OIIO_UTIL_API std::string | unique_path (string_view model="%%%%-%%%%-%%%%-%%%%") |
OIIO_UTIL_API FILE * | fopen (string_view path, string_view mode) |
Version of fopen that can handle UTF-8 paths even on Windows. More... | |
OIIO_UTIL_API int | fseek (FILE *file, int64_t offset, int whence) |
OIIO_UTIL_API int64_t | ftell (FILE *file) |
Version of ftell that works with 64 bit offsets on all systems. More... | |
OIIO_UTIL_API std::string | current_path () |
OIIO_UTIL_API void | open (OIIO::ifstream &stream, string_view path, std::ios_base::openmode mode=std::ios_base::in) |
OIIO_UTIL_API void | open (OIIO::ofstream &stream, string_view path, std::ios_base::openmode mode=std::ios_base::out) |
OIIO_UTIL_API int | open (string_view path, int flags) |
OIIO_UTIL_API bool | read_text_file (string_view filename, std::string &str, size_t size=(1UL<< 24)) |
OIIO_UTIL_API bool | read_text_from_command (string_view command, std::string &str, size_t size=(1UL<< 24)) |
OIIO_UTIL_API bool | write_text_file (string_view filename, string_view str) |
template<typename T > | |
bool | write_binary_file (string_view filename, cspan< T > data) |
template<typename T > | |
bool | write_binary_file (string_view filename, const std::vector< T > &data) |
OIIO_UTIL_API size_t | read_bytes (string_view path, void *buffer, size_t n, size_t pos=0) |
OIIO_UTIL_API std::time_t | last_write_time (string_view path) noexcept |
OIIO_UTIL_API void | last_write_time (string_view path, std::time_t time) noexcept |
OIIO_UTIL_API uint64_t | file_size (string_view path) noexcept |
OIIO_UTIL_API void | convert_native_arguments (int argc, const char *argv[]) |
Ensure command line arguments are UTF-8 everywhere. More... | |
OIIO_UTIL_API bool | enumerate_sequence (string_view desc, std::vector< int > &numbers) |
OIIO_UTIL_API bool | parse_pattern (const char *pattern, int framepadding_override, std::string &normalized_pattern, std::string &framespec) |
OIIO_UTIL_API bool | enumerate_file_sequence (const std::string &pattern, const std::vector< int > &numbers, std::vector< std::string > &filenames) |
OIIO_UTIL_API bool | enumerate_file_sequence (const std::string &pattern, const std::vector< int > &numbers, const std::vector< string_view > &views, std::vector< std::string > &filenames) |
OIIO_UTIL_API bool | scan_for_matching_filenames (const std::string &pattern, const std::vector< string_view > &views, std::vector< int > &frame_numbers, std::vector< string_view > &frame_views, std::vector< std::string > &filenames) |
OIIO_UTIL_API bool | scan_for_matching_filenames (const std::string &pattern, std::vector< int > &numbers, std::vector< std::string > &filenames) |
OIIO_UTIL_API std::string | filename_to_regex (string_view pattern, bool simple_glob=true) |
Platform-independent utilities for manipulating file names, files, directories, and other file system miscellany.
OIIO_UTIL_API void Filesystem::convert_native_arguments | ( | int | argc, |
const char * | argv[] | ||
) |
Ensure command line arguments are UTF-8 everywhere.
OIIO_UTIL_API bool Filesystem::copy | ( | string_view | from, |
string_view | to, | ||
std::string & | err | ||
) |
Copy a file, directory, or link. It is an error if 'to' already exists. The file names are all UTF-8 encoded. Return true upon success, false upon failure and place an error message in err.
|
inline |
Definition at line 172 of file filesystem.h.
OIIO_UTIL_API bool Filesystem::create_directory | ( | string_view | path, |
std::string & | err | ||
) |
Create the directory, whose name is UTF-8 encoded. Return true for success, false for failure and place an error message in err.
|
inline |
Definition at line 163 of file filesystem.h.
OIIO_UTIL_API std::string Filesystem::current_path | ( | ) |
Return the current (".") directory path.
OIIO_UTIL_API bool Filesystem::enumerate_file_sequence | ( | const std::string & | pattern, |
const std::vector< int > & | numbers, | ||
std::vector< std::string > & | filenames | ||
) |
Given a normalized pattern (such as "foo.%04d.tif") and a list of frame numbers, generate a list of filenames. All the filename strings will be presumed to be UTF-8 encoded.
Return true upon success, false if the description was too malformed to generate a sequence.
OIIO_UTIL_API bool Filesystem::enumerate_file_sequence | ( | const std::string & | pattern, |
const std::vector< int > & | numbers, | ||
const std::vector< string_view > & | views, | ||
std::vector< std::string > & | filenames | ||
) |
Given a normalized pattern (such as "foo_%V.%04d.tif") and a list of frame numbers, generate a list of filenames. "views" is list of per-frame views, or empty. In each frame filename, "%V" is replaced with the view, and "%v" is replaced with the first character of the view. All the filename strings will be presumed to be UTF-8 encoded.
Return true upon success, false if the description was too malformed to generate a sequence.
OIIO_UTIL_API bool Filesystem::enumerate_sequence | ( | string_view | desc, |
std::vector< int > & | numbers | ||
) |
Turn a sequence description string into a vector of integers. The sequence description can be any of the following
|
noexcept |
Return true if the UTF-8 encoded path exists.
|
noexcept |
Return the file extension (including the last '.' if include_dot=true) of a UTF-8 encoded filename or filepath.
|
noexcept |
Return the size of the file (in bytes), or uint64_t(-1) if there is any error. The file name is UTF-8 encoded.
|
noexcept |
Return the filename (excluding any directories, but including the file extension, if any) of a UTF-8 encoded filepath.
OIIO_UTIL_API std::string Filesystem::filename_to_regex | ( | string_view | pattern, |
bool | simple_glob = true |
||
) |
Convert a UTF-8 encoded filename into a regex-safe pattern – any special regex characters .
, (
, )
, [
, ]
, {
, }
are backslashed. If simple_glob
is also true, then replace ?
with .?
and *
with .*
. This doesn't support full Unix command line glob syntax (no char sets [abc]
or string sets {ab,cd,ef}
), but it does handle simple globbing of ?
to mean any single character and *
to mean any sequence of 0 or more characters.
OIIO_UTIL_API std::string Filesystem::find_program | ( | string_view | program | ) |
Find the given program in the $PATH
searchpath and return its full path. If the program is not found, return an empty string.
OIIO_UTIL_API FILE* Filesystem::fopen | ( | string_view | path, |
string_view | mode | ||
) |
Version of fopen that can handle UTF-8 paths even on Windows.
OIIO_UTIL_API int Filesystem::fseek | ( | FILE * | file, |
int64_t | offset, | ||
int | whence | ||
) |
Version of fseek that works with 64 bit offsets on all systems. Like std::fseek, returns zero on success, nonzero on failure.
OIIO_UTIL_API int64_t Filesystem::ftell | ( | FILE * | file | ) |
Version of ftell that works with 64 bit offsets on all systems.
|
noexcept |
Return the filepath in generic format, not any OS-specific conventions. Input and output are both UTF-8 encoded.
OIIO_UTIL_API bool Filesystem::get_directory_entries | ( | const std::string & | dirname, |
std::vector< std::string > & | filenames, | ||
bool | recursive = false , |
||
const std::string & | filter_regex = std::string() |
||
) |
Fill a vector-of-strings with the names of all files contained by directory dirname. If recursive is true, it will return all files below the directory (even in subdirectories). If filter_regex is supplied and non-empty, only filenames matching the regular expression will be returned. Return true if ok, false if there was an error (such as dirname not being found or not actually being a directory). All file and directory names are presumed to be UTF-8 encoded.
|
noexcept |
Return true if the UTF-8 encoded path exists and is a directory.
|
noexcept |
Return true if the UTF-8 encoded path is an executable file (by any of user, group, or owner).
|
noexcept |
Return true if the UTF-8 encoded path exists and is a regular file.
|
noexcept |
Get last modified time of the file named by path
(UTF-8 encoded).
|
noexcept |
Set last modified time on the file named by path
(UTF-8 encoded).
OIIO_UTIL_API void Filesystem::open | ( | OIIO::ifstream & | stream, |
string_view | path, | ||
std::ios_base::openmode | mode = std::ios_base::in |
||
) |
Version of std::ifstream.open that can handle UTF-8 paths
OIIO_UTIL_API void Filesystem::open | ( | OIIO::ofstream & | stream, |
string_view | path, | ||
std::ios_base::openmode | mode = std::ios_base::out |
||
) |
Version of std::ofstream.open that can handle UTF-8 paths
OIIO_UTIL_API int Filesystem::open | ( | string_view | path, |
int | flags | ||
) |
Version of C open() that can handle UTF-8 paths, returning an integer file descriptor. Note that the flags are passed to underlying calls to open()/_open() and therefore may be OS specific – use with caution! If you want more OS-agnostic file opening, prefer the FILE or stream methods of IO. (N.B.: use of this function requires the caller to #include <fcntl.h>
in order to get the definitions of the flags.)
|
noexcept |
Return all but the last part of the UTF-8 encoded path, for example, parent_path("foo/bar") returns "foo", and parent_path("foo") returns "".
OIIO_UTIL_API bool Filesystem::parse_pattern | ( | const char * | pattern, |
int | framepadding_override, | ||
std::string & | normalized_pattern, | ||
std::string & | framespec | ||
) |
Given a pattern (such as "foo.#.tif" or "bar.1-10#.exr"), return a normalized pattern in printf format (such as "foo.%04d.tif") and a framespec (such as "1-10").
If framepadding_override is > 0, it overrides any specific padding amount in the original pattern.
Return true upon success, false if the description was too malformed to generate a sequence.
OIIO_UTIL_API bool Filesystem::path_is_absolute | ( | string_view | path, |
bool | dot_is_absolute = false |
||
) |
Return true if the UTF-8 encoded path is an "absolute" (not relative) path. If 'dot_is_absolute' is true, consider "./foo" absolute.
OIIO_UTIL_API size_t Filesystem::read_bytes | ( | string_view | path, |
void * | buffer, | ||
size_t | n, | ||
size_t | pos = 0 |
||
) |
Read a maximum of n bytes from the named file, starting at position pos (which defaults to the start of the file), storing results in buffer[0..n-1]. Return the number of bytes read, which will be n for full success, less than n if the file was fewer than n+pos bytes long, or 0 if the file did not exist or could not be read.
OIIO_UTIL_API bool Filesystem::read_text_file | ( | string_view | filename, |
std::string & | str, | ||
size_t | size = (1UL<< 24) |
||
) |
Read the entire contents of the named text file (as a UTF-8 encoded filename) and place it in str, returning true on success, false on failure. The optional size parameter gives the maximum amount to read (for memory safety) and defaults to 16MB. Set size to 0 for no limit (use at your own risk).
OIIO_UTIL_API bool Filesystem::read_text_from_command | ( | string_view | command, |
std::string & | str, | ||
size_t | size = (1UL<< 24) |
||
) |
Run a command line process and capture its console output in str
, returning true on success, false on failure. The optional size parameter gives the maximum amount to read (for memory safety) and defaults to 16MB. Set size to 0 for no limit (use at your own risk).
OIIO_UTIL_API bool Filesystem::remove | ( | string_view | path, |
std::string & | err | ||
) |
Remove the file or directory. The file names are all UTF-8 encoded. Return true for success, false for failure and place an error message in err.
|
inline |
Definition at line 189 of file filesystem.h.
OIIO_UTIL_API unsigned long long Filesystem::remove_all | ( | string_view | path, |
std::string & | err | ||
) |
Remove the file or directory, including any children (recursively). The file names are all UTF-8 encoded. Return the number of files removed. Place an error message (if applicable in err.
|
inline |
Definition at line 198 of file filesystem.h.
OIIO_UTIL_API bool Filesystem::rename | ( | string_view | from, |
string_view | to, | ||
std::string & | err | ||
) |
Rename (or move) a file, directory, or link. The file names are all UTF-8 encoded. Return true upon success, false upon failure and place an error message in err.
|
inline |
Definition at line 181 of file filesystem.h.
|
noexcept |
Replace the file extension of a UTF-8 encoded filename or filepath. Does not alter filepath, just returns a new string. Note that the new_extension should contain a leading '.' dot.
OIIO_UTIL_API bool Filesystem::scan_for_matching_filenames | ( | const std::string & | pattern, |
const std::vector< string_view > & | views, | ||
std::vector< int > & | frame_numbers, | ||
std::vector< string_view > & | frame_views, | ||
std::vector< std::string > & | filenames | ||
) |
Given a normalized pattern (such as "/path/to/foo.%04d.tif") scan the containing directory (/path/to) for matching frame numbers, views and files. "%V" in the pattern matches views, while "%v" matches the first character of each entry in views. All the filename strings will be presumed to be UTF-8 encoded.
Return true upon success, false if the directory doesn't exist or the pattern can't be parsed.
OIIO_UTIL_API bool Filesystem::scan_for_matching_filenames | ( | const std::string & | pattern, |
std::vector< int > & | numbers, | ||
std::vector< std::string > & | filenames | ||
) |
Given a normalized pattern (such as "/path/to/foo.%04d.tif") scan the containing directory (/path/to) for matching frame numbers and files. All the filename strings will be presumed to be UTF-8 encoded.
Return true upon success, false if the directory doesn't exist or the pattern can't be parsed.
OIIO_UTIL_API std::string Filesystem::searchpath_find | ( | const std::string & | filename, |
const std::vector< std::string > & | dirs, | ||
bool | testcwd = true , |
||
bool | recursive = false |
||
) |
Find the first instance of a filename existing in a vector of directories, returning the full path as a string. If the file is not found in any of the listed directories, return an empty string. If the filename is absolute, the directory list will not be used. If testcwd is true, "." will be tested before the searchpath; otherwise, "." will only be tested if it's explicitly in dirs. If recursive is true, the directories will be searched recursively, finding a matching file in any subdirectory of the directories listed in dirs; otherwise. All file and directory names are presumed to be UTF-8 encoded.
OIIO_UTIL_API std::vector<std::string> Filesystem::searchpath_split | ( | string_view | searchpath, |
bool | validonly = false |
||
) |
Turn a searchpath (multiple UTF-8 encoded directory paths separated by ':' or ';') into a vector<string> containing the name of each individual directory. If validonly is true, only existing and readable directories will end up in the list. N.B., the directory names will not have trailing slashes.
|
inline |
Definition at line 100 of file filesystem.h.
OIIO_UTIL_API std::string Filesystem::temp_directory_path | ( | ) |
Return a directory path (UTF-8 encoded) where temporary files can be made.
OIIO_UTIL_API std::string Filesystem::unique_path | ( | string_view | model = "%%%%-%%%%-%%%%-%%%%" | ) |
Return a unique filename suitable for making a temporary file or directory. The file names are all UTF-8 encoded. NOTE: this function is not recommended, because it's a known security and stability issue, since another process could create a file of the same name after the path is retrieved but before it is created. So in the long run, we want to wean ourselves off this. But in practice, it's not an emergency. We'll replace this with something else eventually.
bool Filesystem::write_binary_file | ( | string_view | filename, |
cspan< T > | data | ||
) |
Write the entire contents of the span data
to the file (UTF-8 encoded) as a binary blob, overwriting any prior contents of the file (if it existed), returning true on success, false on failure.
Definition at line 273 of file filesystem.h.
bool Filesystem::write_binary_file | ( | string_view | filename, |
const std::vector< T > & | data | ||
) |
Definition at line 282 of file filesystem.h.
OIIO_UTIL_API bool Filesystem::write_text_file | ( | string_view | filename, |
string_view | str | ||
) |
Write the entire contents of the string str
to the named file (UTF-8 encoded), overwriting any prior contents of the file (if it existed), returning true on success, false on failure.