Class for iterating over query results. More...

#include <iter.hpp>

Public Member Functions
	iter (ecs_iter_t *it)
	Construct iterator from C iterator object.

row_iterator	begin () const
	Get an iterator to the beginning of the entity range.

row_iterator	end () const
	Get an iterator to the end of the entity range.

flecs::entity	system () const
	Get the system entity associated with the iterator.

flecs::entity	event () const
	Get the event entity associated with the iterator.

flecs::id	event_id () const
	Get the event ID associated with the iterator.

flecs::world	world () const
	Get the world associated with the iterator.

const flecs::iter_t *	c_ptr () const
	Get a pointer to the underlying C iterator object.

size_t	count () const
	Get the number of entities to iterate over.

ecs_ftime_t	delta_time () const
	Get the time elapsed since the last frame.

ecs_ftime_t	delta_system_time () const
	Get the time elapsed since the last system invocation.

flecs::type	type () const
	Get the type of the iterated table.

flecs::table	table () const
	Get the table for the current iterator result.

flecs::table	other_table () const
	Get the other table for the current iterator result.

flecs::table_range	range () const
	Get the table range for the current iterator result.

void *	ctx ()
	Access ctx.

template<typename T >
T *	ctx ()
	Access ctx.

void *	param ()
	Access param.

template<typename T >
T *	param ()
	Access param.

flecs::entity	entity (size_t row) const
	Obtain a mutable handle to the entity being iterated over.

bool	is_self (int8_t index) const
	Return whether the field is matched on self.

bool	is_set (int8_t index) const
	Return whether the field is set.

bool	is_readonly (int8_t index) const
	Return whether the field is readonly.

int32_t	field_count () const
	Number of fields in the iterator.

size_t	size (int8_t index) const
	Size of the field data type.

flecs::entity	src (int8_t index) const
	Obtain the field source (0 if This).

flecs::id	id (int8_t index) const
	Obtain the ID matched for the field.

flecs::id	pair (int8_t index) const
	Obtain the pair ID matched for the field.

int32_t	column_index (int8_t index) const
	Obtain the column index for the field.

int8_t	term_index () const
	Obtain the term that triggered an observer.

template<typename T , typename A = actual_type_t<T>, if_t< is_const_v< T > > = 0>
flecs::field< A >	field (int8_t index) const
	Get read-only access to field data.

template<typename T , typename A = actual_type_t<T>, if_not_t< is_const_v< T > > = 0>
flecs::field< A >	field (int8_t index) const
	Get read/write access to field data.

flecs::untyped_field	field (int8_t index) const
	Get unchecked access to field data.

void *	field_at (int8_t index, size_t row) const
	Get pointer to field at row.

template<typename T , typename A = actual_type_t<T>, if_t< is_const_v< T > > = 0>
const A &	field_at (int8_t index, size_t row) const
	Get const reference to field at row.

template<typename T , typename A = actual_type_t<T>, if_not_t< is_const_v< T > > = 0>
A &	field_at (int8_t index, size_t row) const
	Get mutable reference to field at row.

flecs::field< const flecs::entity_t >	entities () const
	Get read-only access to entity IDs.

bool	changed ()
	Check if the current table has changed since the last iteration.

void	skip ()
	Skip current table.

uint64_t	group_id () const
	Return the group ID for the current table (grouped queries only).

flecs::entity	get_var (int var_id) const
	Get value of variable by ID.

flecs::entity	get_var (const char *name) const
	Get value of variable by name.

bool	next ()
	Progress iterator.

void	each ()
	Forward to each().

template<typename Func >
void	targets (int8_t index, const Func &func)
	Iterate targets for pair field.

void	fini ()
	Free iterator resources.

flecs::string	to_json (flecs::iter_to_json_desc_t *desc=nullptr)
	Serialize an iterator result to JSON.

Detailed Description

Class for iterating over query results.

Definition at line 68 of file iter.hpp.

Constructor & Destructor Documentation

◆ iter()

flecs::iter::iter ( ecs_iter_t * it )

inline

Construct iterator from C iterator object.

This operation is typically not invoked directly by the user.

Parameters

it	Pointer to C iterator.

Definition at line 78 of file iter.hpp.

Member Function Documentation

◆ begin()

row_iterator flecs::iter::begin ( ) const

