Corrade::Utility::Path namespace new in Git master

Filesystem utilities.

This library is built if CORRADE_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.

Classes

class MapDeleter new in Git master
Memory-mapped file deleter.

Enums

enum class ListFlag: unsigned char { SkipDotAndDotDot = 1 << 0, SkipFiles = 1 << 1, SkipDirectories = 1 << 2, SkipSpecial = 1 << 3, SortAscending = (1 << 4) | (1 << 5), SortDescending = 1 << 5 } new in Git master
Directory listing flag.

Typedefs

using ListFlags = Containers::EnumSet<ListFlag> new in Git master
Directory listing flags.

Functions

auto fromNativeSeparators(Containers::String path) -> Containers::String new in Git master
Convert path from native separators.
auto toNativeSeparators(Containers::String path) -> Containers::String new in Git master
Convert path to native separators.
auto split(Containers::StringView path) -> Containers::Pair<Containers::StringView, Containers::StringView> new in Git master
Split path and filename.
auto splitExtension(Containers::StringView path) -> Containers::Pair<Containers::StringView, Containers::StringView> new in Git master
Split basename and extension.
auto join(Containers::StringView path, Containers::StringView filename) -> Containers::String new in Git master
Join path and filename.
auto join(const Containers::StringIterable& paths) -> Containers::String new in Git master
Join paths.
auto exists(Containers::StringView filename) -> bool new in Git master
Check if given file or directory exists.
auto isDirectory(Containers::StringView path) -> bool new in Git master
Check if given path is a directory.
auto make(Containers::StringView path) -> bool new in Git master
Make a path.
auto remove(Containers::StringView path) -> bool new in Git master
Remove a file or a directory.
auto move(Containers::StringView from, Containers::StringView to) -> bool new in Git master
Move given file or directory.
auto libraryLocation(const void* address) -> Containers::Optional<Containers::String> new in Git master
Shared library location containing given address.
template<class R, class ... Args>
auto libraryLocation(R(*)(Args...) address) -> Containers::Optional<Containers::String> new in Git master
auto executableLocation() -> Containers::Optional<Containers::String> new in Git master
Executable location.
auto currentDirectory() -> Containers::Optional<Containers::String> new in Git master
Current directory.
auto homeDirectory() -> Containers::Optional<Containers::String> new in Git master
Current user's home directory.
auto configurationDirectory(Containers::StringView name) -> Containers::Optional<Containers::String> new in Git master
Application configuration directory.
auto temporaryDirectory() -> Containers::Optional<Containers::String> new in Git master
Temporary directory.
auto list(Containers::StringView path, ListFlags flags = {}) -> Containers::Optional<Containers::Array<Containers::String>> new in Git master
List directory contents.
auto size(Containers::StringView filename) -> Containers::Optional<std::size_t> new in Git master
File size.
auto lastModification(Containers::StringView filename) -> Containers::Optional<std::int64_t> new in Git master
File last modification timestamp.
auto read(Containers::StringView filename) -> Containers::Optional<Containers::Array<char>> new in Git master
Read a file into an array.
auto readString(Containers::StringView filename) -> Containers::Optional<Containers::String> new in Git master
Read a file into a string.
auto write(Containers::StringView filename, Containers::ArrayView<const void> data) -> bool new in Git master
Write an array into a file.
auto write(Containers::StringView filename, const char* string) -> bool deleted new in Git master
Writing a C string into a file is not allowed.
auto append(Containers::StringView filename, Containers::ArrayView<const void> data) -> bool new in Git master
Append an array to a file.
auto append(Containers::StringView filename, const char* string) -> bool deleted new in Git master
Appending a C string to a file is not allowed.
auto copy(Containers::StringView from, Containers::StringView to) -> bool new in Git master
Copy a file.
auto map(Containers::StringView filename) -> Containers::Optional<Containers::Array<char, MapDeleter>> new in Git master
Map a file for reading and writing.
auto mapRead(Containers::StringView filename) -> Containers::Optional<Containers::Array<const char, MapDeleter>> new in Git master
Map a file for reading.
auto mapWrite(Containers::StringView filename, std::size_t size) -> Containers::Optional<Containers::Array<char, MapDeleter>> new in Git master
Map a file for writing.

Enum documentation

enum class Corrade::Utility::Path::ListFlag: unsigned char new in Git master
#include <Corrade/Utility/Path.h>

