bsa::tes4::file class final
#include <bsa/tes4.hpp>

Represents a file within the TES4 virtual filesystem.

Base classes

class bsa::components::compressed_byte_container: A byte storage container with compression support.

Capacity

auto empty() const -> bool noexcept: Checks if the underlying byte container is empty.
auto size() const -> std::size_t noexcept: Returns the size of the underlying byte container.

Compression

void compress(version a_version, compression_codec a_codec = compression_codec::normal): Compresses the file.
auto compress_bound(version a_version, compression_codec a_codec = compression_codec::normal) const -> std::size_t: Returns an upper bound on the storage size required to compress the file.
auto compress_into(version a_version, std::span<std::byte> a_out, compression_codec a_codec = compression_codec::normal) const -> std::size_t: Compresses the file into the given buffer.

Decompression

void decompress(version a_version, compression_codec a_codec = compression_codec::normal): Decompresses the file.
void decompress_into(version a_version, std::span<std::byte> a_out, compression_codec a_codec = compression_codec::normal) const: Decompresses the file into the given buffer.
auto decompressed_size() const -> std::size_t noexcept: Retrieves the decompressed size of the compressed storage.

Doxygen only

void doxygen_read(version a_version, compression_codec a_codec = compression_codec::normal, compression_type a_compression = compression_type::decompressed) protected
void doxygen_write(version a_version, compression_codec a_codec = compression_codec::normal) const protected

Element access

auto as_bytes() const -> std::span<const std::byte> noexcept: Retrieves an immutable view into the underlying bytes.
auto data() const -> const std::byte* noexcept: Retrieves an immutable pointer to the underlying bytes.

Member types

using key = components::key<hashing::hash, hashing::hash_file_in_place>: The key used to indentify a file.

Modifiers

void clear() noexcept: Clears the contents of the file.
void set_data(std::span<const std::byte> a_data, std::optional<std::size_t> a_decompressedSize = std::nullopt) noexcept: Assigns the underlying container to be a non-owning view into the given data.
void set_data(std::vector<std::byte> a_data, std::optional<std::size_t> a_decompressedSize = std::nullopt) noexcept: Assigns the underlying container to be an owning view into the given data.

Observers

auto compressed() const -> bool noexcept: Checks if the underlying bytes are compressed.

Reading

void read(std::filesystem::path a_path, version a_version, compression_codec a_codec = compression_codec::normal, compression_type a_compression = compression_type::decompressed): Reads the contents of the source.
void read(std::span<const std::byte> a_src, version a_version, compression_codec a_codec = compression_codec::normal, compression_type a_compression = compression_type::decompressed, copy_type a_copy = copy_type::deep): Reads the contents of the source.

Writing

void write(std::filesystem::path a_path, version a_version, compression_codec a_codec = compression_codec::normal) const
void write(binary_io::any_ostream& a_dst, version a_version, compression_codec a_codec = compression_codec::normal) const

Function documentation

bool bsa::tes4::file::empty() const noexcept
#include <bsa/detail/common.hpp>

Checks if the underlying byte container is empty.

std::size_t bsa::tes4::file::size() const noexcept
#include <bsa/detail/common.hpp>

Returns the size of the underlying byte container.

void bsa::tes4::file::compress(version a_version, compression_codec a_codec = compression_codec::normal)

Compresses the file.

Parameters
a_version	The version to compress the file for.
a_codec	The codec to use.
Exceptions
bsa::compression_error	Thrown when any backend compression library errors are encountered.

std::size_t bsa::tes4::file::compress_bound(version a_version, compression_codec a_codec = compression_codec::normal) const

Returns an upper bound on the storage size required to compress the file.

Parameters
a_version	The version the file would be compressed for.
a_codec	The codec to use.
Returns	Returns the size required to successfully compress the file.
Exceptions
bsa::compression_error	Thrown when any backend compression library errors are encountered.

std::size_t bsa::tes4::file::compress_into(version a_version, std::span<std::byte> a_out, compression_codec a_codec = compression_codec::normal) const

Compresses the file into the given buffer.

Parameters
a_version	The version to compress the file for.
a_out	The buffer to compress the file into.
a_codec	The codec to use.
Returns	The final size of the compressed buffer.
Exceptions
bsa::compression_error	Thrown when any backend compression library errors are encountered.

