Corrade::Utility::Directory namespace

Filesystem utilities.

Contents

This library is built if WITH_UTILITY is enabled when building Corrade. To use this library with CMake, request the Utility component of the Corrade package and link to the Corrade::Utility target:

find_package(Corrade REQUIRED Utility)

# ...
target_link_libraries(your-app PRIVATE Corrade::Utility)

See also Downloading and building Corrade and Using Corrade with CMake for more information.

Enums

enum class Flag: unsigned char { SkipDotAndDotDot = 1 << 0, SkipFiles = 1 << 1, SkipDirectories = 1 << 2, SkipSpecial = 1 << 3, SortAscending = (1 << 4) | (1 << 5), SortDescending = 1 << 5 }
Listing flag.

Typedefs

using Flags = Containers::EnumSet<Flag>
Listing flags.

Functions

auto fromNativeSeparators(std::string path) -> std::string
Convert path from native separators.
auto toNativeSeparators(std::string path) -> std::string
Convert path to native separators.
auto path(const std::string& filename) -> std::string
Extract path from filename.
auto filename(const std::string& filename) -> std::string
Extract filename (without path) from filename.
auto splitExtension(const std::string& path) -> std::pair<std::string, std::string> new in 2019.10
Split basename and extension.
auto join(const std::string& path, const std::string& filename) -> std::string
Join path and filename.
auto join(std::initializer_list<std::string> paths) -> std::string new in 2019.10
Join paths.
auto list(const std::string& path, Flags flags = Flags()) -> std::vector<std::string>
List directory contents.
auto mkpath(const std::string& path) -> bool
Create path.
auto rm(const std::string& path) -> bool
Remove file or directory.
auto move(const std::string& oldPath, const std::string& newPath) -> bool
Move given file or directory.
auto isSandboxed() -> bool
Whether the application runs in a sandboxed environment.
auto current() -> std::string new in 2019.10
Current directory.
auto libraryLocation(const void* address) -> std::string new in 2019.10
Shared library location containing given address.
template<class R, class ... Args>
auto libraryLocation(R(*)(Args...) address) -> std::string new in 2019.10
auto executableLocation() -> std::string
Executable location.
auto home() -> std::string
Current user's home directory.
auto configurationDir(const std::string& name) -> std::string
Application configuration dir.
auto tmp() -> std::string
Temporary dir.
auto exists(const std::string& filename) -> bool new in 2019.10
Check if the file or directory exists.
auto isDirectory(const std::string& path) -> bool new in 2019.10
Check if given path is a directory.
auto fileExists(const std::string& filename) -> bool deprecated in 2019.10
Check if the file or directory exists.
auto fileSize(const std::string& filename) -> Containers::Optional<std::size_t> new in 2020.06
File size.
auto read(const std::string& filename) -> Containers::Array<char>
Read file into an array.
auto readString(const std::string& filename) -> std::string
Read file into a string.
auto write(const std::string& filename, Containers::ArrayView<const void> data) -> bool
Write array into a file.
auto writeString(const std::string& filename, const std::string& data) -> bool
Write string into a file.
auto append(const std::string& filename, Containers::ArrayView<const void> data) -> bool new in 2019.10
Append array into a file.
auto appendString(const std::string& filename, const std::string& data) -> bool new in 2019.10
Write string into file.
auto copy(const std::string& from, const std::string& to) -> bool new in 2019.10
Copy a file.
auto map(const std::string& filename) -> Containers::Array<char, MapDeleter> new in 2020.06
Map file for reading and writing.
auto mapRead(const std::string& filename) -> Containers::Array<const char, MapDeleter>
Map file for reading.
auto mapWrite(const std::string& filename, std::size_t size) -> Containers::Array<char, MapDeleter> new in 2020.06
Map file for writing.
auto map(const std::string& filename, std::size_t size) -> Containers::Array<char, MapDeleter> deprecated in 2020.06
Map file for writing.

Enum documentation

enum class Corrade::Utility::Directory::Flag: unsigned char

Listing flag.

Enumerators
SkipDotAndDotDot

Skip . and .. directories

SkipFiles

Skip regular files

SkipDirectories

Skip directories (including . and ..)

SkipSpecial

Skip everything that is not a file or directory

SortAscending

Sort items in ascending order. If both Flag::SortAscending and Flag::SortDescending is specified, ascending order is used.

SortDescending

Sort items in descending order. If both Flag::SortAscending and Flag::SortDescending is specified, ascending order is used.

Typedef documentation

typedef Containers::EnumSet<Flag> Corrade::Utility::Directory::Flags

