Compiled Resources

Resources provides exact, case-sensitive lookup by identifier and normalized relative path. Optional accessors distinguish a present empty file from a missing key, while OrThrow variants report ResourceError.

Stored and Logical Values

getStoredData() borrows the immutable bytes embedded in the executable. getData() and getText() return the original logical content and transparently decode compressed resources. Uncompressed text uses literal-backed storage, while decoded values are cached on first access. Generated storage keeps opaque data blocks separate from versioned metadata blocks. The resource manager parses and caches metadata only when the resource index is first accessed.

Metadata

ResourceInfo reports logical and stored sizes, optional compression and SHA3-256 metadata, and the reserved encryption state. The encryption state is always false for compiled resources generated by this version.

Application Access

Application::resources() creates the manager lazily and returns a read-only process-wide resource interface. Applications without generated resources receive an empty manager.

Interface

class ResourceError : public erbsland::err::RuntimeError

A required resource lookup or decoding failure.

Public Functions

ResourceError(ResourceErrorCategory category, text::String message) noexcept

Create a resource error.

ResourceError(ResourceErrorCategory category, std::string_view message) noexcept

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

inline ResourceErrorCategory category() const noexcept

Get the machine-readable error category.

enum class erbsland::resource::ResourceErrorCategory : uint8_t

A machine-readable resource lookup failure category.

Values:

enumerator NotFound

No resource exists for the requested identifier and path.

enumerator InvalidData

The stored resource representation cannot be decoded.

class ResourceInfo

Metadata for one compiled resource.

Public Functions

ResourceInfo(unit::ByteLength originalSize, unit::ByteLength storedSize, std::optional<mem::ByteCompressionAlgorithm> compressionAlgorithm, std::optional<cryptology::HashAlgorithm> hashAlgorithm, mem::ByteBlock hash, bool encrypted) noexcept

Create resource metadata.

inline bool isCompressed() const noexcept

Test whether the resource is compressed.

inline bool hasHash() const noexcept

Test whether a hash is available.

inline bool isEncrypted() const noexcept

Test whether the resource is encrypted.

inline unit::ByteLength originalSize() const noexcept

Get the original logical byte size.

inline unit::ByteLength storedSize() const noexcept

Get the embedded representation size.

inline const std::optional<mem::ByteCompressionAlgorithm> &compressionAlgorithm() const noexcept

Get the compression algorithm, or no value for uncompressed data.

inline const std::optional<cryptology::HashAlgorithm> &hashAlgorithm() const noexcept

Get the hash algorithm, or no value when hashing was disabled.

inline const mem::ByteBlock &hash() const noexcept

Get the logical-data digest, or an empty block when hashing was disabled.

class ResourceManager : public erbsland::resource::Resources

The default lazy manager for process-wide compiled resources.

Construction performs no allocation. The immutable lookup index and decoded values are created on first access.

See: Compiled Resources

Public Functions

ResourceManager()

Create an empty manager that initializes its index on first access.

~ResourceManager() override

Release cached compiled-resource values.

virtual bool contains(const text::String &identifier, const text::String &path) const override

Test whether a resource exists.

virtual std::optional<mem::ConstByteSpan> getStoredData(const text::String &identifier, const text::String &path) const override

Get the exact embedded representation.

virtual mem::ConstByteSpan getStoredDataOrThrow(const text::String &identifier, const text::String &path) const override

Get the exact embedded representation.

Throws:

ResourceError – If the resource does not exist.

virtual std::optional<mem::ByteBlock> getData(const text::String &identifier, const text::String &path) const override

Get the original logical bytes, transparently decompressing when necessary.

virtual mem::ByteBlock getDataOrThrow(const text::String &identifier, const text::String &path) const override

Get the original logical bytes.

Throws:

ResourceError – If the resource is missing or invalid.

virtual std::optional<text::String> getText(const text::String &identifier, const text::String &path) const override

Get the exact logical bytes as tolerant UTF-8 text.

virtual text::String getTextOrThrow(const text::String &identifier, const text::String &path) const override

Get the exact logical bytes as tolerant UTF-8 text.

Throws:

ResourceError – If the resource is missing or invalid.

virtual std::optional<ResourceInfo> getInfo(const text::String &identifier, const text::String &path) const override

Get resource metadata.

virtual ResourceInfo getInfoOrThrow(const text::String &identifier, const text::String &path) const override

Get resource metadata.

Throws:

ResourceError – If the resource does not exist.

class Resources

A thread-safe read-only compiled-resource lookup interface.

Borrowed stored-data spans remain valid for the lifetime of this interface. Implementations must permit concurrent calls to every const lookup method.

Subclassed by erbsland::resource::ResourceManager

Public Functions

virtual bool contains(const text::String &identifier, const text::String &path) const = 0

Test whether a resource exists.

virtual std::optional<mem::ConstByteSpan> getStoredData(const text::String &identifier, const text::String &path) const = 0

Get the exact embedded representation.

virtual mem::ConstByteSpan getStoredDataOrThrow(const text::String &identifier, const text::String &path) const = 0

Get the exact embedded representation.

Throws:

ResourceError – If the resource does not exist.

virtual std::optional<mem::ByteBlock> getData(const text::String &identifier, const text::String &path) const = 0

Get the original logical bytes, transparently decompressing when necessary.

virtual mem::ByteBlock getDataOrThrow(const text::String &identifier, const text::String &path) const = 0

Get the original logical bytes.

Throws:

ResourceError – If the resource is missing or invalid.

virtual std::optional<text::String> getText(const text::String &identifier, const text::String &path) const = 0

Get the exact logical bytes as tolerant UTF-8 text.

virtual text::String getTextOrThrow(const text::String &identifier, const text::String &path) const = 0

Get the exact logical bytes as tolerant UTF-8 text.

Throws:

ResourceError – If the resource is missing or invalid.

virtual std::optional<ResourceInfo> getInfo(const text::String &identifier, const text::String &path) const = 0

Get resource metadata.

virtual ResourceInfo getInfoOrThrow(const text::String &identifier, const text::String &path) const = 0

Get resource metadata.

Throws:

ResourceError – If the resource does not exist.