Flecs: Iterators
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
Iterators
C API » Core

Functions for working with ecs_iter_t. More...

Collaboration diagram for Iterators:

## Functions
bool | ecs_iter_next (ecs_iter_t *it)
| Progress any iterator.
void | ecs_iter_fini (ecs_iter_t *it)
| Clean up iterator resources.
int32_t | ecs_iter_count (ecs_iter_t *it)
| Count the number of matched entities in a query.
bool | ecs_iter_is_true (ecs_iter_t *it)
| Test if an iterator is true.
ecs_entity_t | ecs_iter_first (ecs_iter_t *it)
| Get the first matching entity from an iterator.
void | ecs_iter_set_var (ecs_iter_t *it, int32_t var_id, ecs_entity_t entity)
| Set the value for an iterator variable.
void | ecs_iter_set_var_as_table (ecs_iter_t *it, int32_t var_id, const ecs_table_t *table)
| Same as ecs_iter_set_var(), but for a table.
void | ecs_iter_set_var_as_range (ecs_iter_t *it, int32_t var_id, const ecs_table_range_t *range)
| Same as ecs_iter_set_var(), but for a range of entities.
ecs_entity_t | ecs_iter_get_var (ecs_iter_t *it, int32_t var_id)
| Get the value of an iterator variable as an entity.
const char * | ecs_iter_get_var_name (const ecs_iter_t *it, int32_t var_id)
| Get the variable name.
int32_t | ecs_iter_get_var_count (const ecs_iter_t *it)
| Get the number of variables.
ecs_var_t * | ecs_iter_get_vars (const ecs_iter_t *it)
| Get the variable array.
ecs_table_t * | ecs_iter_get_var_as_table (ecs_iter_t *it, int32_t var_id)
| Get the value of an iterator variable as a table.
ecs_table_range_t | ecs_iter_get_var_as_range (ecs_iter_t *it, int32_t var_id)
| Get the value of an iterator variable as a table range.
bool | ecs_iter_var_is_constrained (ecs_iter_t *it, int32_t var_id)
| Return whether a variable is constrained.
uint64_t | ecs_iter_get_group (const ecs_iter_t *it)
| Return the group ID for the currently iterated result.
bool | ecs_iter_changed (ecs_iter_t *it)
| Return whether the current iterator result has changed.
char * | ecs_iter_str (const ecs_iter_t *it)
| Convert an iterator to a string.
ecs_iter_t | ecs_page_iter (const ecs_iter_t *it, int32_t offset, int32_t limit)
| Create a paged iterator.
bool | ecs_page_next (ecs_iter_t *it)
| Progress a paged iterator.
ecs_iter_t | ecs_worker_iter (const ecs_iter_t *it, int32_t index, int32_t count)
| Create a worker iterator.
bool | ecs_worker_next (ecs_iter_t *it)
| Progress a worker iterator.
void * | ecs_field_w_size (const ecs_iter_t *it, size_t size, int8_t index)
| Get data for a field.
void * | ecs_field_at_w_size (const ecs_iter_t *it, size_t size, int8_t index, int32_t row)
| Get data for a field at a specified row.
bool | ecs_field_is_readonly (const ecs_iter_t *it, int8_t index)
| Test whether the field is read-only.
bool | ecs_field_is_writeonly (const ecs_iter_t *it, int8_t index)
| Test whether the field is write-only.
bool | ecs_field_is_set (const ecs_iter_t *it, int8_t index)
| Test whether a field is set.
ecs_id_t | ecs_field_id (const ecs_iter_t *it, int8_t index)
| Return the ID matched for a field.
int32_t | ecs_field_column (const ecs_iter_t *it, int8_t index)
| Return the index of a matched table column.
ecs_entity_t | ecs_field_src (const ecs_iter_t *it, int8_t index)
| Return the field source.
size_t | ecs_field_size (const ecs_iter_t *it, int8_t index)
| Return the field type size.
bool | ecs_field_is_self (const ecs_iter_t *it, int8_t index)
| Test whether the field is matched on self.

## Detailed Description

Functions for working with ecs_iter_t.

## Function Documentation

## ◆ ecs_field_at_w_size()

