dyn_table.hpp

Go to the documentation of this file.

#pragma once

 
#include <cstddef>
#include <cstdint>
#include <span>
#include <string>
#include <string_view>
#include <vector>
 
#include <wowlib/core/client_version.hpp>
#include <wowlib/core/error.hpp>
#include <wowlib/db/record_bridge.hpp>
#include <wowlib/db/schema_catalog.hpp>
#include <wowlib/db/table_core.hpp>
 
namespace wowlib::db {
  namespace detail {
    class ColumnRows final : public RecordSink, public RecordSource {
    public:
      ColumnRows() = default;

      explicit ColumnRows(std::span<const Column> schema);
 
      // --- RecordSink -------------------------------------------------------
      void clear() override;
      void reserve(std::size_t n) override;
      std::size_t add() override;
      std::size_t size() const override;
      std::uint32_t idOf(std::size_t record) const override;
      void setInt(std::size_t record, std::size_t column, std::size_t element, std::int64_t value) override;
      void setFloat(std::size_t record, std::size_t column, std::size_t element, float value) override;
      void setString(std::size_t record, std::size_t column, std::size_t element, std::string_view value) override;
      void cloneWithId(std::size_t src, std::uint32_t newId) override;
      std::size_t findById(std::uint32_t id) const override;
 
      // --- RecordSource -----------------------------------------------------
      std::int64_t getInt(std::size_t record, std::size_t column, std::size_t element) const override;
      std::uint32_t getSlot(std::size_t record, std::size_t column, std::size_t element) const override;
      std::string_view getString(std::size_t record, std::size_t column, std::size_t element) const override;
 
      // --- store operations beyond the codec protocol -----------------------
      void eraseRow(std::size_t record);

      std::string& stringSlot(std::size_t record, std::size_t column, std::size_t element);

      std::uint32_t& flagsSlot(std::size_t record, std::size_t column);
      std::uint32_t flagsSlot(std::size_t record, std::size_t column) const;

      struct Facts {
        AccessKind kind = AccessKind::U32; 
        std::uint8_t elemBytes = 0; 
        std::uint16_t podSlots = 0; 
        std::uint16_t strSlots = 0; 
        bool hasFlags = false; 
      };

      const Facts& facts(std::size_t column) const { return _facts[column]; }

      std::span<const std::byte> podBytes(std::size_t column) const {
        return _cols[column].pod;
      }

      std::span<const Column> schema() const { return _schema; }
 
    private:
      struct Store {
        std::vector<std::byte> pod; 
        std::vector<std::string> strs; 
        std::vector<std::uint32_t> flags; 
      };

      std::byte* _podPtr(std::size_t record, std::size_t column, std::size_t element);
      const std::byte* _podPtr(std::size_t record, std::size_t column, std::size_t element) const;
 
      std::span<const Column> _schema{}; 
      std::vector<Facts> _facts{}; 
      std::vector<Store> _cols{}; 
      std::size_t _rows = 0; 
      std::size_t _idColumn = SIZE_MAX; 
    };
  }

  struct PodColumnView {
    std::span<const std::byte> bytes; 
    std::uint8_t elemBytes = 0; 
    std::uint16_t elemsPerRow = 1; 
    bool isSigned = false; 
    bool isFloat = false; 
  };