Directory 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 ListFlag::SortAscending and ListFlag::SortDescending is specified, ascending order is used.
SortDescending

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

Typedef documentation

typedef Containers::EnumSet<ListFlag> Corrade::Utility::Path::ListFlags new in Git master
#include <Corrade/Utility/Path.h>

Directory listing flags.

Function documentation

Containers::String Corrade::Utility::Path::fromNativeSeparators(Containers::String path) new in Git master
#include <Corrade/Utility/Path.h>

Convert path from native separators.

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

On Windows the argument and return type is Containers::String and the operation is performed in-place if path is owned, transferring the data ownership to the returned instance. Makes a owned copy first if not. On other platforms it's a Containers::StringView that simply gets passed through.

Containers::String Corrade::Utility::Path::toNativeSeparators(Containers::String path) new in Git master
#include <Corrade/Utility/Path.h>

Convert path to native separators.

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

On Windows the argument and return type is Containers::String and the operation is performed in-place if path is owned, transferring the data ownership to the returned instance. Makes a owned copy first if not. On other platforms it's a Containers::StringView that simply gets passed through.

Containers::Pair<Containers::StringView, Containers::StringView> Corrade::Utility::Path::split(Containers::StringView path) new in Git master
#include <Corrade/Utility/Path.h>

Split path and filename.

Returns a pair of {head, tail} where head is everything before the last slash and tail is everything after. The head will never have a trailing slash except if it's the root (one or two slashes). In all cases, calling join() on the result will give back the original argument. Equivalent to Python os.path.split(). For example:

  • "path/to/file" results in {"path/to", "file"}
  • "file.txt" results in {"", "file.txt"}
  • "/home/user/ results in {"/home/user", ""}
  • "/root" results in {"/", "root"}
  • "//" results in {"//", ""}

The implementation expects forward slashes as directory separators. Use fromNativeSeparators() to convert from a platform-specific format. Containers::StringViewFlags of the input are propagated the same way as with Containers::StringView::slice().

Containers::Pair<Containers::StringView, Containers::StringView> Corrade::Utility::Path::splitExtension(Containers::StringView path) new in Git master
#include <Corrade/Utility/Path.h>

Split basename and extension.

Returns a pair of {root, ext} such that 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. Equivalent to Python os.path.splitext(). For example:

  • "path/to/file.txt" results in {"path/to/file", ".txt"}
  • "file" results in {"file", ""}
  • "/home/.bashrc" results in {"/home/.bashrc", ""}

The implementation expects forward slashes as directory separators. Use fromNativeSeparators() to convert from a platform-specific format. Containers::StringViewFlags of the input are propagated the same way as with Containers::StringView::slice().

Containers::String Corrade::Utility::Path::join(Containers::StringView path, Containers::StringView filename) new in Git master
#include <Corrade/Utility/Path.h>

Join path and filename.

If the path is empty or the filename is absolute (with a leading slash or a drive letter on Windows), returns filename. Otherwise joins them together with a forward slash, unless present in path already. Behavior is equivalent to os.path.split(). For example:

  • {"path/to", "file"} results in "path/to/file"
  • {"path/to/", "file"} results in "path/to/file"
  • {"", "file"} results in "file"
  • {"path", "/absolute/file"} results in "/absolute/file"

The implementation expects forward slashes as directory separators. Use fromNativeSeparators() to convert from a platform-specific format.

Containers::String Corrade::Utility::Path::join(const Containers::StringIterable& paths) new in Git master
#include <Corrade/Utility/Path.h>

Join paths.

Result is equivalent to recursively calling join(Containers::StringView, Containers::StringView) on consecutive pairs of input arguments. When paths is empty, returns an empty string, when it's just a single path, returns it verbatim.

The implementation expects forward slashes as directory separators. Use fromNativeSeparators() to convert from a platform-specific format.

bool Corrade::Utility::Path::exists(Containers::StringView filename) new in Git master
#include <Corrade/Utility/Path.h>

Check if given file or directory exists.

Returns true if the file exists, false otherwise. Inaccessible files may still return true even if reading them will subsequently fail. Checking for an empty filename always fails, checking "." always succeeds, even in case current working directory doesn't exist.

Expects that the filename is in UTF-8. If it's already Containers::StringViewFlag::NullTerminated, it's passed to system APIs directly, otherwise a null-terminated copy is allocated first. On Windows the path is instead first converted to UTF-16 using Unicode::widen() and then passed to system APIs.

