Functions for working with ecs_iter_t. More...

Collaboration diagram for Iterators:

Functions
void	ecs_iter_poly (const ecs_world_t world, const ecs_poly_t poly, ecs_iter_t iter, ecs_term_t filter)
	Create iterator from poly object.

bool	ecs_iter_next (ecs_iter_t *it)
	Progress any iterator.

void	ecs_iter_fini (ecs_iter_t *it)
	Cleanup iterator resources.

int32_t	ecs_iter_count (ecs_iter_t *it)
	Count number of matched entities in query.

bool	ecs_iter_is_true (ecs_iter_t *it)
	Test if iterator is true.

ecs_entity_t	ecs_iter_first (ecs_iter_t *it)
	Get first matching entity from iterator.

void	ecs_iter_set_var (ecs_iter_t *it, int32_t var_id, ecs_entity_t entity)
	Set value for 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 This constrains the variable to a range of entities in a table.

ecs_entity_t	ecs_iter_get_var (ecs_iter_t *it, int32_t var_id)
	Get value of iterator variable as entity.

ecs_table_t *	ecs_iter_get_var_as_table (ecs_iter_t *it, int32_t var_id)
	Get value of iterator variable as table.

ecs_table_range_t	ecs_iter_get_var_as_range (ecs_iter_t *it, int32_t var_id)
	Get value of iterator variable as table range.

bool	ecs_iter_var_is_constrained (ecs_iter_t *it, int32_t var_id)
	Returns whether variable is constrained.

char *	ecs_iter_str (const ecs_iter_t *it)
	Convert iterator to 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, int32_t index)
	Obtain data for a query field.

bool	ecs_field_is_readonly (const ecs_iter_t *it, int32_t index)
	Test whether the field is readonly.

bool	ecs_field_is_writeonly (const ecs_iter_t *it, int32_t index)
	Test whether the field is writeonly.

bool	ecs_field_is_set (const ecs_iter_t *it, int32_t index)
	Test whether field is set.

ecs_id_t	ecs_field_id (const ecs_iter_t *it, int32_t index)
	Return id matched for field.

int32_t	ecs_field_column_index (const ecs_iter_t *it, int32_t index)
	Return index of matched table column.

ecs_entity_t	ecs_field_src (const ecs_iter_t *it, int32_t index)
	Return field source.

size_t	ecs_field_size (const ecs_iter_t *it, int32_t index)
	Return field type size.

bool	ecs_field_is_self (const ecs_iter_t *it, int32_t index)
	Test whether the field is matched on self.

Detailed Description

Functions for working with ecs_iter_t.

Function Documentation

◆ ecs_field_column_index()

int32_t ecs_field_column_index	(	const ecs_iter_t *	it,
		int32_t	index )

Return index of 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,
		int32_t	index )

Return id matched for 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,
		int32_t	index )

Test whether the field is readonly.

This operation returns whether the field is readonly. Readonly 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 readonly.

◆ ecs_field_is_self()

bool ecs_field_is_self	(	const ecs_iter_t *	it,
		int32_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,
		int32_t	index )

Test whether 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,
		int32_t	index )

Test whether the field is writeonly.

This operation returns whether this is a writeonly field. Writeonly terms are annotated with [out].

Serializers are not required to serialize the values of a writeonly field.

Parameters

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

Returns: Whether the field is writeonly.

◆ ecs_field_size()

size_t ecs_field_size	(	const ecs_iter_t *	it,
		int32_t	index )

Return field type size.

Return 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,
		int32_t	index )

Return 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,
		int32_t	index )

Obtain data for a query 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 one.

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

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.

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

Parameters

it	The iterator.
size	The type size of the requested data.
index	The index of the field in the iterator.

Returns: A pointer to the data of the field.

◆ ecs_iter_count()

int32_t ecs_iter_count ( ecs_iter_t * it )

Count number of matched entities in 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: True if iterator has more results, false if not.

◆ ecs_iter_fini()

void ecs_iter_fini ( ecs_iter_t * it )

Cleanup 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 first matching entity from 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_var()

ecs_entity_t ecs_iter_get_var	(	ecs_iter_t *	it,
		int32_t	var_id )

Get value of iterator variable as entity.

A variable can be interpreted as 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 set in ecs_iter_t::variable_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 value of iterator variable as table range.

A value can be interpreted as table range if it is set as 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 set in ecs_iter_t::variable_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 value of iterator variable as table.

A variable can be interpreted as table if it is set as 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 set in ecs_iter_t::variable_count).

Parameters

it	The iterator.
var_id	The variable index.

Returns: The variable value.

◆ ecs_iter_is_true()

bool ecs_iter_is_true ( ecs_iter_t * it )

Test if 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 rules (see the rules 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_filter_next(), ecs_query_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_poly()

void ecs_iter_poly	(	const ecs_world_t *	world,
		const ecs_poly_t *	poly,
		ecs_iter_t *	iter,
		ecs_term_t *	filter )

Create iterator from poly object.

The provided poly object must have the iterable mixin. If an object is provided that does not have the mixin, the function will assert.

When a filter is provided, an array of two iterators must be passed to the function. This allows the mixin implementation to create a chained iterator when necessary, which requires two iterator objects.

If a filter is provided, the first element in the array of two iterators is the one that should be iterated. The mixin implementation may or may not set the second element, depending on whether an iterator chain is required.

Additionally, when a filter is provided the returned iterator will be for a single term with the provided filter id. If the iterator is chained, the previous iterator in the chain can be accessed through it->chain_it.

Parameters

world	The world or stage for which to create the iterator.
poly	The poly object from which to create the iterator.
iter	The iterator (out, ecs_iter_t[2] when filter is set).
filter	Optional term used for filtering the results.

◆ ecs_iter_set_var()

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

Set value for 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:

// Rule that matches (Eats, *)
ecs_rule_t *r = ecs_rule_init(world, &(ecs_filter_desc_t){
  .terms = {
    { .first.id = Eats, .second.name = "$food" }
  }
});
 
int food_var = ecs_rule_find_var(r, "food");
 
// Set Food to Apples, so we're only matching (Eats, Apples)
ecs_iter_t it = ecs_rule_iter(world, r);
ecs_iter_set_var(&it, food_var, Apples);
 
while (ecs_rule_next(&it)) {
  for (int i = 0; i < it.count; i ++) {
    // iterate as usual
  }
}

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.

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

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

◆ ecs_iter_str()

char * ecs_iter_str ( const ecs_iter_t * it )

Convert iterator to 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 )

Returns whether 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.

Progresses an iterator created by ecs_page_iter().

Parameters

it	The iterator.

Returns: true if 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.

Progresses an iterator created by ecs_worker_iter().

Parameters

it	The iterator.

Returns: true if iterator has more results, false if not.