cubos::core::ecs::SparseRelationTable class final
#include <core/ecs/table/sparse_relation/table.hpp>

A table which stores relations. Allows for quick insertion, deletion and iteration.

Internally, the table is stored simply as a vector of relations and their data. Each row in this table stores:

  • the 'from' entity index;
  • the 'to' entity index;
  • the previous and next rows with the same 'from' index;
  • the previous and next rows with the same 'to' index;
  • the relation data itself.

To make random accesses more efficient, we also store an hashtable which maps entity index pairs to rows. This way, we can quickly check if a relation exists or where it's stored.

Additionally, we store two other hashtables, one which associate 'from' and 'to' indices to rows in the table which represent the first and last nodes of linked lists, where each node is a row with the same 'from' or 'to' index, depending on the list.

These linked lists are essential to provide fast query times, as instead of having to iterate over the entire table and filter for entity, we only need to follow the linked list chain.

Public types

struct Output
Output structure for the iterator.
enum class Transformation { None, Swap, SwapIfGreater }
Transformations to apply while moving relations between tables.

Constructors, destructors, conversion operators

SparseRelationTable(const reflection::Type& relationType)
Constructs with the given relation type.
Iterator(const SparseRelationTable& table, uint32_t row)
Constructs.
Iterator(const Iterator& other) defaulted
Copy constructs.
View(const SparseRelationTable& table, uint32_t index, bool isFrom)
Constructs.
Iterator(const SparseRelationTable& table, uint32_t row, bool isFrom)
Constructs.
Iterator(const Iterator& other) defaulted
Copy constructs.

Public functions

void clear()
Removes all relations from the table.
auto insert(uint32_t from, uint32_t to, void* value) -> bool
Adds a relation between the given indices. If it already exists, overwrites it.
auto erase(uint32_t from, uint32_t to) -> bool
Removes a relation between the given indices. If it didn't exist, does nothing.
auto eraseFrom(uint32_t from) -> std::size_t
Removes all relations from the given index.
auto moveFrom(uint32_t from, SparseRelationTable& other, Transformation transformation) -> std::size_t
Moves all relations with the given from index to another table.
auto eraseTo(uint32_t to) -> std::size_t
Removes all relations to the given index.
auto moveTo(uint32_t to, SparseRelationTable& other, Transformation transformation) -> std::size_t
Moves all relations with the given to index to another table.
auto contains(uint32_t from, uint32_t to) const -> bool
Checks whether the given relation exists between the given indices.
auto row(uint32_t from, uint32_t to) const -> std::size_t
Gets the row of the relation with the given indices, or size() if there is none.
auto at(std::size_t row) -> void*
Get the relation at the given row.
auto at(std::size_t row) const -> const void*
Get the relation at the given row.
void indices(std::size_t row, uint32_t& from, uint32_t& to) const
Get the entity indices at the given row.
auto from(std::size_t row) const -> uint32_t
Get the 'from' entity index at the given row.
auto to(std::size_t row) const -> uint32_t
Get the 'to' entity index at the given row.
auto firstFrom(uint32_t index) const -> std::size_t
Gets the first row with the given from index, or size() if there is none.
auto firstTo(uint32_t index) const -> std::size_t
Gets the first row with the given to index, or size() if there is none.
auto nextFrom(std::size_t row) const -> std::size_t
Gets the next row with the same from index, or size() if there is none.
auto nextTo(std::size_t row) const -> std::size_t
Gets the next row with the same to index, or size() if there is none.
auto begin() const -> Iterator
Gets an iterator to the first relation of the table.
auto end() const -> Iterator
Gets an iterator which represents the end of the table.
auto viewFrom(uint32_t from) const -> View
Returns a view of the relations with the given from index.
auto viewTo(uint32_t to) const -> View
Returns a view of the relations with the given to index.
auto size() const -> std::size_t
Returns the number of relations on the table.
auto operator==(const Iterator& other) const -> bool
Compares two iterators.
auto operator*() const -> const Output&
Accesses the relation referenced by this iterator.
auto operator->() const -> const Output*
Accesses the relation referenced by this iterator.
auto operator++() -> Iterator&
Advances the iterator.
auto begin() const -> Iterator
Gets an iterator to the first relation of the view.
auto end() const -> Iterator
Gets an iterator which represents the end of the view.
auto operator==(const Iterator& other) const -> bool
Compares two iterators.
auto operator*() const -> const Output&
Accesses the relation referenced by this iterator.
auto operator->() const -> const Output*
Accesses the relation referenced by this iterator.
auto operator++() -> Iterator&
Advances the iterator.