void * ecs_field_at_w_size | ( | const ecs_iter_t * | it,
|  | size_t | size,
|  | int8_t | index,
|  | int32_t | row )

Get data for a field at a specified row.

This operation should be used instead of ecs_field_w_size() for sparse component fields. This operation should be called for each returned row in a result. In the following example, the Velocity component is sparse:

while (ecs_query_next(&it)) {
Position *p = ecs_field(&it, Position, 0);
for (int32_t i = 0; i < it.count; i ++) {
Velocity *v = ecs_field_at(&it, Velocity, 1, i);
p[i].x += v->x;
p[i].y += v->y;
}
}
ecs_field
#define ecs_field(it, T, index)
Get field data for a component.
Definition flecs_c.h:727
ecs_field_at
#define ecs_field_at(it, T, index, row)
Get field data at a specific row.
Definition flecs_c.h:735
ecs_query_next
bool ecs_query_next(ecs_iter_t *it)
Progress a query iterator.

Parameters

  it | The iterator.
  size | The size of the field type.
  index | The index of the field.
  row | The row to get data for.

Returns
  A pointer to the data of the field.

## ◆ ecs_field_column()

int32_t ecs_field_column | ( | const ecs_iter_t * | it,
|  | int8_t | index )

Return the index of a matched table column.

This function only returns column indices for fields that have been matched on the $this variable. Fields matched on other tables will return -1.

Parameters

  it | The iterator.
  index | The index of the field in the iterator.

Returns
  The index of the matched column, -1 if not matched.

## ◆ ecs_field_id()

ecs_id_t ecs_field_id | ( | const ecs_iter_t * | it,
|  | int8_t | index )

Return the ID matched for a field.

Parameters

  it | The iterator.
  index | The index of the field in the iterator.

Returns
  The ID matched for the field.

## ◆ ecs_field_is_readonly()

bool ecs_field_is_readonly | ( | const ecs_iter_t * | it,
|  | int8_t | index )

Test whether the field is read-only.

This operation returns whether the field is read-only. Read-only fields are annotated with [in], or are added as a const type in the C++ API.

Parameters

  it | The iterator.
  index | The index of the field in the iterator.

Returns
  Whether the field is read-only.

## ◆ ecs_field_is_self()

bool ecs_field_is_self | ( | const ecs_iter_t * | it,
|  | int8_t | index )

Test whether the field is matched on self.

This operation returns whether the field is matched on the currently iterated entity. This function will return false when the field is owned by another entity, such as a parent or a prefab.

When this operation returns false, the field must be accessed as a single value instead of an array. Fields for which this operation returns true return arrays with it->count values.

Parameters

  it | The iterator.
  index | The index of the field in the iterator.

Returns
  Whether the field is matched on self.

## ◆ ecs_field_is_set()

bool ecs_field_is_set | ( | const ecs_iter_t * | it,
|  | int8_t | index )

Test whether a field is set.

Parameters

  it | The iterator.
  index | The index of the field in the iterator.

Returns
  Whether the field is set.

## ◆ ecs_field_is_writeonly()

bool ecs_field_is_writeonly | ( | const ecs_iter_t * | it,
|  | int8_t | index )

Test whether the field is write-only.

This operation returns whether this is a write-only field. Write-only terms are annotated with [out].

Serializers are not required to serialize the values of a write-only field.

Parameters

  it | The iterator.
  index | The index of the field in the iterator.

Returns
  Whether the field is write-only.

## ◆ ecs_field_size()

size_t ecs_field_size | ( | const ecs_iter_t * | it,
|  | int8_t | index )

Return the field type size.

Returns the type size of the field. Returns 0 if the field has no data.

Parameters

  it | The iterator.
  index | The index of the field in the iterator.

Returns
  The type size for the field.

## ◆ ecs_field_src()

ecs_entity_t ecs_field_src | ( | const ecs_iter_t * | it,
|  | int8_t | index )

Return the field source.

The field source is the entity on which the field was matched.

Parameters

  it | The iterator.
  index | The index of the field in the iterator.

Returns
  The source for the field.

## ◆ ecs_field_w_size()

void * ecs_field_w_size | ( | const ecs_iter_t * | it,
|  | size_t | size,
|  | int8_t | index )

Get data for a field.

