HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Filesystem Namespace Reference

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_API std::string filename (const std::string &filepath) noexcept
 
OIIO_API std::string extension (const std::string &filepath, bool include_dot=true) noexcept
 
OIIO_API std::string parent_path (const std::string &filepath) noexcept
 
OIIO_API std::string replace_extension (const std::string &filepath, const std::string &new_extension) noexcept
 
OIIO_API std::string generic_filepath (string_view filepath) noexcept
 Return the filepath in generic format, not any OS-specific conventions. More...
 
OIIO_API void searchpath_split (const std::string &searchpath, std::vector< std::string > &dirs, bool validonly=false)
 
OIIO_API std::string searchpath_find (const std::string &filename, const std::vector< std::string > &dirs, bool testcwd=true, bool recursive=false)
 
OIIO_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_API bool path_is_absolute (string_view path, bool dot_is_absolute=false)
 
OIIO_API bool exists (string_view path) noexcept
 
OIIO_API bool is_directory (string_view path) noexcept
 
OIIO_API bool is_regular (string_view path) noexcept
 
OIIO_API bool create_directory (string_view path, std::string &err)
 
bool create_directory (string_view path)
 
OIIO_API bool copy (string_view from, string_view to, std::string &err)
 
bool copy (string_view from, string_view to)
 
OIIO_API bool rename (string_view from, string_view to, std::string &err)
 
bool rename (string_view from, string_view to)
 
OIIO_API bool remove (string_view path, std::string &err)
 
bool remove (string_view path)
 
OIIO_API unsigned long long remove_all (string_view path, std::string &err)
 
unsigned long long remove_all (string_view path)
 
OIIO_API std::string temp_directory_path ()
 
OIIO_API std::string unique_path (string_view model="%%%%-%%%%-%%%%-%%%%")
 
OIIO_API FILE * fopen (string_view path, string_view mode)
 
OIIO_API int fseek (FILE *file, int64_t offset, int whence)
 Version of fseek that works with 64 bit offsets on all systems. More...
 
OIIO_API int64_t ftell (FILE *file)
 Version of ftell that works with 64 bit offsets on all systems. More...
 
OIIO_API std::string current_path ()
 
OIIO_API void open (OIIO::ifstream &stream, string_view path, std::ios_base::openmode mode=std::ios_base::in)
 
OIIO_API void open (OIIO::ofstream &stream, string_view path, std::ios_base::openmode mode=std::ios_base::out)
 
OIIO_API int open (string_view path, int flags)
 
OIIO_API bool read_text_file (string_view filename, std::string &str)
 
OIIO_API bool write_text_file (string_view filename, string_view str)
 
OIIO_API size_t read_bytes (string_view path, void *buffer, size_t n, size_t pos=0)
 
OIIO_API std::time_t last_write_time (string_view path) noexcept
 
OIIO_API void last_write_time (string_view path, std::time_t time) noexcept
 
OIIO_API uint64_t file_size (string_view path) noexcept
 
OIIO_API void convert_native_arguments (int argc, const char *argv[])
 
OIIO_API bool enumerate_sequence (string_view desc, std::vector< int > &numbers)
 
OIIO_API bool parse_pattern (const char *pattern, int framepadding_override, std::string &normalized_pattern, std::string &framespec)
 
OIIO_API bool enumerate_file_sequence (const std::string &pattern, const std::vector< int > &numbers, std::vector< std::string > &filenames)
 
OIIO_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_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_API bool scan_for_matching_filenames (const std::string &pattern, std::vector< int > &numbers, std::vector< std::string > &filenames)
 

Detailed Description

Platform-independent utilities for manipulating file names, files, directories, and other file system miscellany.

Function Documentation

OIIO_API void Filesystem::convert_native_arguments ( int  argc,
const char *  argv[] 
)

Ensure command line arguments are UTF-8 everywhere

OIIO_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. Return true upon success, false upon failure and place an error message in err.

Examples:
alligator/alligator.C, karma_procedurals/BRAY_HdSphere.C, packedshareddata/GU_PackedSharedData.C, packedshareddata/GU_PackedSharedData.h, packedsphere/GU_PackedSphere.C, packedsphere/GU_PackedSphere.h, and RAY/RAY_DemoSprite.C.
bool Filesystem::copy ( string_view  from,
string_view  to 
)
inline

Definition at line 155 of file filesystem.h.

OIIO_API bool Filesystem::create_directory ( string_view  path,
std::string err 
)

Create the directory. Return true for success, false for failure and place an error message in err.

bool Filesystem::create_directory ( string_view  path)
inline

Definition at line 146 of file filesystem.h.

OIIO_API std::string Filesystem::current_path ( )

Return the current (".") directory path.

OIIO_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.

Return true upon success, false if the description was too malformed to generate a sequence.

OIIO_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.

Return true upon success, false if the description was too malformed to generate a sequence.

