Query builder interface. More...

#include <builder_i.hpp>

Inheritance diagram for flecs::query_builder_i< Base, Components >:

Public Member Functions
	query_builder_i (ecs_query_desc_t *desc, int32_t term_index=0)
	Construct from a query descriptor.

Base &	query_flags (ecs_flags32_t flags)
	Set the query flags.

Base &	cache_kind (query_cache_kind_t kind)
	Set the cache kind for the query.

Base &	cached ()
	Enable auto-caching for the query.

Base &	detect_changes ()
	Enable change detection for the query.

Base &	expr (const char *expr)
	Set the query expression string.

Base &	scope_open ()
	Open a query scope.

Base &	scope_close ()
	Close a query scope.

Base &	term ()
	Set the current term to the next one in the term list.

template<typename T >
Base &	term_at ()
	Set the current term to the one with the provided type.

Base &	term_at (int32_t term_index)
	Set the current term to the one at the provided index.

template<typename T >
Base &	term_at (int32_t term_index)
	Set the current term to the one at the provided index and assert 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 the group_by() function.

Base &	on_group_create (ecs_group_create_action_t action)
	Specify the on_group_create() action.

Base &	on_group_delete (ecs_group_delete_action_t action)
	Specify the on_group_delete() action.

With methods
template<typename T >
Base &	with ()
	Add a term for the specified type.

Base &	with (id_t component_id)
	Add a term for the specified component ID.

Base &	with (const char *component_name)
	Add a term for the specified component name.

Base &	with (const char first, const char second)
	Add a term for a pair specified by name.

Base &	with (entity_t first, entity_t second)
	Add a term for a pair specified by entity IDs.

Base &	with (entity_t first, const char *second)
	Add a term for a pair with an entity ID first and a name second.

Base &	with (const char *first, entity_t second)
	Add a term for a pair with a name first and an entity ID second.

template<typename First >
Base &	with (entity_t second)
	Add a term for a pair with type First and an entity ID second.

template<typename First >
Base &	with (const char *second)
	Add a term for a pair with type First and name second.

template<typename First , typename Second >
Base &	with ()
	Add a term for a pair with types First and Second.

template<typename E , if_t< is_enum< E >::value > = 0>
Base &	with (E value)
	Add a term for an enum value.

Base &	with (flecs::term &term)
	Add a term from an existing term reference.

Base &	with (flecs::term &&term)
	Add a term from an existing term (move).

Without methods
Shorthand for .with(...).not_().
template<typename ... Args>
Base &	without (Args &&... args)
	Add a negated term.

template<typename T , typename ... Args>
Base &	without (Args &&... args)
	Add a negated term for the specified type.

template<typename First , typename Second >
Base &	without ()
	Add a negated term for a pair of types.

Write/read methods
Base &	write ()
	Short for inout_stage(flecs::Out).

template<typename ... Args>
Base &	write (Args &&... args)
	Add a write term with the specified arguments.

template<typename T , typename ... Args>
Base &	write (Args &&... args)
	Add a write term for the specified type.

template<typename First , typename Second >
Base &	write ()
	Add a write term for a pair of types.

Base &	read ()
	Short for inout_stage(flecs::In).

template<typename ... Args>
Base &	read (Args &&... args)
	Add a read term with the specified arguments.

template<typename T , typename ... Args>
Base &	read (Args &&... args)
	Add a read term for the specified type.

template<typename First , typename Second >
Base &	read ()
	Add a read term for a pair of types.

Public Member Functions inherited from flecs::term_builder_i< Base >
	term_builder_i ()
	Default constructor.

	term_builder_i (ecs_term_t *term_ptr)
	Construct from a term pointer.

Base &	term (id_t id)
	Set the term ID.

Base &	src ()
	Call prior to setting values for the src identifier.

Base &	first ()
	Call prior to setting values for the first identifier.

Base &	second ()
	Call prior to setting values for the second identifier.

Base &	src (flecs::entity_t id)
	Select the src identifier, initialize it with an entity ID.

template<typename T >
Base &	src ()
	Select the src identifier, initialize it with the ID associated with the type.

Base &	src (const char *name)
	Select the src identifier, initialize it with a name.