This operation retrieves a pointer to an array of data that belongs to the term in the query. The index refers to the location of the term in the query, and starts counting from zero.

For example, the query "Position, Velocity" will return the Position array for index 0, and the Velocity array for index 1.

When the specified field is not owned by the entity, this function returns a pointer instead of an array. This happens when the source of a field is not the entity being iterated, such as a shared component (from a prefab), a component from a parent, or another entity. The ecs_field_is_self() operation can be used to test dynamically if a field is owned.

When a field contains a sparse component, use the ecs_field_at() function. When a field is guaranteed to be set and owned, the ecs_field_self() function can be used. ecs_field_self() has slightly better performance, and provides stricter validity checking.

The provided size must be either 0 or must match the size of the type of the returned array. If the size does not match, the operation may assert. The size can be dynamically obtained with ecs_field_size().

An example:

while (ecs_query_next(&it)) {
Position *p = ecs_field(&it, Position, 0);
Velocity *v = ecs_field(&it, Velocity, 1);
for (int32_t i = 0; i < it.count; i ++) {
p[i].x += v[i].x;
p[i].y += v[i].y;
}
}

Parameters

  it | The iterator.
  size | The size of the field type.
  index | The index of the field.

Returns
  A pointer to the data of the field.

## ◆ ecs_iter_changed()

bool ecs_iter_changed | ( | ecs_iter_t * | it | ) |

Return whether the current iterator result has changed.

This operation must be used in combination with a query that supports change detection (e.g., is cached). The operation returns whether the currently iterated result has changed since the last time it was iterated by the query.

Change detection works on a per-table basis. Changes to individual entities cannot be detected this way.

Parameters

  it | The iterator.

Returns
  True if the result changed, false if it didn't.

## ◆ ecs_iter_count()

int32_t ecs_iter_count | ( | ecs_iter_t * | it | ) |

Count the number of matched entities in a query.

This operation returns the number of matched entities. If a query contains no matched entities but still yields results (e.g., it has no terms with $this sources), the operation will return 0.

To determine the number of matched entities, the operation iterates the iterator until it yields no more results.

Parameters

  it | The iterator.

Returns
  The number of matched entities.

## ◆ ecs_iter_fini()

void ecs_iter_fini | ( | ecs_iter_t * | it | ) |

Clean up iterator resources.

This operation cleans up any resources associated with the iterator.

This operation should only be used when an iterator is not iterated until completion (next() has not yet returned false). When an iterator is iterated until completion, resources are automatically freed.

Parameters

  it | The iterator.

## ◆ ecs_iter_first()

ecs_entity_t ecs_iter_first | ( | ecs_iter_t * | it | ) |

Get the first matching entity from an iterator.

After this operation, the application should treat the iterator as if it has been iterated until completion.

Parameters

  it | The iterator.

Returns
  The first matching entity, or 0 if no entities were matched.

## ◆ ecs_iter_get_group()

uint64_t ecs_iter_get_group | ( | const ecs_iter_t * | it | ) |

Return the group ID for the currently iterated result.

This operation returns the group ID for queries that use group_by. If this operation is called on an iterator that is not iterating a query that uses group_by, it will fail.

For queries that use cascade, this operation will return the hierarchy depth of the currently iterated result.

Parameters

  it | The iterator.

Returns
  The group ID of the currently iterated result.

## ◆ ecs_iter_get_var()

ecs_entity_t ecs_iter_get_var | ( | ecs_iter_t * | it,
|  | int32_t | var_id )

Get the value of an iterator variable as an entity.

A variable can be interpreted as an entity if it is set to an entity, or if it is set to a table range with count 1.

This operation can only be invoked on valid iterators. The variable index must be smaller than the total number of variables provided by the iterator (as returned by ecs_iter_get_var_count()).

Parameters

  it | The iterator.
  var_id | The variable index.

Returns
  The variable value.

## ◆ ecs_iter_get_var_as_range()

ecs_table_range_t ecs_iter_get_var_as_range | ( | ecs_iter_t * | it,
|  | int32_t | var_id )

Get the value of an iterator variable as a table range.

A value can be interpreted as a table range if it is set as a table range, or if it is set to an entity with a non-empty type (the entity must have at least one component, tag, or relationship in its type).

