Flecs v4.1
A fast entity component system (ECS) for C & C++
Loading...
Searching...
No Matches
flecs::iter Struct Reference

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_tc_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.
 
flecs::string str () const
 Convert current iterator result to string.
 
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_tentities () 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
itPointer 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 392 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
indexThe 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 455 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 382 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
rowRow 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
TType of the field.
Parameters
indexThe 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
TType of the field.
Parameters
indexThe 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
indexThe field index.

Definition at line 320 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
indexThe field index.
rowThe row index.
Returns
Pointer to the field value at the specified row.

Definition at line 334 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
TType of the field (must be const-qualified).
Parameters
indexThe field index.
rowThe row index.
Returns
Const reference to the field value at the specified row.

Definition at line 351 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
TType of the field (must not be const-qualified).
Parameters
indexThe field index.
rowThe row index.
Returns
Mutable reference to the field value at the specified row.

Definition at line 368 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 476 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
nameThe variable name.
Returns
The variable value.

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

Definition at line 109 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_idThe variable ID.
Returns
The variable value.

Definition at line 101 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 411 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
indexThe 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
indexThe 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
indexThe 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
indexThe 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 439 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
indexThe 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
indexThe 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 403 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
indexThe field index.
Returns
The source entity for the field.

Definition at line 39 of file iter.hpp.

◆ str()

flecs::string flecs::iter::str ( ) const
inline

Convert current iterator result to string.

Returns
String representation of the current iterator result.

Definition at line 275 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
indexThe field index.
funcCallback invoked for each target.

Definition at line 119 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: