Flecs: flecs::query_builder_i< Base, Components > Struct Template Reference
Description: A fast entity component system (ECS) for C & C++

| Flecs v4.0 A fast entity component system (ECS) for C & C++

Loading...
Searching...
No Matches
flecs::query_builder_i< Base, Components > Struct Template Referenceabstract
C++ API » Core » Queries

Query builder interface. More...

`#include <builder_i.hpp>`

Inheritance diagram for flecs::query_builder_i< Base, Components >:
[legend]

## Public Member Functions
| query_builder_i (ecs_query_desc_t *desc, int32_t term_index=0)
Base & | query_flags (ecs_flags32_t flags)
Base & | cache_kind (query_cache_kind_t kind)
Base & | cached ()
Base & | detect_changes ()
Base & | expr (const char *expr)
template<typename T>
Base & | with ()
Base & | with (id_t component_id)
Base & | with (const char *component_name)
Base & | with (const char *first, const char *second)
Base & | with (entity_t first, entity_t second)
Base & | with (entity_t first, const char *second)
Base & | with (const char *first, entity_t second)
template<typename First>
Base & | with (entity_t second)
template<typename First>
Base & | with (const char *second)
template<typename First, typename Second>
Base & | with ()
template<typename E, if_t< is_enum< E >::value > = 0>
Base & | with (E value)
Base & | with (flecs::term &term)
Base & | with (flecs::term &&term)
template<typename ... Args>
Base & | without (Args &&... args)
template<typename T, typename ... Args>
Base & | without (Args &&... args)
template<typename First, typename Second>
Base & | without ()
Base & | write ()
template<typename ... Args>
Base & | write (Args &&... args)
template<typename T, typename ... Args>
Base & | write (Args &&... args)
template<typename First, typename Second>
Base & | write ()
Base & | read ()
template<typename ... Args>
Base & | read (Args &&... args)
template<typename T, typename ... Args>
Base & | read (Args &&... args)
template<typename First, typename Second>
Base & | read ()
Base & | scope_open ()
Base & | scope_close ()
Base & | term ()
| Sets the current term to next one in term list.
template<typename T>
Base & | term_at ()
| Sets the current term to the one with the provided type.
Base & | term_at (int32_t term_index)
| Sets the current term to the one at the provided index.
template<typename T>
Base & | term_at (int32_t term_index)
| Sets the current term to the one at the provided index and asserts that the type matches.
template<typename T>
Base & | order_by (int(*compare)(flecs::entity_t, const T *, flecs::entity_t, const T *))
| Sort the output of a query.
Base & | order_by (flecs::entity_t component, int(*compare)(flecs::entity_t, const void *, flecs::entity_t, const void *))
| Sort the output of a query.
template<typename T>
Base & | group_by (uint64_t(*group_by_action)(flecs::world_t *, flecs::table_t *table, flecs::id_t id, void *ctx))
| Group and sort matched tables.
Base & | group_by (flecs::entity_t component, uint64_t(*group_by_action)(flecs::world_t *, flecs::table_t *table, flecs::id_t id, void *ctx))
| Group and sort matched tables.
template<typename T>
Base & | group_by ()
| Group and sort matched tables.
Base & | group_by (flecs::entity_t component)
| Group and sort matched tables.
Base & | group_by_ctx (void *ctx, ecs_ctx_free_t ctx_free=nullptr)
| Specify context to be passed to group_by function.
Base & | on_group_create (ecs_group_create_action_t action)
| Specify on_group_create action.
Base & | on_group_delete (ecs_group_delete_action_t action)
| Specify on_group_delete action.
Public Member Functions inherited from flecs::term_builder_i< Base >
| term_builder_i (ecs_term_t *term_ptr)
Base & | term (id_t id)
Base & | src ()
Base & | first ()
Base & | second ()
Base & | src (flecs::entity_t id)
template<typename T>
Base & | src ()
Base & | src (const char *name)
Base & | first (flecs::entity_t id)
template<typename T>
Base & | first ()
Base & | first (const char *name)
Base & | second (flecs::entity_t id)
template<typename T>
Base & | second ()
Base & | second (const char *name)
Base & | up (flecs::entity_t trav=0)
template<typename Trav>
Base & | up ()
Base & | cascade (flecs::entity_t trav=0)
template<typename Trav>
Base & | cascade ()
Base & | desc ()
Base & | parent ()
Base & | trav (flecs::entity_t trav, flecs::flags32_t flags=0)
Base & | id_flags (id_t flags)
| Set id flags for term.
Base & | inout (flecs::inout_kind_t inout)
| Set read/write access of term.
Base & | inout_stage (flecs::inout_kind_t inout)
| Set read/write access for stage.
Base & | write ()
| Short for inout_stage(flecs::Out).
Base & | read ()
| Short for inout_stage(flecs::In).
Base & | read_write ()
| Short for inout_stage(flecs::InOut).
Base & | in ()
| Short for inout(flecs::In)
Base & | out ()
| Short for inout(flecs::Out)
Base & | inout ()
| Short for inout(flecs::InOut)
Base & | inout_none ()
| Short for inout(flecs::In)
Base & | oper (flecs::oper_kind_t oper)
| Set operator of term.
Base & | and_ ()
Base & | or_ ()
Base & | not_ ()
Base & | optional ()
Base & | and_from ()
Base & | or_from ()
Base & | not_from ()
Base & | filter ()
Public Member Functions inherited from flecs::term_ref_builder_i< Base >
Base & | self ()
Base & | id (flecs::entity_t id)
Base & | entity (flecs::entity_t entity)
Base & | name (const char *name)
Base & | var (const char *var_name)
Base & | flags (flecs::flags64_t flags)