inline

Get an iterator to the beginning of the entity range.

Definition at line 81 of file iter.hpp.

◆ c_ptr()

const flecs::iter_t * flecs::iter::c_ptr ( ) const

inline

Get a pointer to the underlying C iterator object.

Definition at line 103 of file iter.hpp.

◆ changed()

bool flecs::iter::changed ( )

inline

Check if the current table has changed since the last iteration.

Can only be used when iterating queries and/or systems.

Returns: True if the table has changed.

Definition at line 384 of file iter.hpp.

◆ column_index()

int32_t flecs::iter::column_index ( int8_t index ) const

inline

Obtain the column index for the field.

Parameters

index The field index.

Returns: The column index for the field.

Definition at line 259 of file iter.hpp.

◆ count()

size_t flecs::iter::count ( ) const

inline

Get the number of entities to iterate over.

Returns: The number of entities in the current result.

Definition at line 111 of file iter.hpp.

◆ ctx() [1/2]

void * flecs::iter::ctx ( )

inline

Access ctx.

ctx contains the context pointer assigned to a system.

Definition at line 153 of file iter.hpp.

◆ ctx() [2/2]

template<typename T >

T * flecs::iter::ctx ( )

inline

Access ctx.

ctx contains the context pointer assigned to a system.

Definition at line 161 of file iter.hpp.

◆ delta_system_time()

ecs_ftime_t flecs::iter::delta_system_time ( ) const

inline

Get the time elapsed since the last system invocation.

Returns: The delta system time.

Definition at line 131 of file iter.hpp.

◆ delta_time()

ecs_ftime_t flecs::iter::delta_time ( ) const

inline

Get the time elapsed since the last frame.

Returns: The delta time.

Definition at line 123 of file iter.hpp.

◆ each()

void flecs::iter::each ( )

inline

Forward to each().

If a system has an each() callback registered, this operation will forward the current iterator to the each() callback.

Definition at line 450 of file iter.hpp.

◆ end()

row_iterator flecs::iter::end ( ) const

inline

Get an iterator to the end of the entity range.

Definition at line 86 of file iter.hpp.

◆ entities()

flecs::field< const flecs::entity_t > flecs::iter::entities ( ) const

inline

Get read-only access to entity IDs.

Returns: The entity IDs.

Definition at line 373 of file iter.hpp.

◆ entity()

flecs::entity flecs::iter::entity ( size_t row ) const

inline

Obtain a mutable handle to the entity being iterated over.

Get the entity for a given row.

Parameters

row	Row being iterated over.

Returns: The entity at the specified row.

Definition at line 32 of file iter.hpp.

◆ event()

flecs::entity flecs::iter::event ( ) const

inline

Get the event entity associated with the iterator.

Get the entity associated with the event that triggered the observer.

Definition at line 17 of file iter.hpp.

◆ event_id()

flecs::id flecs::iter::event_id ( ) const

inline

Get the event ID associated with the iterator.

Get the event ID (component or pair).

Definition at line 22 of file iter.hpp.

◆ field() [1/3]

template<typename T , typename A , if_not_t< is_const_v< T > > >

flecs::field< A > flecs::iter::field ( int8_t index ) const

inline

Get read-only access to field data.

Get field data for a mutable component type.

Get field data for a const component type.

If the specified field index does not match with the provided type, the function will assert.

This function should not be used in each() callbacks, unless it is to access a shared field. For access to non-shared fields in each(), use field_at().

Template Parameters

T	Type of the field.

Parameters

index The field index.

Returns: The field data.

Definition at line 80 of file iter.hpp.

◆ field() [2/3]

template<typename T , typename A = actual_type_t<T>, if_not_t< is_const_v< T > > = 0>

flecs::field< A > flecs::iter::field ( int8_t index ) const

Get read/write access to field data.

If the matched ID for the specified field does not match with the provided type or if the field is readonly, the function will assert.

This function should not be used in each() callbacks, unless it is to access a shared field. For access to non-shared fields in each(), use field_at().

Template Parameters

T	Type of the field.

Parameters

index The field index.

Returns: The field data.

◆ field() [3/3]

flecs::untyped_field flecs::iter::field ( int8_t index ) const

inline

Get unchecked access to field data.

Unchecked access is required when a system does not know the type of a field at compile time.