Unlike other APIs such as read() or list(), this function doesn't have any failure state nor it produces any error message — and if it returns true, it doesn't necessarily mean the file can be opened or the directory listed, that's only possible to know once such operation is attempted.

bool Corrade::Utility::Path::isDirectory(Containers::StringView path) new in Git master
#include <Corrade/Utility/Path.h>

Check if given path is a directory.

Returns true if the path exists and is a directory, false otherwise. Inaccessible directories may still return true even if listing them will subsequently fail.

Expects that the path is in UTF-8. If it's already Containers::StringViewFlag::NullTerminated, it's passed to system APIs directly, otherwise a null-terminated copy is allocated first. On Windows the path is instead first converted to UTF-16 using Unicode::widen() and then passed to system APIs.

Unlike other APIs such as list(), this function doesn't have any failure state nor it produces any error message — and if it returns true, it doesn't necessarily mean the directory can be listed, that's only possible to know once such operation is attempted.

true for a symlink that points to a directory. This behavior is not implemented on Windows at the moment.

bool Corrade::Utility::Path::make(Containers::StringView path) new in Git master
#include <Corrade/Utility/Path.h>

Make a path.

If any component of path doesn't exist already, can't be created, or exists but is not a directory, prints a message to Error and returns false. Creating an empty path always succeeds.

Expects that the path is in UTF-8. If it's already Containers::StringViewFlag::NullTerminated, it's passed to system APIs directly, otherwise a null-terminated copy is allocated first. On Windows the path is instead first converted to UTF-16 using Unicode::widen() and then passed to system APIs.

bool Corrade::Utility::Path::remove(Containers::StringView path) new in Git master
#include <Corrade/Utility/Path.h>

Remove a file or a directory.

If path doesn't exist, is a non-empty directory or can't be removed for some other reason, prints a message to Error and returns false.

Expects that the path is in UTF-8. If it's already Containers::StringViewFlag::NullTerminated, it's passed to system APIs directly, otherwise a null-terminated copy is allocated first. On Windows the path is instead first converted to UTF-16 using Unicode::widen() and then passed to system APIs.

bool Corrade::Utility::Path::move(Containers::StringView from, Containers::StringView to) new in Git master
#include <Corrade/Utility/Path.h>

Move given file or directory.

If the destination exists, it's overwritten. If from doesn't exist, can't be read, or to can't be written, prints a message to Error and returns false.

Expects that from and to are in UTF-8. If either path is already Containers::StringViewFlag::NullTerminated, it's passed to system APIs directly, otherwise a null-terminated copy is allocated first. On Windows the path is instead first converted to UTF-16 using Unicode::widen() and then passed to system APIs.

Containers::Optional<Containers::String> Corrade::Utility::Path::libraryLocation(const void* address) new in Git master
#include <Corrade/Utility/Path.h>

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 resolvable, prints a message to Error and returns Containers::NullOpt.

Returned value is encoded in UTF-8, on Windows it's first converted from a UTF-16 representation using Unicode::narrow().

#include <Corrade/Utility/Path.h>
template<class R, class ... Args>
Containers::Optional<Containers::String> Corrade::Utility::Path::libraryLocation(R(*)(Args...) address) new in Git master

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

Containers::Optional<Containers::String> Corrade::Utility::Path::executableLocation() new in Git master
#include <Corrade/Utility/Path.h>

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, prints a message to Error and returns Containers::NullOpt.

Returned value is encoded in UTF-8, on Windows it's first converted from a UTF-16 representation using Unicode::narrow().

Containers::Optional<Containers::String> Corrade::Utility::Path::currentDirectory() new in Git master
#include <Corrade/Utility/Path.h>

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 or if the current directory doesn't exist prints a message to Error and returns Containers::NullOpt.

Returned value is encoded in UTF-8, on Windows it's first converted from a UTF-16 representation using Unicode::narrow().

On Unix systems and Emscripten the function is thread-safe. on Windows, the current directory is stored as a global state and thus modifying its value in multithreaded applications may have bad consequences. See the GetCurrentDirectory() documentation for details.

Containers::Optional<Containers::String> Corrade::Utility::Path::homeDirectory() new in Git master
#include <Corrade/Utility/Path.h>

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, prints a message to Error and returns Containers::NullOpt.