Enum documentation

enum class cubos::core::ecs::SparseRelationTable::Transformation

Transformations to apply while moving relations between tables.

Enumerators
None

Keep the relations as they are.
Swap

Flip the 'from' and 'to' indices.
SwapIfGreater

Swap if the 'from' index is greater than the 'to' index.

Function documentation

cubos::core::ecs::SparseRelationTable::SparseRelationTable(const reflection::Type& relationType)

Constructs with the given relation type.

Parameters
relationType Relation type.

cubos::core::ecs::SparseRelationTable::Iterator(const SparseRelationTable& table, uint32_t row)

Constructs.

Parameters
table Table.
row Row.

cubos::core::ecs::SparseRelationTable::Iterator(const Iterator& other) defaulted

Copy constructs.

Parameters
other Other iterator.

cubos::core::ecs::SparseRelationTable::View(const SparseRelationTable& table, uint32_t index, bool isFrom)

Constructs.

Parameters
table
index Index being iterated over.
isFrom Is the index a from index? If false, its a to index.

cubos::core::ecs::SparseRelationTable::Iterator(const SparseRelationTable& table, uint32_t row, bool isFrom)

Constructs.

Parameters
table Table.
row Row.
isFrom Are we iterating over the same from index? If false, iterates over to.

cubos::core::ecs::SparseRelationTable::Iterator(const Iterator& other) defaulted

Copy constructs.

Parameters
other Other iterator.

bool cubos::core::ecs::SparseRelationTable::insert(uint32_t from, uint32_t to, void* value)

Adds a relation between the given indices. If it already exists, overwrites it.

Parameters
from From index.
to To index.
value Relation value to move from.
Returns Whether the relation already existed.

bool cubos::core::ecs::SparseRelationTable::erase(uint32_t from, uint32_t to)

Removes a relation between the given indices. If it didn't exist, does nothing.

Parameters
from From index.
to To index.
Returns Whether the relation existed.

std::size_t cubos::core::ecs::SparseRelationTable::eraseFrom(uint32_t from)

Removes all relations from the given index.

Parameters
from From index.
Returns How many relations were erased.

std::size_t cubos::core::ecs::SparseRelationTable::moveFrom(uint32_t from, SparseRelationTable& other, Transformation transformation)

Moves all relations with the given from index to another table.

Parameters
from From index.
other Other table. Must have the same relation type.
transformation Transformation to apply to the relations.
Returns How many relations were erased.

std::size_t cubos::core::ecs::SparseRelationTable::eraseTo(uint32_t to)

Removes all relations to the given index.

Parameters
to To index.
Returns How many relations were moved.

std::size_t cubos::core::ecs::SparseRelationTable::moveTo(uint32_t to, SparseRelationTable& other, Transformation transformation)

Moves all relations with the given to index to another table.

Parameters
to To index index.
other Other table. Must have the same relation type.
transformation Transformation to apply to the relations.
Returns How many relations were moved.

bool cubos::core::ecs::SparseRelationTable::contains(uint32_t from, uint32_t to) const

Checks whether the given relation exists between the given indices.

Parameters
from From index.
to To index.
Returns Whether the relation exists.

std::size_t cubos::core::ecs::SparseRelationTable::row(uint32_t from, uint32_t to) const

Gets the row of the relation with the given indices, or size() if there is none.

Parameters
from From index.
to To index.
Returns Row of the data.