This operation can only be invoked on valid iterators. The variable index must be smaller than the total number of variables provided by the iterator (as returned by ecs_iter_get_var_count()).

Parameters

  it | The iterator.
  var_id | The variable index.

Returns
  The variable value.

## ◆ ecs_iter_get_var_as_table()

ecs_table_t * ecs_iter_get_var_as_table | ( | ecs_iter_t * | it,
|  | int32_t | var_id )

Get the value of an iterator variable as a table.

A variable can be interpreted as a table if it is set as a table range with both offset and count set to 0, or if offset is 0 and count matches the number of elements in the table.

This operation can only be invoked on valid iterators. The variable index must be smaller than the total number of variables provided by the iterator (as returned by ecs_iter_get_var_count()).

Parameters

  it | The iterator.
  var_id | The variable index.

Returns
  The variable value.

## ◆ ecs_iter_get_var_count()

int32_t ecs_iter_get_var_count | ( | const ecs_iter_t * | it | ) |

Get the number of variables.

Parameters

  it | The iterator.

Returns
  The number of variables.

## ◆ ecs_iter_get_var_name()

const char * ecs_iter_get_var_name | ( | const ecs_iter_t * | it,
|  | int32_t | var_id )

Get the variable name.

Parameters

  it | The iterator.
  var_id | The variable index.

Returns
  The variable name.

## ◆ ecs_iter_get_vars()

ecs_var_t * ecs_iter_get_vars | ( | const ecs_iter_t * | it | ) |

Get the variable array.

Parameters

  it | The iterator.

Returns
  The variable array (if any).

## ◆ ecs_iter_is_true()

bool ecs_iter_is_true | ( | ecs_iter_t * | it | ) |

Test if an iterator is true.

This operation will return true if the iterator returns at least one result. This is especially useful in combination with fact-checking queries (see the queries addon).

The operation requires a valid iterator. After the operation is invoked, the application should no longer invoke next() on the iterator and should treat it as if the iterator is iterated until completion.

Parameters

  it | The iterator.

Returns
  True if the iterator returns at least one result.

## ◆ ecs_iter_next()

bool ecs_iter_next | ( | ecs_iter_t * | it | ) |

Progress any iterator.

This operation is useful in combination with iterators for which it is not known what created them. Example use cases are functions that should accept any kind of iterator (such as serializers) or iterators created from poly objects.

This operation is slightly slower than using a type-specific iterator (e.g., ecs_query_next(), ecs_each_next()), as it has to call a function pointer, which introduces a level of indirection.

Parameters

  it | The iterator.

Returns
  True if iterator has more results, false if not.

## ◆ ecs_iter_set_var()

void ecs_iter_set_var | ( | ecs_iter_t * | it,
|  | int32_t | var_id,
|  | ecs_entity_t | entity )

Set the value for an iterator variable.

This constrains the iterator to return only results for which the variable equals the specified value. The default value for all variables is EcsWildcard, which means the variable can assume any value.

Example:

// Query that matches (Eats, *)
ecs_query_t *q = ecs_query(world, {
.terms = {
{ .first.id = Eats, .second.name = "$food" }
}
});
int food_var = ecs_query_find_var(q, "food");
// Set Food to Apples, so we're only matching (Eats, Apples)
ecs_iter_t it = ecs_query_iter(world, q);
ecs_iter_set_var(&it, food_var, Apples);
while (ecs_query_next(&it)) {
for (int i = 0; i < it.count; i ++) {
// iterate as usual
}
}
ecs_query
#define ecs_query(world,...)
Shorthand for creating a query with ecs_query_init().
Definition flecs_c.h:262
ecs_iter_set_var
void ecs_iter_set_var(ecs_iter_t *it, int32_t var_id, ecs_entity_t entity)
Set the value for an iterator variable.
ecs_query_find_var
int32_t ecs_query_find_var(const ecs_query_t *query, const char *name)
Find a variable index.
ecs_query_iter
ecs_iter_t ecs_query_iter(const ecs_world_t *world, const ecs_query_t *query)
Create a query iterator.
ecs_iter_t
Iterator.
Definition flecs.h:1166
ecs_iter_t::count
int32_t count
Number of entities to iterate.
Definition flecs.h:1173
ecs_query_t
Queries are lists of constraints (terms) that match entities.
Definition flecs.h:834