Returned value is encoded in UTF-8, on Windows it's first converted from a UTF-16 representation using Unicode::narrow().

Containers::Optional<Containers::String> Corrade::Utility::Path::configurationDirectory(Containers::StringView name) new in Git master
#include <Corrade/Utility/Path.h>

Application configuration directory.

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, prints a message to Error and returns Containers::NullOpt.

Returned value is encoded in UTF-8, on Windows it's first converted from a UTF-16 representation using Unicode::narrow().

Containers::Optional<Containers::String> Corrade::Utility::Path::temporaryDirectory() new in Git master
#include <Corrade/Utility/Path.h>

Temporary directory.

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, prints a message to Error and returns Containers::NullOpt.

Returned value is encoded in UTF-8, on Windows it's first converted from a UTF-16 representation using Unicode::narrow().

Containers::Optional<Containers::Array<Containers::String>> Corrade::Utility::Path::list(Containers::StringView path, ListFlags flags = {}) new in Git master
#include <Corrade/Utility/Path.h>

List directory contents.

If path is not a directory or it can't be opened, prints a message to Error and returns Containers::NullOpt.

Expects that the path is in UTF-8. If it's already Containers::StringViewFlag::NullTerminated, it's passed to system APIs directly, otherwise a null-terminated copy is allocated first. On Windows the path is instead first converted to UTF-16 using Unicode::widen() and then passed to system APIs.

Containers::Optional<std::size_t> Corrade::Utility::Path::size(Containers::StringView filename) new in Git master
#include <Corrade/Utility/Path.h>

File size.

If the file can't be read, is a directory 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. If it's already Containers::StringViewFlag::NullTerminated, it's passed to system APIs directly, otherwise a null-terminated copy is allocated first. On Windows the path is instead first converted to UTF-16 using Unicode::widen() and then passed to system APIs.

Containers::Optional<std::int64_t> Corrade::Utility::Path::lastModification(Containers::StringView filename) new in Git master
#include <Corrade/Utility/Path.h>

File last modification timestamp.

Returns a nanosecond-precision Unix timestamp of the file last modification time. The signed 64-bit integer type covers a span of ±292 years, however while nanoseconds are returned, in reality it's a much coarser granularity — depending on the filesystem, Linux and Android offer roughly tens of milliseconds, macOS and Windows likely just seconds. If the metadata can't be queried, prints a message to Error and returns Containers::NullOpt.

Expects that the filename is in UTF-8. If it's already Containers::StringViewFlag::NullTerminated, it's passed to system APIs directly, otherwise a null-terminated copy is allocated first. On Windows the path is instead first converted to UTF-16 using Unicode::widen() and then passed to system APIs.

Containers::Optional<Containers::Array<char>> Corrade::Utility::Path::read(Containers::StringView filename) new in Git master
#include <Corrade/Utility/Path.h>

Read a file into an array.

Reads the whole file in a binary mode (i.e., without newline conversion). If the file can't be read, prints a message to Error and returns Containers::NullOpt. If the file is empty, returns a zero-sized nullptr array. If the file is non-seekable, it's read in 4 kB chunks and the returned array is growable. For seekable files the returned array has a default deleter but the size may get shortened from what the system reported to what was actually read.

Expects that the filename is in UTF-8. If it's already Containers::StringViewFlag::NullTerminated, it's passed to system APIs directly, otherwise a null-terminated copy is allocated first. On Windows the path is instead first converted to UTF-16 using Unicode::widen() and then passed to system APIs.

Containers::Optional<Containers::String> Corrade::Utility::Path::readString(Containers::StringView filename) new in Git master
#include <Corrade/Utility/Path.h>

Read a file into a string.

Similar to read() but returns a Containers::String, which is guaranteed to be null-terminated.

bool Corrade::Utility::Path::write(Containers::StringView filename, Containers::ArrayView<const void> data) new in Git master
#include <Corrade/Utility/Path.h>

Write an array into a file.

Writes the file as binary (i.e., without newline conversion). Existing files are overwritten, use append() to append instead. Prints a message to Error and returns false if the file can't be written.

Expects that the filename is in UTF-8. If it's already Containers::StringViewFlag::NullTerminated, it's passed to system APIs directly, otherwise a null-terminated copy is allocated first. On Windows the path is instead first converted to UTF-16 using Unicode::widen() and then passed to system APIs.

bool Corrade::Utility::Path::write(Containers::StringView filename, const char* string) deleted new in Git master
#include <Corrade/Utility/Path.h>