void bsa::tes4::file::decompress(version a_version, compression_codec a_codec = compression_codec::normal)

Decompresses the file.

Parameters
a_version	The version to decompress the file for.
a_codec	The codec to use.
Exceptions
bsa::compression_error	Thrown when any backend compression library errors are encountered.

void bsa::tes4::file::decompress_into(version a_version, std::span<std::byte> a_out, compression_codec a_codec = compression_codec::normal) const

Decompresses the file into the given buffer.

Parameters
a_version	The version to decompress the file for.
a_out	The buffer to decompress the file into.
a_codec	The codec to use.
Exceptions
bsa::compression_error	Thrown when any backend compression library errors are encountered.

std::size_t bsa::tes4::file::decompressed_size() const noexcept
#include <bsa/detail/common.hpp>

Retrieves the decompressed size of the compressed storage.

Only valid if the container is compressed.

void bsa::tes4::file::doxygen_read(version a_version, compression_codec a_codec = compression_codec::normal, compression_type a_compression = compression_type::decompressed) protected

Parameters
a_version	The version to compress the file for.
a_codec	The codec to use.
a_compression	The resulting compression of the file read.

void bsa::tes4::file::doxygen_write(version a_version, compression_codec a_codec = compression_codec::normal) const protected

Parameters
a_version	The version to decompress the file for.
a_codec	The codec to use.

std::span<const std::byte> bsa::tes4::file::as_bytes() const noexcept
#include <bsa/detail/common.hpp>

Retrieves an immutable view into the underlying bytes.

const std::byte* bsa::tes4::file::data() const noexcept
#include <bsa/detail/common.hpp>

Retrieves an immutable pointer to the underlying bytes.

void bsa::tes4::file::set_data(std::span<const std::byte> a_data, std::optional<std::size_t> a_decompressedSize = std::nullopt) noexcept
#include <bsa/detail/common.hpp>

Assigns the underlying container to be a non-owning view into the given data.

Parameters
a_data	The data to store a view to.
a_decompressedSize	The decompressed size of the data, if the given data is compressed.

void bsa::tes4::file::set_data(std::vector<std::byte> a_data, std::optional<std::size_t> a_decompressedSize = std::nullopt) noexcept
#include <bsa/detail/common.hpp>

Assigns the underlying container to be an owning view into the given data.

Parameters
a_data	The data to take ownership of.
a_decompressedSize	The decompressed size of the data, if the given data is compressed.

bool bsa::tes4::file::compressed() const noexcept
#include <bsa/detail/common.hpp>

Checks if the underlying bytes are compressed.

void bsa::tes4::file::read(std::filesystem::path a_path, version a_version, compression_codec a_codec = compression_codec::normal, compression_type a_compression = compression_type::decompressed)

Reads the contents of the source.

Parameters
a_path	The path to the given archive on the native filesystem.
a_version	The version to compress the file for.
a_codec	The codec to use.
a_compression	The resulting compression of the file read.
Exceptions
binary_io::buffer_exhausted	Thrown when reads index out of bounds.
std::system_error	Thrown when filesystem errors are encountered.

void bsa::tes4::file::read(std::span<const std::byte> a_src, version a_version, compression_codec a_codec = compression_codec::normal, compression_type a_compression = compression_type::decompressed, copy_type a_copy = copy_type::deep)

Reads the contents of the source.

Parameters
a_src	The source to read from.
a_version	The version to compress the file for.
a_codec	The codec to use.
a_compression	The resulting compression of the file read.
a_copy	The method to use when copying data from `a_src`.
Exceptions
binary_io::buffer_exhausted	Thrown when reads index out of bounds.

void bsa::tes4::file::write(std::filesystem::path a_path, version a_version, compression_codec a_codec = compression_codec::normal) const

Parameters
a_path	The path to write the archive to on the native filesystem.
a_version	The version to decompress the file for.
a_codec	The codec to use.

void bsa::tes4::file::write(binary_io::any_ostream& a_dst, version a_version, compression_codec a_codec = compression_codec::normal) const

Parameters
a_dst	The stream to write the archive to.
a_version	The version to decompress the file for.
a_codec	The codec to use.