## Protected Member Functions
virtual flecs::world_t * | world_v () override=0
Protected Member Functions inherited from flecs::term_builder_i< Base >
void | set_term (ecs_term_t *term)
Protected Member Functions inherited from flecs::term_ref_builder_i< Base >
void | assert_term_ref ()

## Protected Attributes
int32_t | term_index_
int32_t | expr_count_

## Additional Inherited Members
Public Attributes inherited from flecs::term_builder_i< Base >
ecs_term_t * | term_
Public Attributes inherited from flecs::term_ref_builder_i< Base >
ecs_term_ref_t * | term_ref_

## Detailed Description

template<typename Base, typename ... Components>
struct flecs::query_builder_i< Base, Components >

Query builder interface.

Definition at line 18 of file builder_i.hpp.

## Constructor & Destructor Documentation

## ◆ query_builder_i()

template<typename Base, typename ... Components>

flecs::query_builder_i< Base, Components >::query_builder_i | ( | ecs_query_desc_t * | desc,
|  | int32_t | term_index = 0 )
| inline

Definition at line 19 of file builder_i.hpp.

## Member Function Documentation

## ◆ cache_kind()

template<typename Base, typename ... Components>

Base & flecs::query_builder_i< Base, Components >::cache_kind | ( | query_cache_kind_t | kind | ) |
| inline

Definition at line 29 of file builder_i.hpp.

## ◆ cached()

template<typename Base, typename ... Components>

Base & flecs::query_builder_i< Base, Components >::cached | ( |  | ) |
| inline

Definition at line 34 of file builder_i.hpp.

## ◆ detect_changes()

template<typename Base, typename ... Components>

Base & flecs::query_builder_i< Base, Components >::detect_changes | ( |  | ) |
| inline

Definition at line 38 of file builder_i.hpp.

## ◆ expr()

template<typename Base, typename ... Components>

Base & flecs::query_builder_i< Base, Components >::expr | ( | const char * | expr | ) |
| inline

Definition at line 43 of file builder_i.hpp.

## ◆ group_by() [1/4]

template<typename Base, typename ... Components>
template<typename T>

Base & flecs::query_builder_i< Base, Components >::group_by | ( |  | ) |
| inline

Group and sort matched tables.

Same as group_by<T>, but with default group_by action.

Template Parameters

  T | The component used to determine the group rank.

Definition at line 354 of file builder_i.hpp.

## ◆ group_by() [2/4]

template<typename Base, typename ... Components>

Base & flecs::query_builder_i< Base, Components >::group_by | ( | flecs::entity_t | component | ) |
| inline

Group and sort matched tables.

Same as group_by, but with default group_by action.

Parameters

  component | The component used to determine the group rank.