OIIO_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

  • A value (e.g., "3")
  • A value range ("1-10", "10-1", "1-10x3", "1-10y3"): START-FINISH A range, inclusive of start & finish START-FINISHxSTEP A range with step size START-FINISHySTEP The complement of a stepped range, that is, all numbers within the range that would NOT have been selected by 'x'. Note that START may be > FINISH, or STEP may be negative.
  • Multiple values or ranges, separated by a comma (e.g., "3,4,10-20x2") Return true upon success, false if the description was too malformed to generate a sequence.
OIIO_API bool Filesystem::exists ( string_view  path)
noexcept

Return true if the file exists.

OIIO_API std::string Filesystem::extension ( const std::string filepath,
bool  include_dot = true 
)
noexcept

Return the file extension (including the last '.' if include_dot=true) of a filename or filepath.

Examples:
FS/FS_HomeHelper.C, SOP/SOP_BlindData.C, SOP/SOP_BlindData.h, and SOP/SOP_CustomBrush.h.
OIIO_API uint64_t Filesystem::file_size ( string_view  path)
noexcept

Return the size of the file (in bytes), or uint64_t(-1) if there is any error.

OIIO_API std::string Filesystem::filename ( const std::string filepath)
noexcept

Return the filename (excluding any directories, but including the file extension, if any) of a filepath.

OIIO_API FILE* Filesystem::fopen ( string_view  path,
string_view  mode 
)

Version of fopen that can handle UTF-8 paths even on Windows

OIIO_API int Filesystem::fseek ( FILE *  file,
int64_t  offset,
int  whence 
)

Version of fseek that works with 64 bit offsets on all systems.

OIIO_API int64_t Filesystem::ftell ( FILE *  file)

Version of ftell that works with 64 bit offsets on all systems.

OIIO_API std::string Filesystem::generic_filepath ( string_view  filepath)
noexcept

Return the filepath in generic format, not any OS-specific conventions.

OIIO_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), but if recursive is false (the default)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).

OIIO_API bool Filesystem::is_directory ( string_view  path)
noexcept

Return true if the file exists and is a directory.

OIIO_API bool Filesystem::is_regular ( string_view  path)
noexcept

Return true if the file exists and is a regular file.

OIIO_API std::time_t Filesystem::last_write_time ( string_view  path)
noexcept

Get last modified time of file

OIIO_API void Filesystem::last_write_time ( string_view  path,
std::time_t  time 
)
noexcept

Set last modified time on file

OIIO_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_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_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.)

OIIO_API std::string Filesystem::parent_path ( const std::string filepath)
noexcept

Return all but the last part of the path, for example, parent_path("foo/bar") returns "foo", and parent_path("foo") returns "".

OIIO_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_API bool Filesystem::path_is_absolute ( string_view  path,
bool  dot_is_absolute = false 
)

Return true if the path is an "absolute" (not relative) path. If 'dot_is_absolute' is true, consider "./foo" absolute.

OIIO_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_API bool Filesystem::read_text_file ( string_view  filename,
std::string str 
)

Read the entire contents of the named text file and place it in str, returning true on success, false on failure.

OIIO_API bool Filesystem::remove ( string_view  path,
std::string err 
)

Remove the file or directory. Return true for success, false for failure and place an error message in err.

bool Filesystem::remove ( string_view  path)
inline

Definition at line 171 of file filesystem.h.

OIIO_API unsigned long long Filesystem::remove_all ( string_view  path,
std::string err 
)

Remove the file or directory, including any children (recursively). Return the number of files removed. Place an error message (if applicable in err.

unsigned long long Filesystem::remove_all ( string_view  path)
inline

Definition at line 180 of file filesystem.h.

OIIO_API bool Filesystem::rename ( string_view  from,
string_view  to,
std::string err 
)

Rename (or move) a file, directory, or link. Return true upon success, false upon failure and place an error message in err.

bool Filesystem::rename ( string_view  from,
string_view  to 
)
inline

Definition at line 163 of file filesystem.h.

OIIO_API std::string Filesystem::replace_extension ( const std::string filepath,
const std::string new_extension 
)
noexcept

Replace the file extension of a filename or filepath. Does not alter filepath, just returns a new string. Note that the new_extension should contain a leading '.' dot.

OIIO_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.

Return true upon success, false if the directory doesn't exist or the pattern can't be parsed.

OIIO_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.

Return true upon success, false if the directory doesn't exist or the pattern can't be parsed.

OIIO_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.

OIIO_API void Filesystem::searchpath_split ( const std::string searchpath,
std::vector< std::string > &  dirs,
bool  validonly = false 
)

Turn a searchpath (multiple directory paths separated by ':' or ';') into a vector<string> containing 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.

OIIO_API std::string Filesystem::temp_directory_path ( )

Return a directory path where temporary files can be made.

OIIO_API std::string Filesystem::unique_path ( string_view  model = "%%%%-%%%%-%%%%-%%%%")

Return a unique filename suitable for making a temporary file or directory.

OIIO_API bool Filesystem::write_text_file ( string_view  filename,
string_view  str 
)

Write the entire contents of the string str to the file, overwriting any prior contents of the file (if it existed), returning true on success, false on failure.