This function should not be used in each() callbacks, unless it is to access a shared field. For access to non-shared fields in each(), use field_at().

Parameters

index The field index.

Definition at line 311 of file iter.hpp.

◆ field_at() [1/3]

void * flecs::iter::field_at	(	int8_t	index,
		size_t	row ) const

inline

Get pointer to field at row.

This function may be used to access shared fields when row is set to 0.

Parameters

index	The field index.
row	The row index.

Returns: Pointer to the field value at the specified row.

Definition at line 325 of file iter.hpp.

◆ field_at() [2/3]

template<typename T , typename A = actual_type_t<T>, if_t< is_const_v< T > > = 0>

const A & flecs::iter::field_at	(	int8_t	index,
		size_t	row ) const

inline

Get const reference to field at row.

This function may be used to access shared fields when row is set to 0.

Template Parameters

T	Type of the field (must be const-qualified).

Parameters

index	The field index.
row	The row index.

Returns: Const reference to the field value at the specified row.

Definition at line 342 of file iter.hpp.

◆ field_at() [3/3]

template<typename T , typename A = actual_type_t<T>, if_not_t< is_const_v< T > > = 0>

A & flecs::iter::field_at	(	int8_t	index,
		size_t	row ) const

inline

Get mutable reference to field at row.

This function may be used to access shared fields when row is set to 0.

Template Parameters

T	Type of the field (must not be const-qualified).

Parameters

index	The field index.
row	The row index.

Returns: Mutable reference to the field value at the specified row.

Definition at line 359 of file iter.hpp.

◆ field_count()

int32_t flecs::iter::field_count ( ) const

inline

Number of fields in the iterator.

Returns: The number of fields.

Definition at line 219 of file iter.hpp.

◆ fini()

void flecs::iter::fini ( )

inline

Free iterator resources.

This operation only needs to be called when the iterator is not iterated until completion (e.g., the last call to next() did not return false).

Failing to call this operation on an unfinished iterator will throw a fatal LEAK_DETECTED error.

See also: ecs_iter_fini()

Definition at line 471 of file iter.hpp.

◆ get_var() [1/2]

flecs::entity flecs::iter::get_var ( const char * name ) const

inline

Get value of variable by name.

Get the value of a variable by name.

Get value of a query variable for current result.

Parameters

name	The variable name.

Returns: The variable value.

Get the value of a query variable for the current result.

Definition at line 110 of file iter.hpp.

◆ get_var() [2/2]

flecs::entity flecs::iter::get_var ( int var_id ) const

inline

Get value of variable by ID.

Get the value of a variable by ID.

Get value of a query variable for current result.

Parameters

var_id The variable ID.

Returns: The variable value.

Definition at line 102 of file iter.hpp.

◆ group_id()

uint64_t flecs::iter::group_id ( ) const

inline

Return the group ID for the current table (grouped queries only).

Returns: The group ID.

Definition at line 403 of file iter.hpp.

◆ id()

flecs::id flecs::iter::id ( int8_t index ) const

inline

Obtain the ID matched for the field.

Get the ID for a field.

Parameters

index The field index.

Returns: The ID matched for the field.

Definition at line 44 of file iter.hpp.

◆ is_readonly()

bool flecs::iter::is_readonly ( int8_t index ) const

inline

Return whether the field is readonly.

Parameters

index The field index.

Returns: True if the field is readonly, false if not.

Definition at line 211 of file iter.hpp.

◆ is_self()

bool flecs::iter::is_self ( int8_t index ) const

inline

Return whether the field is matched on self.

Parameters

index The field index.

Returns: True if the field is matched on self, false if not.

Definition at line 193 of file iter.hpp.

◆ is_set()

bool flecs::iter::is_set ( int8_t index ) const

inline

Return whether the field is set.

Parameters

index The field index.

Returns: True if the field is set, false if not.

Definition at line 202 of file iter.hpp.

◆ next()

bool flecs::iter::next ( )

inline

Progress iterator.

This operation should only be called from a context where the iterator is not being progressed automatically. An example of a valid context is inside of a run() callback. An example of an invalid context is inside of an each() callback.

Returns: True if there is more data to iterate, false if not.

Definition at line 434 of file iter.hpp.

◆ other_table()

