Flecs: flecs::iter Struct Reference
Description: A fast entity component system (ECS) for C & C++

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

Loading...
Searching...
No Matches
flecs::iter Struct Reference
C++ API » Core » Iterators

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.
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_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 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

  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]

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.

## ◆ ctx() [2/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.

## ◆ 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

  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]

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 320 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]

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_at() [1/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 368 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 351 of file iter.hpp.

## ◆ field_at() [3/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 334 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

  name | The 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_id | The 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

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

  index | The field index.

Returns
  The pair ID matched for the field.

Definition at line 49 of file iter.hpp.

## ◆ param() [1/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.

## ◆ param() [2/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.

## ◆ 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 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

  index | The 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

  index | The field index.
  func | Callback 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:

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