table.hpp

Go to the documentation of this file.

#pragma once

 
#include <cstddef>
#include <cstdint>
#include <span>
#include <string_view>
#include <vector>
 
#include <welder/vocabulary.hpp>
 
#include <wowlib/core/buffer.hpp>
#include <wowlib/core/client_version.hpp>
#include <wowlib/core/error.hpp>
#include <wowlib/core/file_key.hpp>
#include <wowlib/db/codec.hpp>
#include <wowlib/db/record_bridge.hpp>
#include <wowlib/db/schema.hpp>
#include <wowlib/db/table_core.hpp>
#include <wowlib/formats/common/string_block.hpp>
#include <wowlib/formats/common/validation.hpp>
#include <wowlib/fs/filesystem.hpp>
 
namespace wowlib::db {
  template <TableRecord Record>
  class Table {
  public:
    static constexpr ClientVersion Version = Record::Version;

    static constexpr std::string_view TableName = Record::TableName;
 
    [[=welder::mark::no_reassign,
      =welder::doc("The decoded records, file order. Mutate in place; write() "
        "serializes exactly this list.")]]
    std::vector<Record> records;
 
    Table() { _wire(); }
    Table(const Table& o) : records{o.records}, _core{o._core} { _wire(); }
 
    Table(Table&& o) noexcept : records{std::move(o.records)}, _core{std::move(o._core)} {
      _wire();
    }
 
    Table& operator=(const Table& o) {
      records = o.records;
      _core = o._core;
      _wire();
      return *this;
    }
 
    Table& operator=(Table&& o) noexcept {
      records = std::move(o.records);
      _core = std::move(o._core);
      _wire();
      return *this;
    }

    [[=welder::doc("Decode a table file image."),
      =welder::returns(
        "nothing; raises on malformed input or a schema mismatch")]]
    Result<void> read(std::span<const std::byte> data [[=welder::doc("the whole file content")]]) {
      return _core.read(data);
    }

        @return nothing, or why loading failed. */
    Result<void> read(fs::FileSystem& fs [[=welder::doc("the filesystem gateway")]],
                      const FileKey& key [[=welder::doc("the file to read")]]) {
      return _core.read(fs, key);
    }

    [[=welder::doc(
        "Serialize the table to a file image; a loaded table re-emits "
        "the format it was read from. `policy` decides how keyless "
        "encrypted sections are handled."),
      =welder::returns("the file bytes")]]
    Result<FileBuffer> write(EncryptedPolicy policy
      [[=welder::doc("keyless-section handling (WDC only)")]]
      = EncryptedPolicy::Preserve) const {
      return _core.write(policy);
    }

        @param policy how keyless encrypted sections are handled (see write()).
        @return nothing, or why saving failed. */
    Result<void> write(fs::FileSystem& fs [[=welder::doc("the filesystem gateway")]],
                       const FileKey& key [[=welder::doc("the file to write")]],
                       EncryptedPolicy policy
        [[=welder::doc("keyless-section handling (WDC only)")]]
                         = EncryptedPolicy::Preserve) const {
      return _core.write(fs, key, policy);
    }

    [[=welder::getter,
      =welder::doc(
        "The preserved string block the record string fields were decoded "
        "from; offsets never move, write() appends new strings past its "
        "end.")]]
    const formats::StringBlock& strings() const { return _core.strings(); }


    [[=welder::getter,
      =welder::doc(
        "The encrypted sections skipped on read: their records are not "
        "in records, but the file re-writes them verbatim.")]]
    const std::vector<EncryptedSection>& encryptedSections() const {
      return _core.encryptedSections();
    }

    [[=welder::getter,
      =welder::doc(
        "Whether the whole table decoded — false when encrypted sections "
        "were skipped.")]]
    bool fullyDecoded() const { return _core.fullyDecoded(); }
 
    // There is deliberately NO "value fits its column" check: a column's width
    // IS its member's width (schema.hpp derives one from the other) and the WDC
    // writer sizes each bit-packed field from the actual value range it is
    // given, so nothing reachable through the typed API can overflow what
    // encodes it.
    [[nodiscard]]
    [[=welder::doc(R"(
        Check the logical integrity contracts the records must satisfy to
        survive a write and load in the client: the primary key stays unique,
        and no string holds an embedded NUL the string block would truncate.
        write() never runs this.)"),
      =welder::returns("every violated contract, in record order")]]
    formats::ValidationReport validate() const { return _core.validate(); }
 
    [[nodiscard]]
    [[=welder::doc("Validate and raise on the first error instead of returning "
        "a report — the assert-style face of validate()."),
      =welder::returns("nothing; raises when validate() finds any error")]]
    Result<void> ensureValid() const { return validate().toResult(); }

    const TableCore& core() const { return _core; }
 
  private:
    void _wire() {
      static constexpr auto Schema = schemaOf<Record>();
      _core.wire(&records, &detail::RecordOpsFor<Record>, TableInfo{Version, TableName, Schema});
    }
 
    TableCore _core;
  };
}