flecs::table flecs::iter::other_table ( ) const

inline

Get the other table for the current iterator result.

Get the other table (used for on_add/on_remove observers).

This is used for move operations where data is moved from one table to another.

Definition at line 68 of file iter.hpp.

◆ pair()

flecs::id flecs::iter::pair ( int8_t index ) const

inline

Obtain the pair ID matched for the field.

Get the pair ID for a field.

This operation will fail if the ID is not a pair.

Parameters

index The field index.

Returns: The pair ID matched for the field.

Definition at line 49 of file iter.hpp.

◆ param() [1/2]

void * flecs::iter::param ( )

inline

Access param.

param contains the pointer passed to the param argument of system::run().

Definition at line 168 of file iter.hpp.

◆ param() [2/2]

template<typename T >

T * flecs::iter::param ( )

inline

Access param.

param contains the pointer passed to the param argument of system::run().

Definition at line 176 of file iter.hpp.

◆ range()

flecs::table_range flecs::iter::range ( ) const

inline

Get the table range for the current iterator result.

Get the table range for the current result.

Definition at line 73 of file iter.hpp.

◆ size()

size_t flecs::iter::size ( int8_t index ) const

inline

Size of the field data type.

Parameters

index The field index.

Returns: The size of the field data type.

Definition at line 228 of file iter.hpp.

◆ skip()

void flecs::iter::skip ( )

inline

Skip current table.

This indicates to the query that the data in the current table is not modified. By default, iterating a table with a query will mark the iterated components as dirty if they are annotated with InOut or Out.

When this operation is invoked, the components of the current table will not be marked dirty.

Definition at line 395 of file iter.hpp.

◆ src()

flecs::entity flecs::iter::src ( int8_t index ) const

inline

Obtain the field source (0 if This).

Get the source entity for a field.

Parameters

index The field index.

Returns: The source entity for the field.

Definition at line 39 of file iter.hpp.

◆ system()

flecs::entity flecs::iter::system ( ) const

inline

Get the system entity associated with the iterator.

Get the entity associated with the system currently being run.

Definition at line 12 of file iter.hpp.

◆ table()

flecs::table flecs::iter::table ( ) const

inline

Get the table for the current iterator result.

Get the current table.

Definition at line 63 of file iter.hpp.

◆ targets()

template<typename Func >

void flecs::iter::targets	(	int8_t	index,
		const Func &	func )

Iterate targets for pair field.

Iterate over targets for a field.

Parameters

index	The field index.
func	Callback invoked for each target.

Definition at line 121 of file iter.hpp.

◆ term_index()

int8_t flecs::iter::term_index ( ) const

inline

Obtain the term that triggered an observer.

Returns: The index of the term that triggered the observer.

Definition at line 267 of file iter.hpp.

◆ type()

flecs::type flecs::iter::type ( ) const

inline

Get the type of the iterated table.

Get the type of the current table.

Definition at line 58 of file iter.hpp.

◆ world()

flecs::world flecs::iter::world ( ) const

inline

Get the world associated with the iterator.

Get the iterator world.

Definition at line 27 of file iter.hpp.

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

include/flecs/addons/cpp/iter.hpp
include/flecs/addons/cpp/impl/iter.hpp
include/flecs/addons/cpp/mixins/json/iterable.inl

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ iter()

Member Function Documentation

◆ begin()

◆ c_ptr()

◆ changed()

◆ column_index()

◆ count()

◆ ctx() [1/2]

◆ ctx() [2/2]

◆ delta_system_time()

◆ delta_time()

◆ each()

◆ end()

◆ entities()

◆ entity()

◆ event()

◆ event_id()

◆ field() [1/3]

◆ field() [2/3]

◆ field() [3/3]

◆ field_at() [1/3]

◆ field_at() [2/3]

◆ field_at() [3/3]

◆ field_count()

◆ fini()

◆ get_var() [1/2]

◆ get_var() [2/2]

◆ group_id()

◆ id()

◆ is_readonly()

◆ is_self()

◆ is_set()

◆ next()

◆ other_table()

◆ pair()

◆ param() [1/2]

◆ param() [2/2]

◆ range()

◆ size()

◆ skip()

◆ src()

◆ system()

◆ table()

◆ targets()

◆ term_index()

◆ type()

◆ world()