Definition at line 363 of file builder_i.hpp.

## ◆ group_by() [3/4]

template<typename Base, typename ... Components>

Base & flecs::query_builder_i< Base, Components >::group_by | ( | flecs::entity_t | component,
|  | uint64_t(* | group_by_action )(flecs::world_t *, flecs::table_t *table, flecs::id_t id, void *ctx) )
| inline

Group and sort matched tables.

Same as group_by<T>, but with component identifier.

Parameters

  component | The component used to determine the group rank.
  group_by_action | Callback that determines group id for table.

Definition at line 342 of file builder_i.hpp.

## ◆ group_by() [4/4]

template<typename Base, typename ... Components>
template<typename T>

Base & flecs::query_builder_i< Base, Components >::group_by | ( | uint64_t(* | group_by_action )(flecs::world_t *, flecs::table_t *table, flecs::id_t id, void *ctx) | ) |
| inline

Group and sort matched tables.

Similar to ecs_query_order_by(), but instead of sorting individual entities, this operation only sorts matched tables. This can be useful of a query needs to enforce a certain iteration order upon the tables it is iterating, for example by giving a certain component or tag a higher priority.

The sorting function assigns a "rank" to each type, which is then used to sort the tables. Tables with higher ranks will appear later in the iteration.

Resorting happens when a query iterator is obtained, and only if the set of matched tables for a query has changed. If table sorting is enabled together with entity sorting, table sorting takes precedence, and entities will be sorted within each set of tables that are assigned the same rank.

Template Parameters

  T | The component used to determine the group rank.

Parameters

  group_by_action | Callback that determines group id for table.

Definition at line 331 of file builder_i.hpp.

## ◆ group_by_ctx()

template<typename Base, typename ... Components>

Base & flecs::query_builder_i< Base, Components >::group_by_ctx | ( | void * | ctx,
|  | ecs_ctx_free_t | ctx_free = nullptr )
| inline

Specify context to be passed to group_by function.

Parameters

  ctx | Context to pass to group_by function.
  ctx_free | Function to cleanup context (called when query is deleted).

Definition at line 372 of file builder_i.hpp.

## ◆ on_group_create()

template<typename Base, typename ... Components>

Base & flecs::query_builder_i< Base, Components >::on_group_create | ( | ecs_group_create_action_t | action | ) |
| inline

Specify on_group_create action.

Definition at line 380 of file builder_i.hpp.

## ◆ on_group_delete()

template<typename Base, typename ... Components>

Base & flecs::query_builder_i< Base, Components >::on_group_delete | ( | ecs_group_delete_action_t | action | ) |
| inline

Specify on_group_delete action.

Definition at line 387 of file builder_i.hpp.

## ◆ order_by() [1/2]

template<typename Base, typename ... Components>

Base & flecs::query_builder_i< Base, Components >::order_by | ( | flecs::entity_t | component,
|  | int(* | compare )(flecs::entity_t, const void *, flecs::entity_t, const void *) )
| inline

Sort the output of a query.

Same as order_by<T>, but with component identifier.

Parameters

  component | The component used to sort.
  compare | The compare function used to sort the components.

Definition at line 307 of file builder_i.hpp.

## ◆ order_by() [2/2]

template<typename Base, typename ... Components>
template<typename T>

Base & flecs::query_builder_i< Base, Components >::order_by | ( | int(* | compare )(flecs::entity_t, const T *, flecs::entity_t, const T *) | ) |
| inline

Sort the output of a query.

This enables sorting of entities across matched tables. As a result of this operation, the order of entities in the matched tables may be changed. Resorting happens when a query iterator is obtained, and only if the table data has changed.

If multiple queries that match the same (down)set of tables specify different sorting functions, resorting is likely to happen every time an iterator is obtained, which can significantly slow down iterations.

The sorting function will be applied to the specified component. Resorting only happens if that component has changed, or when the entity order in the table has changed. If no component is provided, resorting only happens when the entity order changes.

Template Parameters

  T | The component used to sort.

Parameters

  compare | The compare function used to sort the components.

Definition at line 296 of file builder_i.hpp.

## ◆ query_flags()

template<typename Base, typename ... Components>