The variable must be initialized after creating the iterator and before the first call to next().

Parameters

  it | The iterator.
  var_id | The variable index.
  entity | The entity variable value.

See also
  ecs_iter_set_var_as_range()
  ecs_iter_set_var_as_table()

## ◆ ecs_iter_set_var_as_range()

void ecs_iter_set_var_as_range | ( | ecs_iter_t * | it,
|  | int32_t | var_id,
|  | const ecs_table_range_t * | range )

Same as ecs_iter_set_var(), but for a range of entities.

This constrains the variable to a range of entities in a table.

Parameters

  it | The iterator.
  var_id | The variable index.
  range | The range variable value.

See also
  ecs_iter_set_var()
  ecs_iter_set_var_as_table()

## ◆ ecs_iter_set_var_as_table()

void ecs_iter_set_var_as_table | ( | ecs_iter_t * | it,
|  | int32_t | var_id,
|  | const ecs_table_t * | table )

Same as ecs_iter_set_var(), but for a table.

This constrains the variable to all entities in a table.

Parameters

  it | The iterator.
  var_id | The variable index.
  table | The table variable value.

See also
  ecs_iter_set_var()
  ecs_iter_set_var_as_range()

## ◆ ecs_iter_str()

char * ecs_iter_str | ( | const ecs_iter_t * | it | ) |

Convert an iterator to a string.

Prints the contents of an iterator to a string. Useful for debugging and/or testing the output of an iterator.

The function only converts the currently iterated data to a string. To convert all data, the application has to manually call the next function and call ecs_iter_str() on each result.

Parameters

  it | The iterator.

Returns
  A string representing the contents of the iterator.

## ◆ ecs_iter_var_is_constrained()

bool ecs_iter_var_is_constrained | ( | ecs_iter_t * | it,
|  | int32_t | var_id )

Return whether a variable is constrained.

This operation returns true for variables set by one of the ecs_iter_set_var* operations.

A constrained variable is guaranteed not to change values while results are being iterated.

Parameters

  it | The iterator.
  var_id | The variable index.

Returns
  Whether the variable is constrained to a specified value.

## ◆ ecs_page_iter()

ecs_iter_t ecs_page_iter | ( | const ecs_iter_t * | it,
|  | int32_t | offset,
|  | int32_t | limit )

Create a paged iterator.

Paged iterators limit the results to those starting from 'offset', and will return at most 'limit' results.

The iterator must be iterated with ecs_page_next().

A paged iterator acts as a passthrough for data exposed by the parent iterator, so that any data provided by the parent will also be provided by the paged iterator.

Parameters

  it | The source iterator.
  offset | The number of entities to skip.
  limit | The maximum number of entities to iterate.

Returns
  A page iterator.

## ◆ ecs_page_next()

bool ecs_page_next | ( | ecs_iter_t * | it | ) |

Progress a paged iterator.

Progress an iterator created by ecs_page_iter().

Parameters

  it | The iterator.

Returns
  True if the iterator has more results, false if not.

## ◆ ecs_worker_iter()

ecs_iter_t ecs_worker_iter | ( | const ecs_iter_t * | it,
|  | int32_t | index,
|  | int32_t | count )

Create a worker iterator.

Worker iterators can be used to equally divide the number of matched entities across N resources (usually threads). Each resource will process the total number of matched entities divided by 'count'.

Entities are distributed across resources such that the distribution is stable between queries. Two queries that match the same table are guaranteed to match the same entities in that table.

The iterator must be iterated with ecs_worker_next().

A worker iterator acts as a passthrough for data exposed by the parent iterator, so that any data provided by the parent will also be provided by the worker iterator.

Parameters

  it | The source iterator.
  index | The index of the current resource.
  count | The total number of resources to divide entities between.

Returns
  A worker iterator.

## ◆ ecs_worker_next()

bool ecs_worker_next | ( | ecs_iter_t * | it | ) |

Progress a worker iterator.

Progress an iterator created by ecs_worker_iter().

Parameters

  it | The iterator.

Returns
  True if the iterator has more results, false if not.