This is a snapshot of a work-in-progress documentation theme. If you feel lost, miss something, or want to see the original Doxygen docs instead, head over to the archived version of this documentation page.

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, you need to 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 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 join(const std::string& path, const std::string& filename) -> std::string
Join path and filename.
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 fileExists(const std::string& filename) -> bool
Check if the file exists.
auto isSandboxed() -> bool
Whether the application runs in a sandboxed environment.
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 list(const std::string& path, Flags flags = Flags()) -> std::vector<std::string>
List directory contents.
auto read(const std::string& filename) -> Containers::Array<char>
Read file into array.
auto readString(const std::string& filename) -> std::string
Read file into string.
auto write(const std::string& filename, Containers::ArrayView<const void> data) -> bool
Write array into file.
auto writeString(const std::string& filename, const std::string& data) -> bool
Write string into file.
auto map(const std::string& filename, std::size_t size) -> Containers::Array<char, MapDeleter>
Map file for reading and writing.
auto mapRead(const std::string& filename) -> Containers::Array<const char, MapDeleter>
Map file for reading.

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 what 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 first 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::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.

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::fileExists(const std::string& filename)

Check if the file exists.

Returns true if the file exists and is accessible (e.g. user has permission to open it), false otherwise. Expects that the filename is 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::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, 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.

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

List directory contents.

On failure returns empty vector.

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

Read file into array.

Reads whole file as binary (i.e. without newline conversion). Returns nullptr and prints message to Error if the file can't be read. Expects that the filename is in UTF-8.

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

Read file into string.

Convenience overload for read().

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

Write array into file.

Writes the file as binary (i.e. without newline conversion). Returns false and prints 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 file.

Convenience overload for write().

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

Map file for reading and 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. 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<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.