Listing flags.

Function documentation

std::string Corrade::Utility::Directory::fromNativeSeparators(std::string path)

Convert path from native separators.

On Windows converts backward slashes to forward slashes, on all other platforms returns the input argument untouched.

std::string Corrade::Utility::Directory::toNativeSeparators(std::string path)

Convert path to native separators.

On Windows converts forward slashes to backward slashes, on all other platforms returns the input argument untouched.

std::string Corrade::Utility::Directory::path(const std::string& filename)

Extract path from filename.

Returns everything before the last slash. If the filename doesn't contain any path, returns empty string, if the filename is already a path (ends with slash), returns whole string without trailing slash.

std::string Corrade::Utility::Directory::filename(const std::string& filename)

Extract filename (without path) from filename.

If the filename doesn't contain any slash, returns whole string, otherwise returns everything after last slash.

std::pair<std::string, std::string> Corrade::Utility::Directory::splitExtension(const std::string& path) new in 2019.10

Split basename and extension.

Returns a pair (root, ext) where root + ext == path, and ext is empty or begins with a period and contains at most one period. Leading periods on the filename are ignored, splitExtension("/home/.bashrc") returns ("/home/.bashrc", ""). Behavior equivalent to Python's os.path.splitext().

std::string Corrade::Utility::Directory::join(const std::string& path, const std::string& filename)

Join path and filename.

If the path is empty or the filename is absolute (with leading slash), returns filename.

std::string Corrade::Utility::Directory::join(std::initializer_list<std::string> paths) new in 2019.10

Join paths.

Convenience overload to join(const std::string&, const std::string&) when joining the path from more than two parts. When paths is empty, returns empty string, when it's just a single path, returns it verbatim.

std::vector<std::string> Corrade::Utility::Directory::list(const std::string& path, Flags flags = Flags())

List directory contents.

On failure returns empty vector.

bool Corrade::Utility::Directory::mkpath(const std::string& path)

Create path.

Returns true if path was successfully created, false otherwise. Expects that the path is in UTF-8.

bool Corrade::Utility::Directory::rm(const std::string& path)

Remove file or directory.

Returns true if path is file or empty directory and was successfully removed, false otherwise. Expects that the path is in UTF-8.

bool Corrade::Utility::Directory::move(const std::string& oldPath, const std::string& newPath)

Move given file or directory.

Returns true on success, false otherwise. Expects that the paths are in UTF-8.

bool Corrade::Utility::Directory::isSandboxed()

Whether the application runs in a sandboxed environment.

Returns true if running on iOS, Android, as a macOS app bundle, Windows Phone/Store application or in a browser through Emscripten, false otherwise.

std::string Corrade::Utility::Directory::current() new in 2019.10

Current directory.

Returns current working directory on Unix systems (equivalent to the value of shell builtin pwd), non-RT Windows and Emscripten. On other systems prints a warning and returns an empty string. Returned value is encoded in UTF-8.

std::string Corrade::Utility::Directory::libraryLocation(const void* address) new in 2019.10

Shared library location containing given address.

Like executableLocation() but instead of the main executable returns location of a shared library that contains address. If the address is not contained in a shared object, an error is printed to the output and an empty string is returned. Returned value is encoded in UTF-8.

template<class R, class ... Args>
std::string Corrade::Utility::Directory::libraryLocation(R(*)(Args...) address) new in 2019.10

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

std::string Corrade::Utility::Directory::executableLocation()

Executable location.

Returns location of the executable on Linux, Windows, non-sandboxed and sandboxed macOS and iOS. On other systems or if the directory can't be found, a warning is printed and an empty string is returned. Returned value is encoded in UTF-8.

std::string Corrade::Utility::Directory::home()

Current user's home directory.

On Unix and non-sandboxed macOS, the directory is equivalent to ${HOME} environment variable. On sandboxed macOS and iOS the directory is equivalent to what's returned by NSHomeDirectory(). On Windows the directory is equivalent to %USERPROFILE%/Documents or similar. On other systems or if the directory can't be found, empty string is returned. Returned value is encoded in UTF-8.

std::string Corrade::Utility::Directory::configurationDir(const std::string& name)

Application configuration dir.

Parameters
name Application name

On Unix (except for macOS), the configuration dir is ${XDG_CONFIG_HOME}/name or ${HOME}/.config/name (name is lowercased), on Windows the configuration dir is in %APPDATA%/name (name is left as is). On macOS and iOS the configuration dir is ${HOME}/Library/Application Support/name. On other systems or if the directory can't be found, empty string is returned. Returned value is encoded in UTF-8.

