Death::IO::FileSystem class
#include <IO/FileSystem.h>

File system related methods.

Public types

class Directory
Handles directory traversal, should be used as iterator.
class MapDeleter
Memory-mapped file deleter.
enum class Permission { None = 0, Read = 0x01, Write = 0x02, Execute = 0x04 }
Available permissions to check or set, supports a bitwise combination of its member values.
enum class EnumerationOptions { None = 0, SkipFiles = 0x01, SkipDirectories = 0x02, SkipSpecial = 0x04 }
Options that modify behavior of Directory, supports a bitwise combination of its member values.

Public static functions

static auto FindPathCaseInsensitive(Containers::StringView path) -> Containers::StringView
Returns path with correct case on case-sensitive platforms (or {} if path not found).
static auto FindPathCaseInsensitive(Containers::String&& path) -> Containers::String
static auto CombinePath(Containers::StringView first, Containers::StringView second) -> Containers::String
Combines together specified path components.
static auto CombinePath(Containers::ArrayView<const Containers::StringView> paths) -> Containers::String
static auto CombinePath(std::initializer_list<Containers::StringView> paths) -> Containers::String
static auto GetDirectoryName(Containers::StringView path) -> Containers::StringView
Returns the path up to, but not including, the final separator.
static auto GetFileName(Containers::StringView path) -> Containers::StringView
Returns the path component after the final separator.
static auto GetFileNameWithoutExtension(Containers::StringView path) -> Containers::StringView
Returns the path component after the final separator without extension.
static auto GetExtension(Containers::StringView path) -> Containers::String
Returns the extension as lower-case string without dot or empty string if it is not found.
static auto FromNativeSeparators(Containers::StringView path) -> Containers::StringView
Converts path using native separators to forward slashes.
static auto ToNativeSeparators(Containers::StringView path) -> Containers::StringView
Converts path using forward slashes to native separators.
static auto GetAbsolutePath(Containers::StringView path) -> Containers::String
Returns an absolute path from a relative one.
static auto IsAbsolutePath(Containers::StringView path) -> bool
Returns true if the specified path is not empty and is absolute.
static auto GetExecutablePath() -> Containers::String
Returns the path to the executable file for the running application.
static auto GetConfigPath(Containers::StringView applicationName) -> Containers::String
Returns the path to the application-specific writable directory for configuration files.
static auto GetSavePath(Containers::StringView applicationName) -> Containers::String
Returns the path to the application-specific writable directory for saving game state.
static auto GetWorkingDirectory() -> Containers::String
Returns the path of the current working directory.
static auto SetWorkingDirectory(Containers::StringView path) -> bool
Sets the current working directory, the starting point for interpreting relative paths.
static auto GetHomeDirectory() -> Containers::String
Returns the path of the user home directory.
static auto GetTempDirectory() -> Containers::String
Returns the path of the directory for temporary files.
static auto GetExternalStorage() -> Containers::String
Returns the path of the Android external storage directory.
static auto GetLocalStorage() -> Containers::String
Returns the path pointing to ${XDG_DATA_HOME} environment variable.
static auto GetWindowsDirectory() -> Containers::String
Returns the path of Windows® directory.
static auto DirectoryExists(Containers::StringView path) -> bool
Returns true if the specified path is a directory.
static auto FileExists(Containers::StringView path) -> bool
Returns true if the specified path is a file.
static auto Exists(Containers::StringView path) -> bool
Returns true if the file or directory exists.
static auto IsReadable(Containers::StringView path) -> bool
Returns true if the file or directory is readable.
static auto IsWritable(Containers::StringView path) -> bool
Returns true if the file or directory is writeable.
static auto IsExecutable(Containers::StringView path) -> bool
Returns true if the file or directory is executable.
static auto IsReadableFile(Containers::StringView path) -> bool
Returns true if the path is a file and is readable.
static auto IsWritableFile(Containers::StringView path) -> bool
Returns true if the path is a file and is writeable.
static auto IsSymbolicLink(Containers::StringView path) -> bool
Returns true if the path is a symbolic link.
static auto IsHidden(Containers::StringView path) -> bool
Returns true if the file or directory is hidden.
static auto SetHidden(Containers::StringView path, bool hidden) -> bool
Makes a file or directory hidden or not.
static auto IsReadOnly(Containers::StringView path) -> bool
Returns true if the file or directory is read-only.
static auto SetReadOnly(Containers::StringView path, bool readonly) -> bool
Makes a file or directory read-only or not.
static auto CreateDirectories(Containers::StringView path) -> bool
Creates a new directory.
static auto RemoveDirectoryRecursive(Containers::StringView path) -> bool
Deletes an directory and all its content.
static auto RemoveFile(Containers::StringView path) -> bool
Deletes a file.
static auto Move(Containers::StringView oldPath, Containers::StringView newPath) -> bool
Renames or moves a file or a directory.
static auto MoveToTrash(Containers::StringView path) -> bool
Moves a file or a directory to trash.
static auto Copy(Containers::StringView oldPath, Containers::StringView newPath, bool overwrite = true) -> bool
Copies a file.
static auto GetFileSize(Containers::StringView path) -> std::int64_t
Returns the file size in bytes.
static auto GetCreationTime(Containers::StringView path) -> Containers::DateTime
Returns the creation time of the file or directory (if available).
static auto GetLastModificationTime(Containers::StringView path) -> Containers::DateTime
Returns the last time the file or directory was modified.
static auto GetLastAccessTime(Containers::StringView path) -> Containers::DateTime
Returns the last time the file or directory was accessed.
static auto GetPermissions(Containers::StringView path) -> Permission
Returns permissions of a given file or directory.
static auto ChangePermissions(Containers::StringView path, Permission mode) -> bool
Sets the file or directory permissions to those of the mask.
static auto AddPermissions(Containers::StringView path, Permission mode) -> bool
Adds permissions in the mask to a file or a directory.
static auto RemovePermissions(Containers::StringView path, Permission mode) -> bool
Removes permissions in the mask from a file or a directory.
static auto LaunchDirectoryAsync(Containers::StringView path) -> bool
Tries to open specified directory in operating system's file manager.
static auto MountAsPersistent(Containers::StringView path) -> bool
Mounts specified path to persistent file system.
static void SyncToPersistent()
Saves all changes to all persistent file systems.
static auto Open(Containers::StringView path, FileAccess mode, std::int32_t bufferSize = 8192) -> std::unique_ptr<Stream>
Opens a file stream with specified access mode.
static auto OpenAsMemoryMapped(Containers::StringView path, FileAccess mode) -> std::optional<Containers::Array<char, MapDeleter>>
Maps a file for reading and/or writing.