  class [[
      =welder::weld,
      =welder::weld_as("Table"),
      =welder::doc(R"(
        A client-database table with its schema resolved at RUNTIME from
        WoWDBDefs data: open any table of any targeted client era, read its
        rows, edit cells by (row, column, element), and write it back in the
        era's own format. Cells are addressed by column index (see
        column_index/column_info); scalar columns also expose zero-copy
        array views.)")
    ]] DynTable : public TableBase {
  public:
    DynTable() = default;
 
#if WOWLIB_DB_SCHEMA_EMBEDDED
    [[=welder::doc("Open an empty table by name, with its schema resolved "
        "for the given client version from the built-in WoWDBDefs "
        "data."),
      =welder::returns("the empty, schema-bound table; raises for an unknown "
        "table or an uncovered client era")]]
    static Result<DynTable> open(std::string_view table [[=welder::doc("the table name, e.g. \"Map\"")]],
                                 ClientVersion version [[=welder::doc("the client to resolve for")]]);
#endif

    [[=welder::mark::exclude]]
    static DynTable fromSchema(const TableSchema& schema, ClientVersion version);
 
    DynTable(const DynTable& other);
    DynTable& operator=(const DynTable& other);
    DynTable(DynTable&& other) noexcept;
    DynTable& operator=(DynTable&& other) noexcept;
    ~DynTable() = default;

    [[=welder::getter, =welder::doc("The number of rows.")]]
    std::size_t rowCount() const { return _rows.size(); }

    [[=welder::getter, =welder::doc("The number of schema columns.")]]
    std::size_t columnCount() const { return _rows.schema().size(); }

    [[=welder::mark::exclude]]
    std::span<const Column> schema() const { return _rows.schema(); }

    [[=welder::getter, =welder::doc(
      "The client version the table serializes for.")]]
    ClientVersion version() const { return _version; }

    [[=welder::getter, =welder::doc("The table name (WoWDBDefs identifier).")]]
    std::string_view name() const { return _name; }

    [[=welder::doc("The schema entry of one column: name, value class, "
        "shape and key roles."),
      =welder::returns("the column description; raises when out of range")]]
    Result<Column> columnInfo(std::size_t column [[=welder::doc("the column index")]]) const;

    [[=welder::doc("The index of the column with the given name: the "
        "canonical snake_case spelling ('map_name'), or the verbatim "
        "WoWDBDefs spelling ('MapName_lang') as an alias; case-sensitive "
        "either way."),
      =welder::returns("the column index; raises when no column matches")]]
    Result<std::size_t> columnIndex(std::string_view name [[=welder::doc("the column name, case-sensitive")]]) const;

    [[=welder::doc("Append a fresh zero/empty row."),
      =welder::returns("the new row's index")]]
    std::size_t appendRow() { return _rows.add(); }

    [[=welder::doc("Remove one row."),
      =welder::returns("nothing; raises when the row is out of range")]]
    Result<void> eraseRow(std::size_t row [[=welder::doc("the row index")]]);

    [[=welder::doc(
      "Drop every row (the schema and preserved decode state stay).")]]
    void clearRows() { _rows.clear(); }

    [[=welder::doc("The first row whose $id$ column equals the given key."),
      =welder::returns("the row index; raises when no row matches")]]
    Result<std::size_t> findById(std::uint32_t id [[=welder::doc("the primary key value")]]) const;

    [[=welder::doc("Read an integer cell, sign-extended from the column's "
        "exact width. LocString flags read via locstring_flags."),
      =welder::returns("the value; raises on a non-Int column or an "
        "out-of-range index")]]
    Result<std::int64_t> getInt(std::size_t row [[=welder::doc("the row index")]],
                                 std::size_t column [[=welder::doc("an Int column's index")]],
                                 std::size_t element [[=welder::doc("the array element")]] = 0) const;

    [[=welder::doc("Write an integer cell (truncates to the column's exact "
        "width, exactly as the typed member assignment did)."),
      =welder::returns("nothing; raises on a non-Int column or an "
        "out-of-range index")]]
    Result<void> setInt(std::size_t row [[=welder::doc("the row index")]],
                         std::size_t column [[=welder::doc("an Int column's index")]],
                         std::int64_t value [[=welder::doc("the value to store")]],
                         std::size_t element [[=welder::doc("the array element")]] = 0);

    [[=welder::doc("Read a float cell."),
      =welder::returns("the value; raises on a non-Float column or an "
        "out-of-range index")]]
    Result<float> getFloat(std::size_t row [[=welder::doc("the row index")]],
                            std::size_t column [[=welder::doc("a Float column's index")]],
                            std::size_t element [[=welder::doc("the array element")]] = 0) const;
    [[=welder::doc("Write a float cell."),
      =welder::returns("nothing; raises on a non-Float column or an "
        "out-of-range index")]]
    Result<void> setFloat(std::size_t row [[=welder::doc("the row index")]],
                           std::size_t column [[=welder::doc("a Float column's index")]],
                           float value [[=welder::doc("the value to store")]],
                           std::size_t element [[=welder::doc("the array element")]] = 0);

    [[=welder::doc("Read a string cell (String columns: the array element; "
        "LocString columns: the locale slot)."),
      =welder::returns("the text; raises on a non-string column or an "
        "out-of-range index")]]
    Result<std::string_view> getString(std::size_t row [[=welder::doc("the row index")]],
                                        std::size_t column [[=welder::doc("a String/LocString column's index")]],
                                        std::size_t element [[=welder::doc("the array element / locale slot")]] = 0)
    const;
    [[=welder::doc("Write a string cell (String columns: the array element; "
        "LocString columns: the locale slot)."),
      =welder::returns("nothing; raises on a non-string column or an "
        "out-of-range index")]]
    Result<void> setString(std::size_t row [[=welder::doc("the row index")]],
                            std::size_t column [[=welder::doc("a String/LocString column's index")]],
                            std::string_view value [[=welder::doc("the text to store")]],
                            std::size_t element [[=welder::doc("the array element / locale slot")]] = 0);

    [[=welder::doc("Read a LocString column's flags word."),
      =welder::returns("the flags; raises on a non-LocString column")]]
    Result<std::uint32_t> locstringFlags(std::size_t row [[=welder::doc("the row index")]],
                                          std::size_t column [[=welder::doc("a LocString column's index")]]) const;
    [[=welder::doc("Write a LocString column's flags word."),
      =welder::returns("nothing; raises on a non-LocString column")]]
    Result<void> setLocstringFlags(std::size_t row [[=welder::doc("the row index")]],
                                     std::size_t column [[=welder::doc("a LocString column's index")]],
                                     std::uint32_t flags [[=welder::doc("the flags word")]]);

    [[=welder::mark::exclude]] // bound by hand: numpy over the raw buffer
    Result<PodColumnView> podColumn(std::size_t column) const;
 
  private:
    void _wire() {
      _core.wire(&_rows, &_rows, TableInfo{_version, _diskName, _rows.schema()});
    }

    Result<const detail::ColumnRows::Facts*> _checkCell(std::size_t row,
                                                        std::size_t column,
                                                        std::size_t element,
                                                        ColumnType expected) const;
 
    detail::ColumnRows _rows{}; 
    ClientVersion _version{}; 
    std::string_view _name; 
    std::string_view _diskName; 
  };
}