std::string Corrade::Utility::Directory::tmp()

Temporary dir.

On Unix and non-sandboxed macOS, the directory is equivalent to /tmp. On sandboxed macOS and iOS the directory is the /tmp subfolder of the app sandbox. On non-RT Windows the directory is equivalent to %TEMP%. On other systems or if the directory can't be found, empty string is returned. Returned value is encoded in UTF-8.

bool Corrade::Utility::Directory::exists(const std::string& filename) new in 2019.10

Check if the file or directory exists.

Returns true if the file exists and is accessible (i.e., user has a permission to open it), false otherwise. Expects that the filename is in UTF-8.

bool Corrade::Utility::Directory::isDirectory(const std::string& path) new in 2019.10

Check if given path is a directory.

Returns true if the path exists, is accessible (i.e., user has a permission to open it) and is a directory, false otherwise. Expects that the filename is in UTF-8.

bool Corrade::Utility::Directory::fileExists(const std::string& filename)

Check if the file or directory exists.

Containers::Optional<std::size_t> Corrade::Utility::Directory::fileSize(const std::string& filename) new in 2020.06

File size.

If the file doesn't exist or is not seekable, prints a message to Error and returns Containers::NullOpt. Note that some special files on Unix platforms may either be non-seekable or report more bytes than they actually have, in which case using read() is a more reliable way to get the size along with the contents.

Expects that the filename is in UTF-8.

Containers::Array<char> Corrade::Utility::Directory::read(const std::string& filename)

Read file into an array.

Reads the whole file in a binary mode (i.e. without newline conversion). Returns nullptr and prints a message to Error if the file can't be read. Supports non-seekable and other weird files as well. Expects that the filename is in UTF-8.

std::string Corrade::Utility::Directory::readString(const std::string& filename)

Read file into a string.

Convenience overload for read().

bool Corrade::Utility::Directory::write(const std::string& filename, Containers::ArrayView<const void> data)

Write array into a file.

Writes the file as binary (i.e. without newline conversion). Existing files are overwritten, use append() to append instead. Returns false and prints a message to Error if the file can't be written, true otherwise. Expects that the filename is in UTF-8.

bool Corrade::Utility::Directory::writeString(const std::string& filename, const std::string& data)

Write string into a file.

Convenience overload for write().

bool Corrade::Utility::Directory::append(const std::string& filename, Containers::ArrayView<const void> data) new in 2019.10

Append array into a file.

Appends to the file as binary (i.e. without newline conversion). Returns false and prints a message to Error if the file can't be written, true otherwise. Expects that the filename is in UTF-8.

bool Corrade::Utility::Directory::appendString(const std::string& filename, const std::string& data) new in 2019.10

Write string into file.

Convenience overload for append().

bool Corrade::Utility::Directory::copy(const std::string& from, const std::string& to) new in 2019.10

Copy a file.

Zero-allocation file copy with 128 kB block size. Does not work on directories. Returns false and prints a message to Error if from can't be read or to can't be written, true otherwise. Expects that the filename is in UTF-8.

Note that the following might be slightly faster on some systems where memory-mapping is supported and virtual memory is large enough for given file size:

Utility::Directory::write(to, Utility::Directory::mapRead(from));

Containers::Array<char, MapDeleter> Corrade::Utility::Directory::map(const std::string& filename) new in 2020.06

Map file for reading and writing.

Maps the file as read-write memory. The array deleter takes care of unmapping. If the file doesn't exist or an error occurs while mapping, nullptr is returned and a message is printed to Error. Expects that the filename is in UTF-8.

Containers::Array<const char, MapDeleter> Corrade::Utility::Directory::mapRead(const std::string& filename)

Map file for reading.

Maps the file as read-only memory. The array deleter takes care of unmapping. If the file doesn't exist or an error occurs while mapping, nullptr is returned and a message is printed to Error. Expects that the filename is in UTF-8.

Containers::Array<char, MapDeleter> Corrade::Utility::Directory::mapWrite(const std::string& filename, std::size_t size) new in 2020.06

Map file for writing.

Maps the file as read-write memory and enlarges it to size. If the file does not exist yet, it is created, if it exists, it's truncated — thus no data is preserved. The array deleter takes care of unmapping, however the file is not deleted after unmapping. If an error occurs, nullptr is returned and a message is printed to Error. Expects that the filename is in UTF-8.

Containers::Array<char, MapDeleter> Corrade::Utility::Directory::map(const std::string& filename, std::size_t size)

Map file for writing.