Base &	first (flecs::entity_t id)
	Select the first identifier, initialize it with an entity ID.

template<typename T >
Base &	first ()
	Select the first identifier, initialize it with the ID associated with the type.

Base &	first (const char *name)
	Select the first identifier, initialize it with a name.

Base &	second (flecs::entity_t id)
	Select the second identifier, initialize it with an entity ID.

template<typename T >
Base &	second ()
	Select the second identifier, initialize it with the ID associated with the type.

Base &	second (const char *name)
	Select the second identifier, initialize it with a name.

Base &	up (flecs::entity_t trav=0)
	The up flag indicates that the term identifier may be substituted by traversing a relationship upwards.

template<typename Trav >
Base &	up ()
	Traverse upwards using the specified relationship type.

Base &	cascade (flecs::entity_t trav=0)
	The cascade flag is like up(), but returns results in breadth-first order.

template<typename Trav >
Base &	cascade ()
	Cascade using the specified relationship type.

Base &	desc ()
	Use with cascade() to iterate results in descending (bottom-to-top) order.

Base &	parent ()
	Same as up().

Base &	trav (flecs::entity_t trav, flecs::flags32_t flags=0)
	Specify the relationship to traverse, and flags to indicate direction.

Base &	id_flags (id_t flags)
	Set ID flags for the term.

Base &	inout (flecs::inout_kind_t inout)
	Set read/write access of the term.

Base &	inout_stage (flecs::inout_kind_t inout)
	Set read/write access for a 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::InOutNone).

Base &	oper (flecs::oper_kind_t oper)
	Set the operator of the term.

Base &	and_ ()
	Short for oper(flecs::And).

Base &	or_ ()
	Short for oper(flecs::Or).

Base &	not_ ()
	Short for oper(flecs::Not).

Base &	optional ()
	Short for oper(flecs::Optional).

Base &	and_from ()
	Short for oper(flecs::AndFrom).

Base &	or_from ()
	Short for oper(flecs::OrFrom).

Base &	not_from ()
	Short for oper(flecs::NotFrom).

Base &	filter ()
	Mark the term as a filter.

Public Member Functions inherited from flecs::term_ref_builder_i< Base >
	term_ref_builder_i ()
	Default constructor.

virtual	~term_ref_builder_i ()
	Destructor.

Base &	self ()
	The self flag indicates that the term identifier itself is used.

Base &	id (flecs::entity_t id)
	Specify the value of the identifier by ID.

Base &	entity (flecs::entity_t entity)
	Specify the value of the identifier by ID.

Base &	name (const char *name)
	Specify the value of the identifier by name.

Base &	var (const char *var_name)
	Specify that the identifier is a variable (resolved at query evaluation time).

Base &	flags (flecs::flags64_t flags)
	Override the term ID 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)
	Set the current term pointer.

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_
	Pointer to the current term.

Public Attributes inherited from flecs::term_ref_builder_i< Base >
ecs_term_ref_t *	term_ref_
	Pointer to the current term reference.

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

Construct from a query descriptor.

Definition at line 20 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

Set the cache kind for the query.

Definition at line 32 of file builder_i.hpp.

◆ cached()

template<typename Base , typename ... Components>

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

inline

Enable auto-caching for the query.

Definition at line 38 of file builder_i.hpp.

◆ detect_changes()

template<typename Base , typename ... Components>

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

inline

Enable change detection for the query.

Definition at line 43 of file builder_i.hpp.

◆ expr()

template<typename Base , typename ... Components>

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

inline

Set the query expression string.

Definition at line 49 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 the default group_by() action.

Template Parameters

T	The component used to determine the group rank.

Definition at line 392 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 the default group_by() action.

Parameters

component The component used to determine the group rank.

Definition at line 401 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()(flecs::world_t , flecs::table_t table, flecs::id_t id, void ctx)	group_by_action )

inline

Group and sort matched tables.

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

Parameters

component	The component used to determine the group rank.
group_by_action	Callback that determines the group ID for a table.

Definition at line 380 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(*)(flecs::world_t *, flecs::table_t *table, flecs::id_t id, void *ctx) group_by_action )

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 if 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 the group ID for a table.

