Function ecs_query_iter


#include <include/flecs.h>

FLECS_API ecs_iter_t ecs_query_iter(const ecs_world_t *world, ecs_query_t *query)


Return a query iterator. A query iterator lets an application iterate over entities that match the specified query. If a sorting function is specified, the query will check whether a resort is required upon creating the iterator.

Creating a query iterator is a cheap operation that does not allocate any resources. An application does not need to deinitialize or free a query iterator before it goes out of scope.

To iterate the iterator, an application should use ecs_query_next to progress the iterator and test if it has data.

Query iteration requires an outer and an inner loop. The outer loop uses ecs_query_next to test if new tables are available. The inner loop iterates the entities in the table, and is usually a for loop that uses iter.count to loop through the entities and component arrays.

The two loops are necessary because of how data is stored internally. Entities are grouped by the components they have, in tables. A single query can (and often does) match with multiple tables. Because each table has its own set of arrays, an application has to reobtain pointers to those arrays for each matching table.


world - The world or stage, when iterating in readonly mode.

query - The query to iterate.

The query iterator.

Mentioned in


Line 3353 in include/flecs.h.