void* cubos::core::ecs::SparseRelationTable::at(std::size_t row)

Get the relation at the given row.

Parameters
row Row of the relation to get.
Returns Pointer to the relation.

const void* cubos::core::ecs::SparseRelationTable::at(std::size_t row) const

Get the relation at the given row.

Parameters
row Row of the relation to get.
Returns Pointer to the relation.

void cubos::core::ecs::SparseRelationTable::indices(std::size_t row, uint32_t& from, uint32_t& to) const

Get the entity indices at the given row.

Parameters
row Row to get.
from out From index.
to out To index.

uint32_t cubos::core::ecs::SparseRelationTable::from(std::size_t row) const

Get the 'from' entity index at the given row.

Parameters
row Row to get.
Returns From index.

uint32_t cubos::core::ecs::SparseRelationTable::to(std::size_t row) const

Get the 'to' entity index at the given row.

Parameters
row Row to get.
Returns From index.

std::size_t cubos::core::ecs::SparseRelationTable::firstFrom(uint32_t index) const

Gets the first row with the given from index, or size() if there is none.

Parameters
index From index.
Returns First row with the given from index.

std::size_t cubos::core::ecs::SparseRelationTable::firstTo(uint32_t index) const

Gets the first row with the given to index, or size() if there is none.

Parameters
index To index.
Returns First row with the given to index.

std::size_t cubos::core::ecs::SparseRelationTable::nextFrom(std::size_t row) const

Gets the next row with the same from index, or size() if there is none.

Parameters
row Row to get the next from.
Returns Next row with the same from index.

std::size_t cubos::core::ecs::SparseRelationTable::nextTo(std::size_t row) const

Gets the next row with the same to index, or size() if there is none.

Parameters
row Row to get the next to.
Returns Next row with the same to index.

Iterator cubos::core::ecs::SparseRelationTable::begin() const

Gets an iterator to the first relation of the table.

Returns Iterator.

Iterator cubos::core::ecs::SparseRelationTable::end() const

Gets an iterator which represents the end of the table.

Returns Iterator.

View cubos::core::ecs::SparseRelationTable::viewFrom(uint32_t from) const

Returns a view of the relations with the given from index.

Parameters
from From index.
Returns Relation view.

View cubos::core::ecs::SparseRelationTable::viewTo(uint32_t to) const

Returns a view of the relations with the given to index.

Parameters
to To index.
Returns Relation view.

std::size_t cubos::core::ecs::SparseRelationTable::size() const

Returns the number of relations on the table.

Returns Relation count.

bool cubos::core::ecs::SparseRelationTable::operator==(const Iterator& other) const

Compares two iterators.

Parameters
other Other iterator.
Returns Whether the iterators point to the same relation.

const Output& cubos::core::ecs::SparseRelationTable::operator*() const

Accesses the relation referenced by this iterator.

Returns Output.

const Output* cubos::core::ecs::SparseRelationTable::operator->() const

Accesses the relation referenced by this iterator.

Returns Output.

Iterator& cubos::core::ecs::SparseRelationTable::operator++()

Advances the iterator.

Returns Reference to this.

Iterator cubos::core::ecs::SparseRelationTable::begin() const

Gets an iterator to the first relation of the view.

Returns Iterator.

Iterator cubos::core::ecs::SparseRelationTable::end() const

Gets an iterator which represents the end of the view.

Returns Iterator.

bool cubos::core::ecs::SparseRelationTable::operator==(const Iterator& other) const

Compares two iterators.

Parameters
other Other iterator.
Returns Whether the iterators point to the same relation.

const Output& cubos::core::ecs::SparseRelationTable::operator*() const

Accesses the relation referenced by this iterator.

Returns Output.

const Output* cubos::core::ecs::SparseRelationTable::operator->() const

Accesses the relation referenced by this iterator.

Returns Output.

Iterator& cubos::core::ecs::SparseRelationTable::operator++()

Advances the iterator.

Returns Reference to this.