Definition at line 369 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 the group_by() function.

Parameters

ctx	Context to pass to the group_by() function.
ctx_free	Function to clean up context (called when the query is deleted).

Definition at line 410 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 the on_group_create() action.

Definition at line 417 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 the on_group_delete() action.

Definition at line 423 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()(flecs::entity_t, const void , flecs::entity_t, const void *)	compare )

inline

Sort the output of a query.

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

Parameters

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

Definition at line 345 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(*)(flecs::entity_t, const T *, flecs::entity_t, const T *) compare )

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 334 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

Set the query flags.

Definition at line 26 of file builder_i.hpp.

◆ read() [1/4]

template<typename Base , typename ... Components>

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

inline

Short for inout_stage(flecs::In).

Definition at line 209 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

Add a read term for a pair of types.

Definition at line 228 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

Add a read term with the specified arguments.

Definition at line 216 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

Add a read term for the specified type.

Definition at line 222 of file builder_i.hpp.

◆ scope_close()

template<typename Base , typename ... Components>

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

inline

Close a query scope.

Definition at line 240 of file builder_i.hpp.

◆ scope_open()

template<typename Base , typename ... Components>

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

inline

Open a query scope.

Definition at line 235 of file builder_i.hpp.

◆ term()

template<typename Base , typename ... Components>

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

inline

Set the current term to the next one in the term list.

Definition at line 245 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

Set 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 268 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

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

Definition at line 286 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

Set the current term to the one at the provided index and assert that the type matches.

Definition at line 300 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

Add a term for the specified type.

Definition at line 65 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

Add a term for a pair with types First and Second.

Definition at line 129 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

Add a term for the specified component name.

Definition at line 81 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

Add a term for a pair specified by name.

Definition at line 88 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

Add a term for a pair with a name first and an entity ID second.

Definition at line 109 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

Add a term for a pair with type First and name second.

Definition at line 123 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

Add a term for an enum value.

Definition at line 135 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

Add a term for a pair with an entity ID first and a name second.

Definition at line 102 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

Add a term for a pair specified by entity IDs.

Definition at line 95 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

Add a term for a pair with type First and an entity ID second.

Definition at line 117 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

Add a term from an existing term (move).

Definition at line 149 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

Add a term from an existing term reference.

Definition at line 142 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

Add a term for the specified component ID.

Definition at line 74 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

Add a negated term for a pair of types.

Definition at line 175 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

Add a negated term.

Definition at line 163 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

Add a negated term for the specified type.

Definition at line 169 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

Short for inout_stage(flecs::Out).

Definition at line 185 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

Add a write term for a pair of types.

Definition at line 204 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

Add a write term with the specified arguments.

Definition at line 192 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

Add a write term for the specified type.

Definition at line 198 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 431 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 430 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

Public Member Functions

Protected Member Functions

Protected Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ query_builder_i()

Member Function Documentation

◆ cache_kind()

◆ cached()

◆ detect_changes()

◆ expr()

◆ group_by() [1/4]

◆ group_by() [2/4]

◆ group_by() [3/4]

◆ group_by() [4/4]

◆ group_by_ctx()

◆ on_group_create()

◆ on_group_delete()

◆ order_by() [1/2]

◆ order_by() [2/2]

◆ query_flags()

◆ read() [1/4]

◆ read() [2/4]

◆ read() [3/4]

◆ read() [4/4]

◆ scope_close()

◆ scope_open()

◆ term()

◆ term_at() [1/3]

◆ term_at() [2/3]

◆ term_at() [3/3]

◆ with() [1/13]

◆ with() [2/13]

◆ with() [3/13]

◆ with() [4/13]

◆ with() [5/13]

◆ with() [6/13]

◆ with() [7/13]

◆ with() [8/13]

◆ with() [9/13]

◆ with() [10/13]

◆ with() [11/13]

◆ with() [12/13]

◆ with() [13/13]

◆ without() [1/3]

◆ without() [2/3]

◆ without() [3/3]

◆ world_v()

◆ write() [1/4]

◆ write() [2/4]

◆ write() [3/4]

◆ write() [4/4]

Member Data Documentation

◆ expr_count_

◆ term_index_