Writing a C string into a file is not allowed.

To avoid accidentally writing C strings including the null terminator, please wrap them in a Containers::ArrayView or Containers::StringView first, depending on the intention. You can then directly pass the wrapped array to write(Containers::StringView, Containers::ArrayView<const void>).

bool Corrade::Utility::Path::append(Containers::StringView filename, Containers::ArrayView<const void> data) new in Git master
#include <Corrade/Utility/Path.h>

Append an array to a file.

Appends to the file as binary (i.e., without newline conversion). Prints a message to Error and returns false if the file can't be written.

Expects that the filename is in UTF-8. If it's already Containers::StringViewFlag::NullTerminated, it's passed to system APIs directly, otherwise a null-terminated copy is allocated first. On Windows the path is instead first converted to UTF-16 using Unicode::widen() and then passed to system APIs.

bool Corrade::Utility::Path::append(Containers::StringView filename, const char* string) deleted new in Git master
#include <Corrade/Utility/Path.h>

Appending a C string to a file is not allowed.

To avoid accidentally writing C strings including the null terminator, please wrap them in a Containers::ArrayView or Containers::StringView first, depending on the intention. You can then directly pass the wrapped array to append(Containers::StringView, Containers::ArrayView<const void>).

bool Corrade::Utility::Path::copy(Containers::StringView from, Containers::StringView to) new in Git master
#include <Corrade/Utility/Path.h>

Copy a file.

Zero-allocation file copy with 128 kB block size. Works only on single files, i.e., it can't be used to recursively copy whole directories. If the destination exists, it's overwritten. Prints a message to Error and returns false if from can't be read or to can't be written.

Expects that from and to are in UTF-8. If either path is already Containers::StringViewFlag::NullTerminated, it's passed to system APIs directly, otherwise a null-terminated copy is allocated first. On Windows the path is instead first converted to UTF-16 using Unicode::widen() and then passed to system APIs.

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::Path::write(to, *Utility::Path::mapRead(from));

Containers::Optional<Containers::Array<char, MapDeleter>> Corrade::Utility::Path::map(Containers::StringView filename) new in Git master
#include <Corrade/Utility/Path.h>

Map a file for reading and writing.

Maps the file as a read-write memory. The array deleter takes care of unmapping. If the file doesn't exist or an error occurs while mapping, prints a message to Error and returns Containers::NullOpt. Consistently with read(), if the file is empty it's only opened but not mapped and a zero-sized nullptr array is returned, with the deleter containing the open file handle.

Expects that the filename is in UTF-8. If it's already Containers::StringViewFlag::NullTerminated, it's passed to system APIs directly, otherwise a null-terminated copy is allocated first. On Windows the path is instead first converted to UTF-16 using Unicode::widen() and then passed to system APIs.

Containers::Optional<Containers::Array<const char, MapDeleter>> Corrade::Utility::Path::mapRead(Containers::StringView filename) new in Git master
#include <Corrade/Utility/Path.h>

Map a file for reading.

Maps the file as a read-only memory. The array deleter takes care of unmapping. If the file doesn't exist or an error occurs while mapping, prints a message to Error and returns Containers::NullOpt. Consistently with read(), if the file is empty it's only opened but not mapped and a zero-sized nullptr array is returned, with the deleter containing the open file handle.

Expects that the filename is in UTF-8. If it's already Containers::StringViewFlag::NullTerminated, it's passed to system APIs directly, otherwise a null-terminated copy is allocated first. On Windows the path is instead first converted to UTF-16 using Unicode::widen() and then passed to system APIs.

Containers::Optional<Containers::Array<char, MapDeleter>> Corrade::Utility::Path::mapWrite(Containers::StringView filename, std::size_t size) new in Git master
#include <Corrade/Utility/Path.h>

Map a file for writing.

Maps the file as a 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. If an error occurs while mapping, prints a message to Error and returns Containers::NullOpt. Consistently with map() and mapRead(), if size is 0 the file is only opened but not mapped and a zero-sized nullptr array is returned, with the deleter containing the open file handle.

Expects that the filename is in UTF-8. If it's already Containers::StringViewFlag::NullTerminated, it's passed to system APIs directly, otherwise a null-terminated copy is allocated first. On Windows the path is instead first converted to UTF-16 using Unicode::widen() and then passed to system APIs.