Base & flecs::query_builder_i< Base, Components >::query_flags | ( | ecs_flags32_t | flags | ) |
| inline

Definition at line 24 of file builder_i.hpp.

## ◆ read() [1/4]

template<typename Base, typename ... Components>

Base & flecs::query_builder_i< Base, Components >::read | ( |  | ) |
| inline

Definition at line 173 of file builder_i.hpp.

## ◆ read() [2/4]

template<typename Base, typename ... Components>
template<typename First, typename Second>

Base & flecs::query_builder_i< Base, Components >::read | ( |  | ) |
| inline

Definition at line 189 of file builder_i.hpp.

## ◆ read() [3/4]

template<typename Base, typename ... Components>
template<typename ... Args>

Base & flecs::query_builder_i< Base, Components >::read | ( | Args &&... | args | ) |
| inline

Definition at line 179 of file builder_i.hpp.

## ◆ read() [4/4]

template<typename Base, typename ... Components>
template<typename T, typename ... Args>

Base & flecs::query_builder_i< Base, Components >::read | ( | Args &&... | args | ) |
| inline

Definition at line 184 of file builder_i.hpp.

## ◆ scope_close()

template<typename Base, typename ... Components>

Base & flecs::query_builder_i< Base, Components >::scope_close | ( |  | ) |
| inline

Definition at line 198 of file builder_i.hpp.

## ◆ scope_open()

template<typename Base, typename ... Components>

Base & flecs::query_builder_i< Base, Components >::scope_open | ( |  | ) |
| inline

Definition at line 194 of file builder_i.hpp.

## ◆ term()

template<typename Base, typename ... Components>

Base & flecs::query_builder_i< Base, Components >::term | ( |  | ) |
| inline

Sets the current term to next one in term list.

Definition at line 206 of file builder_i.hpp.

## ◆ term_at() [1/3]

template<typename Base, typename ... Components>
template<typename T>

Base & flecs::query_builder_i< Base, Components >::term_at | ( |  | ) |
| inline

Sets the current term to the one with the provided type.

This loops over all terms to find the one with the provided type. For performance-critical paths, use term_at(int32_t) instead.

Definition at line 229 of file builder_i.hpp.

## ◆ term_at() [2/3]

template<typename Base, typename ... Components>

Base & flecs::query_builder_i< Base, Components >::term_at | ( | int32_t | term_index | ) |
| inline

Sets the current term to the one at the provided index.

Definition at line 248 of file builder_i.hpp.

## ◆ term_at() [3/3]

template<typename Base, typename ... Components>
template<typename T>

Base & flecs::query_builder_i< Base, Components >::term_at | ( | int32_t | term_index | ) |
| inline

Sets the current term to the one at the provided index and asserts that the type matches.

Definition at line 262 of file builder_i.hpp.

## ◆ with() [1/13]

template<typename Base, typename ... Components>
template<typename T>

Base & flecs::query_builder_i< Base, Components >::with | ( |  | ) |
| inline

Definition at line 56 of file builder_i.hpp.

## ◆ with() [2/13]

template<typename Base, typename ... Components>
template<typename First, typename Second>

Base & flecs::query_builder_i< Base, Components >::with | ( |  | ) |
| inline

Definition at line 111 of file builder_i.hpp.

## ◆ with() [3/13]

template<typename Base, typename ... Components>

Base & flecs::query_builder_i< Base, Components >::with | ( | const char * | component_name | ) |
| inline

Definition at line 70 of file builder_i.hpp.

## ◆ with() [4/13]

template<typename Base, typename ... Components>

Base & flecs::query_builder_i< Base, Components >::with | ( | const char * | first,
|  | const char * | second )
| inline

Definition at line 76 of file builder_i.hpp.

## ◆ with() [5/13]

template<typename Base, typename ... Components>

Base & flecs::query_builder_i< Base, Components >::with | ( | const char * | first,
|  | entity_t | second )
| inline

Definition at line 94 of file builder_i.hpp.

## ◆ with() [6/13]

template<typename Base, typename ... Components>
template<typename First>

Base & flecs::query_builder_i< Base, Components >::with | ( | const char * | second | ) |
| inline

Definition at line 106 of file builder_i.hpp.

