cubos::core::ecs::QueryTerm struct
#include <core/ecs/query/term.hpp>

Describes a term in a query.

Terms are the building blocks used to build queries. Each term adds some restriction to what the query will match. There are three kinds of terms:

  • Component terms, which allow filtering match entities by those which have or don't have a given component.
  • Relation terms, which allow filtering match entities by some relation between them.
  • Entity terms, which don't filter the results but allow accessing one of the matched entities.

Public types

struct Component
Stores component term data.
struct Entity
Stores entity term data.
struct Relation
Stores relation term data.

Public static functions

static auto makeEntity(int target) -> QueryTerm
Returns a new entity term for the given target.
static auto makeWithComponent(DataTypeId type, int target) -> QueryTerm
Returns a new component term for the given component and target.
static auto makeWithoutComponent(DataTypeId type, int target) -> QueryTerm
Returns a new negated component term for the given component and target.
static auto makeOptComponent(DataTypeId type, int target) -> QueryTerm
Returns a new optional component term for the given component and target.
static auto makeRelation(DataTypeId type, int fromTarget, int toTarget, Traversal traversal = Traversal::Random) -> QueryTerm
Returns a new relation term for the given relation and targets.
static auto resolve(const Types& types, const std::vector<QueryTerm>& baseTerms, std::vector<QueryTerm>& otherTerms) -> std::vector<QueryTerm>
Merges a vector of terms with another, joining pairs of them if possible.
static auto toString(const Types& types, const std::vector<QueryTerm>& terms) -> std::string
Gets a string representation of vector of query terms.

Public functions

auto isEntity() const -> bool
Checks if the term is an entity term.
auto isComponent(const Types& types) const -> bool
Checks if the term is a component term.
auto isRelation(const Types& types) const -> bool
Checks if the term is a relation term.
auto compare(const Types& types, const QueryTerm& other) const -> bool
Compares two terms.

Public variables

DataTypeId type
Type of the data matched by the term.
Entity entity
Entity term data.
Component component
Component term data.
Relation relation
Relation term data.

Function documentation

static QueryTerm cubos::core::ecs::QueryTerm::makeEntity(int target)

Returns a new entity term for the given target.

Parameters
target Index of the target which will be accessed.
Returns Entity term.

static QueryTerm cubos::core::ecs::QueryTerm::makeWithComponent(DataTypeId type, int target)

Returns a new component term for the given component and target.

Parameters
type Component type.
target Index of the target which must have the component.
Returns Component term.

static QueryTerm cubos::core::ecs::QueryTerm::makeWithoutComponent(DataTypeId type, int target)

Returns a new negated component term for the given component and target.

Parameters
type Component type.
target Index of the target which must not have the component.
Returns Component term.

static QueryTerm cubos::core::ecs::QueryTerm::makeOptComponent(DataTypeId type, int target)

Returns a new optional component term for the given component and target.

Parameters
type Component type.
target Index of the target which may have the component.
Returns Component term.

static QueryTerm cubos::core::ecs::QueryTerm::makeRelation(DataTypeId type, int fromTarget, int toTarget, Traversal traversal = Traversal::Random)

Returns a new relation term for the given relation and targets.

Parameters
type Relation type.
fromTarget Index of the target which must have the 'from' side of the relation.
toTarget Index of the target which must have the 'to' side of the relation.
traversal Traversal order for the relation.
Returns Relation term.

static std::vector<QueryTerm> cubos::core::ecs::QueryTerm::resolve(const Types& types, const std::vector<QueryTerm>& baseTerms, std::vector<QueryTerm>& otherTerms)

Merges a vector of terms with another, joining pairs of them if possible.

Parameters
types Type registry.
baseTerms Base vector of terms.
otherTerms in/out Vector of terms to merge into the base. Targets will be modified, if set to -1.
Returns Result of merging the two vectors.

This function is mainly used to merge terms specified manually for a query with terms obtained from its argument types. For example, if we have a query of the form Query<A&, A&>, we will obtain the terms makeWithComponent(A, -1) and makeWithComponent(A, -1). Those term would be passed into other. If we passed to base the terms makeWithComponent(A, 0) and makeWithComponent(A, 1), then, the base wouldn't be modified, and the other vector would have its targets updated so that it matches the base.

Any targets found set to -1 will be set to the current default target. The default target is initially 0, and always changes to the last seen non -1 target. If a relation term has one of the targets undefined, the default target is incremented.

Another example would be to have an empty base vector, and the query Query<A&, B&>. The other vector would be {makeWithComponent(A, -1), makeWithComponent(B, -1)}, and the returned vector would be {makeWithComponent(A, 0), makeWithComponent(B, 0)}.

static std::string cubos::core::ecs::QueryTerm::toString(const Types& types, const std::vector<QueryTerm>& terms)

Gets a string representation of vector of query terms.

Parameters
types Type registry.
terms Vector of terms.
Returns String representation.

bool cubos::core::ecs::QueryTerm::isEntity() const

Checks if the term is an entity term.

Returns Whether it's an entity term.

bool cubos::core::ecs::QueryTerm::isComponent(const Types& types) const

Checks if the term is a component term.

Parameters
types Types registry.
Returns Whether it's a component term.

bool cubos::core::ecs::QueryTerm::isRelation(const Types& types) const

Checks if the term is a relation term.

Parameters
types Types registry.
Returns Whether it's a relation term.

bool cubos::core::ecs::QueryTerm::compare(const Types& types, const QueryTerm& other) const

Compares two terms.

Parameters
types Types registry.
other Other term.
Returns Whether they're equal.

Variable documentation

DataTypeId cubos::core::ecs::QueryTerm::type

Type of the data matched by the term.

If this is set to DataTypeId::Invalid, then the term is an entity term. Otherwise, the term can either be a component or relation term depending on this type.