Constructors, destructors, conversion operators

FileSystem() deleted
~FileSystem() deleted

Constants

static std::size_t MaxPathLength constexpr
Maximum path length supported.
static char PathSeparator constexpr
Native path separator.

Enum documentation

enum class Death::IO::FileSystem::Permission

Available permissions to check or set, supports a bitwise combination of its member values.

Enumerators
None

None
Read

Read
Write

Write
Execute

Execute

enum class Death::IO::FileSystem::EnumerationOptions

Options that modify behavior of Directory, supports a bitwise combination of its member values.

Enumerators
None

Default behavior.
SkipFiles

Skip regular files.
SkipDirectories

Skip directories.
SkipSpecial

Skip everything that is not a file or directory.

Function documentation

static Containers::StringView Death::IO::FileSystem::FindPathCaseInsensitive(Containers::StringView path)

Returns path with correct case on case-sensitive platforms (or {} if path not found).

The target's file system already matches without case (see DEATH_CASE_INSENSITIVE_FILESYSTEM), so the path is returned unchanged and nothing is looked up. Note the difference in the "not found" half of the contract: this form cannot report a missing path and never returns {}, so a caller that uses the result as an existence test only works on the platforms that take the branch below. The callers that do so are all inside code those platforms do not build.

static Containers::String Death::IO::FileSystem::FindPathCaseInsensitive(Containers::String&& path)

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

static Containers::String Death::IO::FileSystem::CombinePath(Containers::ArrayView<const Containers::StringView> paths)

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

static Containers::String Death::IO::FileSystem::CombinePath(std::initializer_list<Containers::StringView> paths)

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

static Containers::String Death::IO::FileSystem::GetConfigPath(Containers::StringView applicationName)

Returns the path to the application-specific writable directory for configuration files.

Unlike GetSavePath(), which targets game-state storage (e.g., "Saved Games" on Windows), this targets the conventional location for application settings. On Windows, the directory is usually equivalent to %APPDATA%, which points to "C:\\Users\\<user>\\AppData\\Roaming\\<name>\\". On macOS, it's usually equivalent to "~/Library/Application Support/<name>/". On other Unix systems, it usually points to "${XDG_CONFIG_HOME}/<name>/" or "~/.config/<name>/". On Android, the internal data directory of the application is returned. On Windows RT, the local data folder of the package is returned.

static Containers::String Death::IO::FileSystem::GetSavePath(Containers::StringView applicationName)

Returns the path to the application-specific writable directory for saving game state.

On macOS, the directory is usually equivalent to "~/Library/Application Support/<name>/". On Android, it's the internal data directory of the application. On other Unix systems, it usually points to "${XDG_CONFIG_HOME}/<name>/ or "~/.config/<name>/". On Windows, it's usually "C:\\Users\\<user>\\Saved Games\\<name>\\". If the parent directory doesn't exist, %APPDATA% will be used instead. On Windows RT, the local data folder of the package is returned, because the application doesn't have access to the user directories.

static Containers::String Death::IO::FileSystem::GetHomeDirectory()

Returns the path of the user home directory.

On Unix and macOS, the directory is equivalent to ${HOME} environment variable. On Windows, the directory is equivalent to %USERPROFILE%, which usually points to "C:\\Users\\<user>\\".

static Containers::String Death::IO::FileSystem::GetTempDirectory()

Returns the path of the directory for temporary files.

On Unix and macOS, the directory is usually equivalent to "/tmp/". On Windows, the directory is equivalent to %TEMP%. On Android, the directory is usually equivalent to the cache directory of the package (for example "/data/user/0/<package>/cache/").

static Containers::String Death::IO::FileSystem::GetExternalStorage()

Returns the path of the Android external storage directory.

static Containers::String Death::IO::FileSystem::GetLocalStorage()

Returns the path pointing to ${XDG_DATA_HOME} environment variable.

If ${XDG_DATA_HOME} environment variable is not set, "~/.local/share/" will be used instead.

static Containers::String Death::IO::FileSystem::GetWindowsDirectory()

Returns the path of Windows® directory.

static bool Death::IO::FileSystem::MountAsPersistent(Containers::StringView path)

Mounts specified path to persistent file system.

static void Death::IO::FileSystem::SyncToPersistent()

Saves all changes to all persistent file systems.

static std::optional<Containers::Array<char, MapDeleter>> Death::IO::FileSystem::OpenAsMemoryMapped(Containers::StringView path, FileAccess mode)

Maps a file for reading and/or 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, returns std::nullopt_t. 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.