## ◆ with() [7/13]

template<typename Base, typename ... Components>
template<typename E, if_t< is_enum< E >::value > = 0>

Base & flecs::query_builder_i< Base, Components >::with | ( | E | value | ) |
| inline

Definition at line 116 of file builder_i.hpp.

## ◆ with() [8/13]

template<typename Base, typename ... Components>

Base & flecs::query_builder_i< Base, Components >::with | ( | entity_t | first,
|  | const char * | second )
| inline

Definition at line 88 of file builder_i.hpp.

## ◆ with() [9/13]

template<typename Base, typename ... Components>

Base & flecs::query_builder_i< Base, Components >::with | ( | entity_t | first,
|  | entity_t | second )
| inline

Definition at line 82 of file builder_i.hpp.

## ◆ with() [10/13]

template<typename Base, typename ... Components>
template<typename First>

Base & flecs::query_builder_i< Base, Components >::with | ( | entity_t | second | ) |
| inline

Definition at line 101 of file builder_i.hpp.

## ◆ with() [11/13]

template<typename Base, typename ... Components>

Base & flecs::query_builder_i< Base, Components >::with | ( | flecs::term && | term | ) |
| inline

Definition at line 128 of file builder_i.hpp.

## ◆ with() [12/13]

template<typename Base, typename ... Components>

Base & flecs::query_builder_i< Base, Components >::with | ( | flecs::term & | term | ) |
| inline

Definition at line 122 of file builder_i.hpp.

## ◆ with() [13/13]

template<typename Base, typename ... Components>

Base & flecs::query_builder_i< Base, Components >::with | ( | id_t | component_id | ) |
| inline

Definition at line 64 of file builder_i.hpp.

## ◆ without() [1/3]

template<typename Base, typename ... Components>
template<typename First, typename Second>

Base & flecs::query_builder_i< Base, Components >::without | ( |  | ) |
| inline

Definition at line 147 of file builder_i.hpp.

## ◆ without() [2/3]

template<typename Base, typename ... Components>
template<typename ... Args>

Base & flecs::query_builder_i< Base, Components >::without | ( | Args &&... | args | ) |
| inline

Definition at line 137 of file builder_i.hpp.

## ◆ without() [3/3]

template<typename Base, typename ... Components>
template<typename T, typename ... Args>

Base & flecs::query_builder_i< Base, Components >::without | ( | Args &&... | args | ) |
| inline

Definition at line 142 of file builder_i.hpp.

## ◆ world_v()

template<typename Base, typename ... Components>

virtual flecs::world_t * flecs::query_builder_i< Base, Components >::world_v | ( |  | ) |
| overrideprotectedpure virtual

Implements flecs::term_builder_i< Base >.

## ◆ write() [1/4]

template<typename Base, typename ... Components>

Base & flecs::query_builder_i< Base, Components >::write | ( |  | ) |
| inline

Definition at line 153 of file builder_i.hpp.

## ◆ write() [2/4]

template<typename Base, typename ... Components>
template<typename First, typename Second>

Base & flecs::query_builder_i< Base, Components >::write | ( |  | ) |
| inline

Definition at line 169 of file builder_i.hpp.

## ◆ write() [3/4]

template<typename Base, typename ... Components>
template<typename ... Args>

Base & flecs::query_builder_i< Base, Components >::write | ( | Args &&... | args | ) |
| inline

Definition at line 159 of file builder_i.hpp.

## ◆ write() [4/4]

template<typename Base, typename ... Components>
template<typename T, typename ... Args>

Base & flecs::query_builder_i< Base, Components >::write | ( | Args &&... | args | ) |
| inline

Definition at line 164 of file builder_i.hpp.

## Member Data Documentation

## ◆ expr_count_

template<typename Base, typename ... Components>

int32_t flecs::query_builder_i< Base, Components >::expr_count_
| protected

Definition at line 395 of file builder_i.hpp.

## ◆ term_index_

template<typename Base, typename ... Components>

int32_t flecs::query_builder_i< Base, Components >::term_index_
| protected

Definition at line 394 of file builder_i.hpp.

The documentation for this struct was generated from the following file:

- include/flecs/addons/cpp/mixins/query/builder_i.hpp