cubos::core::data::File class final
#include <core/data/fs/file.hpp>

Represents a file in the virtual file system of the engine.

Instances of this class are always held through a File::Handle, which is just a smart shared pointer.

Files may either be regular files or directories. Directories can have children files, but no data. Regular files are only allowed inside mounted archives, since they must have data associated with them, while the directories are just a way to organize the files.

Public types

enum class OpenMode { Read, Write, ReadWrite }
Possible modes to open files in.
using Handle = std::shared_ptr<File>
Handle to a file in the Cubos virtual file system.

Public functions

auto mount(std::string_view path, std::unique_ptr<Archive> archive) -> bool
Mounts an archive to a path relative to this file.
auto unmount(std::string_view path) -> bool
Unmounts an archive from a path relative to this file.
auto find(std::string_view path) -> Handle
Gets a handle to a file relative to this file.
auto create(std::string_view path, bool directory = false) -> Handle
Creates a new file on a path relative to this file.
auto destroy() -> bool
Marks this file for destruction.
auto open(OpenMode mode) -> std::unique_ptr<memory::Stream>
Opens this file for reading or writing.
auto name() const -> std::string_view
Gets the name of this file.
auto path() const -> std::string_view
Gets the absolute path of this file.
auto directory() const -> bool
Checks whether this file is a directory.
auto archive() const -> const std::shared_ptr<Archive>&
Gets the archive this file is in.
auto id() const -> std::size_t
Gets the identifier of this file on its archive.
auto parent() const -> Handle
Gets the parent directory of this file.
auto sibling() const -> Handle
Gets the next sibling of this file.
auto child() const -> Handle
Gets the first child of this file.

Enum documentation

enum class cubos::core::data::File::OpenMode

Possible modes to open files in.

Enumerators
Read

Open the file for reading.
Write

Open the file for writing, overwriting any previous changes.
ReadWrite

Open the file for reading or writing data.

Typedef documentation

using cubos::core::data::File::Handle = std::shared_ptr<File>

Handle to a file in the Cubos virtual file system.

This is a smart shared pointer, so that files are not destroyed while being referenced.

Function documentation

bool cubos::core::data::File::mount(std::string_view path, std::unique_ptr<Archive> archive)

Mounts an archive to a path relative to this file.

Parameters
path Path relative to this file to mount the archive on.
archive Archive to mount.
Returns Whether the archive was successfully mounted.

Creates any parent directories that may be necessary, but the mount point itself must not already exist.

This method fails on the following conditions:

  • path is absolute or invalid.
  • a parent file in the path exists and is not a directory.
  • a parent directory in the path belongs to an archive.
  • a file already exists at the mount point.

bool cubos::core::data::File::unmount(std::string_view path)

Unmounts an archive from a path relative to this file.

Parameters
path Path relative to this file to unmount the archive from.
Returns Whether the archive was successfully unmounted.

Removes all of the archive's files from the virtual file system.

This method fails on the following conditions:

  • path is absolute or invalid.
  • any of the files in the path do not exist.
  • the target path is not the mount point for an archive.

Handle cubos::core::data::File::find(std::string_view path)

Gets a handle to a file relative to this file.

Parameters
path Path relative to this file to get the file from.
Returns Handle to the file, or nullptr on failure.

Fails if the file does not exist or if the path is absolute or invalid.

Handle cubos::core::data::File::create(std::string_view path, bool directory = false)

Creates a new file on a path relative to this file.

Parameters
path Relative path to the file.
directory Whether the new file should be a directory.
Returns Handle to the file, or nullptr on failure.

The destination location must be writeable - that is, it must be under a mounted writeable archive. If a file at the given path already exists, it is returned instead. Any parent directories that may be necessary are created.

This method fails on the following conditions:

  • path is absolute or invalid.
  • a parent directory in the path does not exist and cannot be created.
  • a parent directory in the path already exists as a regular file.
  • a file of a different type already exists at the destination.

bool cubos::core::data::File::destroy()

Marks this file for destruction.

Returns Whether the file was successfully marked for destruction.

Although the file will only be deleted when no more references to it exist, it is immediately removed from the virtual file system and this method is called recursively on all its children.

This method fails on the following conditions:

  • this file is the mount point of an archive.
  • this file does not belong to an archive.
  • this file belongs to a read-only archive.

std::unique_ptr<memory::Stream> cubos::core::data::File::open(OpenMode mode)

Opens this file for reading or writing.

Parameters
mode Mode to open the file in.
Returns Handle to a file stream, or nullptr on failure.

If the file is being written to, blocks until the other threads are done with the file.

This method fails on the following conditions:

  • this file is a directory.
  • this file belongs to a read-only archive and the mode is not OpenMode::Read.

std::string_view cubos::core::data::File::name() const

Gets the name of this file.

Returns Name of this file.

std::string_view cubos::core::data::File::path() const

Gets the absolute path of this file.

Returns Absolute path of this file.

bool cubos::core::data::File::directory() const

Checks whether this file is a directory.

Returns Whether this file is a directory.

const std::shared_ptr<Archive>& cubos::core::data::File::archive() const

Gets the archive this file is in.

Returns Archive this file is in, or nullptr if the file is not in an archive.

std::size_t cubos::core::data::File::id() const

Gets the identifier of this file on its archive.

Returns Identifier of this file on its archive, or 0 if it is not in an archive.

Handle cubos::core::data::File::parent() const

Gets the parent directory of this file.

Returns File's parent directory, or nullptr if there isn't one.

Handle cubos::core::data::File::sibling() const

Gets the next sibling of this file.

Returns Next sibling, or nullptr if this file is the last child of its parent.

Handle cubos::core::data::File::child() const

Gets the first child of this file.

Returns First child, or nullptr if this file is not a directory or if it is empty.