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

Functions for working with ecs_term_t and ecs_query_t. More...

Collaboration diagram for Queries:

## Classes
struct | ecs_iter_t
| Iterator. More...
struct | ecs_query_desc_t
| Used with ecs_query_init(). More...
struct | ecs_query_count_t
| Struct returned by ecs_query_count(). More...

## Macros
#define | EcsSelf (1llu << 63)
| Term ID flags.
#define | EcsUp (1llu << 62)
| Match by traversing upwards.
#define | EcsTrav (1llu << 61)
| Traverse relationship transitively.
#define | EcsCascade (1llu << 60)
| Sort results breadth-first.
#define | EcsDesc (1llu << 59)
| Iterate groups in descending order.
#define | EcsIsVariable (1llu << 58)
| Term ID is a variable.
#define | EcsIsEntity (1llu << 57)
| Term ID is an entity.
#define | EcsIsName (1llu << 56)
| Term ID is a name (don't attempt to look up as an entity).
#define | EcsTraverseFlags (EcsSelf|EcsUp|EcsTrav|EcsCascade|EcsDesc)
| All term traversal flags.
#define | EcsTermRefFlags (EcsTraverseFlags|EcsIsVariable|EcsIsEntity|EcsIsName)
| All term reference kind flags.
#define | EcsQueryMatchPrefab (1u << 1u)
| Query must match prefabs.
#define | EcsQueryMatchDisabled (1u << 2u)
| Query must match disabled entities.
#define | EcsQueryMatchEmptyTables (1u << 3u)
| Query must match empty tables.
#define | EcsQueryAllowUnresolvedByName (1u << 6u)
| Query may have unresolved entity identifiers.
#define | EcsQueryTableOnly (1u << 7u)
| Query only returns whole tables (ignores toggle or member fields).
#define | EcsQueryDetectChanges (1u << 8u)
| Enable change detection for a query.
#define | EcsQueryGroupByOrdered (1u << 9u)
| Enable ordering for query groups.
#define | EcsQueryGroupByDesc (1u << 10u)
| Enable descending ordering for query groups.

## Typedefs
typedef struct ecs_query_desc_t | ecs_query_desc_t
| Used with ecs_query_init().
typedef struct ecs_query_count_t | ecs_query_count_t
| Struct returned by ecs_query_count().

## Functions
bool | ecs_term_ref_is_set (const ecs_term_ref_t *ref)
| Test whether a term ref is set.
bool | ecs_term_is_initialized (const ecs_term_t *term)
| Test whether a term is set.
bool | ecs_term_match_this (const ecs_term_t *term)
| Is a term matched on the $this variable.
bool | ecs_term_match_0 (const ecs_term_t *term)
| Is a term matched on a 0 source.
char * | ecs_term_str (const ecs_world_t *world, const ecs_term_t *term)
| Convert a term to a string expression.
char * | ecs_query_str (const ecs_query_t *query)
| Convert a query to a string expression.
ecs_query_t * | ecs_query_init (ecs_world_t *world, const ecs_query_desc_t *desc)
| Create a query.
ecs_query_t * | ecs_query_update (ecs_world_t *world, ecs_entity_t entity, const ecs_query_desc_t *desc)
| Replace the query on an existing entity.
void | ecs_query_fini (ecs_query_t *query)
| Delete a query.
int32_t | ecs_query_find_var (const ecs_query_t *query, const char *name)
| Find a variable index.
const char * | ecs_query_var_name (const ecs_query_t *query, int32_t var_id)
| Get the variable name.
bool | ecs_query_var_is_entity (const ecs_query_t *query, int32_t var_id)
| Test if a variable is an entity.
ecs_iter_t | ecs_query_iter (const ecs_world_t *world, const ecs_query_t *query)
| Create a query iterator.
bool | ecs_query_next (ecs_iter_t *it)
| Progress a query iterator.
bool | ecs_query_has (const ecs_query_t *query, ecs_entity_t entity, ecs_iter_t *it)
| Match an entity with a query.
bool | ecs_query_has_table (const ecs_query_t *query, ecs_table_t *table, ecs_iter_t *it)
| Match a table with a query.
bool | ecs_query_has_range (const ecs_query_t *query, ecs_table_range_t *range, ecs_iter_t *it)
| Match a range with a query.
int32_t | ecs_query_match_count (const ecs_query_t *query)
| Return how often a match event happened for a cached query.
char * | ecs_query_plan (const ecs_query_t *query)
| Convert a query to a string.
char * | ecs_query_plan_w_profile (const ecs_query_t *query, const ecs_iter_t *it)
| Convert a query to a string with a profile.
char * | ecs_query_plans (const ecs_query_t *query)
| Same as ecs_query_plan(), but includes the plan for populating the cache (if any).
const char * | ecs_query_args_parse (ecs_query_t *query, ecs_iter_t *it, const char *expr)
| Populate variables from a key-value string.
bool | ecs_query_changed (ecs_query_t *query)
| Return whether the query data changed since the last iteration.
const ecs_query_t * | ecs_query_get (const ecs_world_t *world, ecs_entity_t query)
| Get the query object.
void | ecs_iter_skip (ecs_iter_t *it)
| Skip a table while iterating.
void | ecs_iter_set_group (ecs_iter_t *it, uint64_t group_id)
| Set the group to iterate for a query iterator.
const ecs_map_t * | ecs_query_get_groups (const ecs_query_t *query)
| Return the map with query groups.
void * | ecs_query_get_group_ctx (const ecs_query_t *query, uint64_t group_id)
| Get the context of a query group.
const ecs_query_group_info_t * | ecs_query_get_group_info (const ecs_query_t *query, uint64_t group_id)
| Get information about a query group.
ecs_query_count_t | ecs_query_count (const ecs_query_t *query)
| Return the number of entities and results the query matches with.
bool | ecs_query_is_true (const ecs_query_t *query)
| Test whether a query returns one or more results.
const ecs_query_t * | ecs_query_get_cache_query (const ecs_query_t *query)
| Get the query used to populate the cache.

## Detailed Description

Functions for working with ecs_term_t and ecs_query_t.

Functions for working with ecs_query_t.

## Macro Definition Documentation

## ◆ EcsCascade

#define EcsCascade (1llu << 60)

Sort results breadth-first.

Can be combined with other term flags on the ecs_term_ref_t::id field.

Definition at line 760 of file flecs.h.

## ◆ EcsDesc

#define EcsDesc (1llu << 59)

Iterate groups in descending order.

Can be combined with other term flags on the ecs_term_ref_t::id field.

Definition at line 766 of file flecs.h.

## ◆ EcsIsEntity

#define EcsIsEntity (1llu << 57)

Term ID is an entity.

Can be combined with other term flags on the ecs_term_ref_t::id field.

Definition at line 778 of file flecs.h.

## ◆ EcsIsName

#define EcsIsName (1llu << 56)

Term ID is a name (don't attempt to look up as an entity).

Can be combined with other term flags on the ecs_term_ref_t::id field.

Definition at line 784 of file flecs.h.

## ◆ EcsIsVariable

#define EcsIsVariable (1llu << 58)

Term ID is a variable.

Can be combined with other term flags on the ecs_term_ref_t::id field.

Definition at line 772 of file flecs.h.

## ◆ EcsQueryAllowUnresolvedByName

#define EcsQueryAllowUnresolvedByName (1u << 6u)

Query may have unresolved entity identifiers.

Can be combined with other query flags on the ecs_query_desc_t::flags field.

Definition at line 1255 of file flecs.h.

## ◆ EcsQueryDetectChanges

#define EcsQueryDetectChanges (1u << 8u)

Enable change detection for a query.

Can be combined with other query flags on the ecs_query_desc_t::flags field.

Adding this flag makes it possible to use ecs_query_changed() and ecs_iter_changed() with the query. Change detection requires the query to be cached. If cache_kind is left to the default value, this flag will cause it to default to EcsQueryCacheAuto.

Definition at line 1273 of file flecs.h.

## ◆ EcsQueryGroupByDesc

#define EcsQueryGroupByDesc (1u << 10u)

Enable descending ordering for query groups.

When this flag is set in combination with EcsQueryGroupByOrdered, groups will be iterated in descending order, with higher group ids first and lower group ids afterwards.

This flag is enabled automatically when a query contains cascade|desc terms.

Definition at line 1294 of file flecs.h.

## ◆ EcsQueryGroupByOrdered

#define EcsQueryGroupByOrdered (1u << 9u)

Enable ordering for query groups.

When this flag is set, groups will be iterated in ascending order, with lower group ids first and higher group ids afterwards.

This flag is enabled automatically when a query contains cascade terms.

Definition at line 1283 of file flecs.h.

## ◆ EcsQueryMatchDisabled

#define EcsQueryMatchDisabled (1u << 2u)

Query must match disabled entities.

Can be combined with other query flags on the ecs_query_desc_t::flags field.

Definition at line 1243 of file flecs.h.

## ◆ EcsQueryMatchEmptyTables

#define EcsQueryMatchEmptyTables (1u << 3u)

Query must match empty tables.

Can be combined with other query flags on the ecs_query_desc_t::flags field.

Definition at line 1249 of file flecs.h.

## ◆ EcsQueryMatchPrefab

#define EcsQueryMatchPrefab (1u << 1u)

Query must match prefabs.

Can be combined with other query flags on the ecs_query_desc_t::flags field.

Definition at line 1237 of file flecs.h.

## ◆ EcsQueryTableOnly

#define EcsQueryTableOnly (1u << 7u)

Query only returns whole tables (ignores toggle or member fields).

Can be combined with other query flags on the ecs_query_desc_t::flags field.

Definition at line 1261 of file flecs.h.

## ◆ EcsSelf

#define EcsSelf (1llu << 63)

Term ID flags.

Match on self. Can be combined with other term flags on the ecs_term_ref_t::id field.

Definition at line 742 of file flecs.h.

## ◆ EcsTermRefFlags

#define EcsTermRefFlags (EcsTraverseFlags|EcsIsVariable|EcsIsEntity|EcsIsName)

All term reference kind flags.

Can be combined with other term flags on the ecs_term_ref_t::id field.

Definition at line 796 of file flecs.h.

## ◆ EcsTrav

#define EcsTrav (1llu << 61)

Traverse relationship transitively.

Can be combined with other term flags on the ecs_term_ref_t::id field.

Definition at line 754 of file flecs.h.

## ◆ EcsTraverseFlags

#define EcsTraverseFlags (EcsSelf|EcsUp|EcsTrav|EcsCascade|EcsDesc)

All term traversal flags.

Can be combined with other term flags on the ecs_term_ref_t::id field.

Definition at line 790 of file flecs.h.

## ◆ EcsUp

#define EcsUp (1llu << 62)

Match by traversing upwards.

Can be combined with other term flags on the ecs_term_ref_t::id field.

Definition at line 748 of file flecs.h.

## Function Documentation

## ◆ ecs_iter_set_group()

void ecs_iter_set_group | ( | ecs_iter_t * | it,
|  | uint64_t | group_id )

Set the group to iterate for a query iterator.

This operation limits the results returned by the query to only the selected group ID. The query must have a group_by function, and the iterator must be a query iterator.

Groups are sets of tables that are stored together in the query cache based on a group ID, which is calculated per table by the group_by function. To iterate a group, an iterator only needs to know the first and last cache node for that group, which can both be found in a fast O(1) operation.

As a result, group iteration is one of the most efficient mechanisms to filter out large numbers of entities, even if those entities are distributed across many tables. This makes it a good fit for things like dividing up a world into cells, and only iterating cells close to a player.

The group to iterate must be set before the first call to ecs_query_next(). No operations that can add or remove components should be invoked between calling ecs_iter_set_group() and ecs_query_next().

Parameters

  it | The query iterator.
  group_id | The group to iterate.

## ◆ ecs_iter_skip()

void ecs_iter_skip | ( | ecs_iter_t * | it | ) |

Skip a table while iterating.

This operation lets the query iterator know that a table was skipped while iterating. A skipped table will not reset its changed state, and the query will not update the dirty flags of the table for its out fields.

Only valid iterators must be provided (next() has to be called at least once and must return true), and the iterator must be a query iterator.

Parameters

  it | The iterator result to skip.

## ◆ ecs_query_args_parse()

const char * ecs_query_args_parse | ( | ecs_query_t * | query,
|  | ecs_iter_t * | it,
|  | const char * | expr )

Populate variables from a key-value string.

Convenience function to set query variables from a key-value string separated by commas. The string must have the following format:

var_a: value, var_b: value

The key-value list may optionally be enclosed in parentheses.

This function uses the script addon.

Parameters

  query | The query.
  it | The iterator for which to set the variables.
  expr | The key-value expression.

Returns
  A pointer to the next character after the last parsed one.

## ◆ ecs_query_changed()

bool ecs_query_changed | ( | ecs_query_t * | query | ) |

Return whether the query data changed since the last iteration.

The operation will return true after:

- new entities have been matched
- new tables have been matched or unmatched
- matched entities were deleted
- matched components were changed

The operation will not return true after a write-only (EcsOut) or filter (EcsInOutFilter) term has changed, when a term is not matched with the current table ($this source) or for tag terms.

The changed state of a table is reset after it is iterated. If an iterator was not iterated until completion, tables may still be marked as changed.

To check the changed state of the current iterator result, use ecs_iter_changed().

Parameters

  query | The query.

Returns
  True if entities changed, otherwise false.

See also
  ecs_iter_changed()

## ◆ ecs_query_count()

ecs_query_count_t ecs_query_count | ( | const ecs_query_t * | query | ) |

Return the number of entities and results the query matches with.

Only entities matching the $this variable as source are counted.

Parameters

  query | The query.

Returns
  The number of matched entities.

## ◆ ecs_query_find_var()

int32_t ecs_query_find_var | ( | const ecs_query_t * | query,
|  | const char * | name )

Find a variable index.

This operation looks up the index of a variable in the query. This index can be used in operations like ecs_iter_set_var() and ecs_iter_get_var().

Parameters

  query | The query.
  name | The variable name.

Returns
  The variable index.

## ◆ ecs_query_fini()

void ecs_query_fini | ( | ecs_query_t * | query | ) |

Delete a query.

Parameters

  query | The query.

## ◆ ecs_query_get()

const ecs_query_t * ecs_query_get | ( | const ecs_world_t * | world,
|  | ecs_entity_t | query )

Get the query object.

Return the query object. Can be used to access various information about the query.

Parameters

  world | The world.
  query | The query.

Returns
  The query object.

## ◆ ecs_query_get_cache_query()

const ecs_query_t * ecs_query_get_cache_query | ( | const ecs_query_t * | query | ) |

Get the query used to populate the cache.

This operation returns the query that is used to populate the query cache. For queries that can be entirely cached, the returned query will be equivalent to the query passed to ecs_query_init().

Parameters

  query | The query.

Returns
  The query used to populate the cache, NULL if query is not cached.

## ◆ ecs_query_get_group_ctx()

void * ecs_query_get_group_ctx | ( | const ecs_query_t * | query,
|  | uint64_t | group_id )

Get the context of a query group.

This operation returns the context of a query group as returned by the on_group_create callback.

Parameters

  query | The query.
  group_id | The group for which to obtain the context.

Returns
  The group context, NULL if the group doesn't exist.

## ◆ ecs_query_get_group_info()

const ecs_query_group_info_t * ecs_query_get_group_info | ( | const ecs_query_t * | query,
|  | uint64_t | group_id )

Get information about a query group.

This operation returns information about a query group, including the group context returned by the on_group_create callback.

Parameters

  query | The query.
  group_id | The group for which to obtain the group info.

Returns
  The group info, NULL if the group doesn't exist.

## ◆ ecs_query_get_groups()

const ecs_map_t * ecs_query_get_groups | ( | const ecs_query_t * | query | ) |

Return the map with query groups.

This map can be used to iterate the active group identifiers of a query. The payload of the map is opaque. The map can be used as follows:

const ecs_map_t *keys = ecs_query_get_groups(q);
ecs_map_iter_t kit = ecs_map_iter(keys);
while (ecs_map_next(&kit)) {
uint64_t group_id = ecs_map_key(&kit);
// Iterate query for group
ecs_iter_t it = ecs_query_iter(world, q);
ecs_iter_set_group(&it, group_id);
while (ecs_query_next(&it)) {
// Iterate as usual
}
}
ecs_iter_set_group
void ecs_iter_set_group(ecs_iter_t *it, uint64_t group_id)
Set the group to iterate for a query iterator.
ecs_query_next
bool ecs_query_next(ecs_iter_t *it)
Progress a query iterator.
ecs_query_iter
ecs_iter_t ecs_query_iter(const ecs_world_t *world, const ecs_query_t *query)
Create a query iterator.
ecs_query_get_groups
const ecs_map_t * ecs_query_get_groups(const ecs_query_t *query)
Return the map with query groups.
ecs_iter_t
Iterator.
Definition flecs.h:1170

This operation is not valid for queries that do not use group_by. The returned map pointer will remain valid for as long as the query exists.

Parameters

  query | The query.

Returns
  The map with query groups.

## ◆ ecs_query_has()

bool ecs_query_has | ( | const ecs_query_t * | query,
|  | ecs_entity_t | entity,
|  | ecs_iter_t * | it )

Match an entity with a query.

This operation matches an entity with a query and returns the result of the match in the "it" out parameter. An application should free the iterator resources with ecs_iter_fini() if this function returns true.

Usage:

ecs_iter_t it;
if (ecs_query_has(q, e, &it)) {
ecs_iter_fini(&it);
}
ecs_iter_fini
void ecs_iter_fini(ecs_iter_t *it)
Clean up iterator resources.
ecs_query_has
bool ecs_query_has(const ecs_query_t *query, ecs_entity_t entity, ecs_iter_t *it)
Match an entity with a query.

Parameters

  query | The query.
  entity | The entity to match.
  it | The iterator with matched data.

Returns
  True if entity matches the query, false if not.

## ◆ ecs_query_has_range()

bool ecs_query_has_range | ( | const ecs_query_t * | query,
|  | ecs_table_range_t * | range,
|  | ecs_iter_t * | it )

Match a range with a query.

This operation matches a range with a query and returns the result of the match in the "it" out parameter. An application should free the iterator resources with ecs_iter_fini() if this function returns true.

The entire range must match the query for the operation to return true.

Usage:

ecs_table_range_t range = {
.table = table,
.offset = 1,
.count = 2
};
ecs_iter_t it;
if (ecs_query_has_range(q, &range, &it)) {
ecs_iter_fini(&it);
}
ecs_query_has_range
bool ecs_query_has_range(const ecs_query_t *query, ecs_table_range_t *range, ecs_iter_t *it)
Match a range with a query.

Parameters

  query | The query.
  range | The range to match.
  it | The iterator with matched data.

Returns
  True if range matches the query, false if not.

## ◆ ecs_query_has_table()

bool ecs_query_has_table | ( | const ecs_query_t * | query,
|  | ecs_table_t * | table,
|  | ecs_iter_t * | it )

Match a table with a query.

This operation matches a table with a query and returns the result of the match in the "it" out parameter. An application should free the iterator resources with ecs_iter_fini() if this function returns true.

Usage:

ecs_iter_t it;
if (ecs_query_has_table(q, t, &it)) {
ecs_iter_fini(&it);
}
ecs_query_has_table
bool ecs_query_has_table(const ecs_query_t *query, ecs_table_t *table, ecs_iter_t *it)
Match a table with a query.

Parameters

  query | The query.
  table | The table to match.
  it | The iterator with matched data.

Returns
  True if table matches the query, false if not.

## ◆ ecs_query_init()

ecs_query_t * ecs_query_init | ( | ecs_world_t * | world,
|  | const ecs_query_desc_t * | desc )

Create a query.

If the descriptor specifies an existing entity, the entity must not already be associated with a query. To replace an existing query on an entity, use ecs_query_update().

Parameters

  world | The world.
  desc | The descriptor (see ecs_query_desc_t).

Returns
  The query.

## ◆ ecs_query_is_true()

bool ecs_query_is_true | ( | const ecs_query_t * | query | ) |

Test whether a query returns one or more results.

Parameters

  query | The query.

Returns
  True if query matches anything, false if not.

## ◆ ecs_query_iter()

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

Create a query iterator.

Use an iterator to iterate through the entities that match a query. Queries can return multiple results, and have to be iterated by repeatedly calling ecs_query_next() until the operation returns false.

Depending on the query, a single result can contain an entire table, a range of entities in a table, or a single entity. Iteration code has an inner and an outer loop. The outer loop loops through the query results, and typically corresponds with a table. The inner loop iterates entities in the result.

Example:

ecs_iter_t it = ecs_query_iter(world, q);
while (ecs_query_next(&it)) {
Position *p = ecs_field(&it, Position, 0);
Velocity *v = ecs_field(&it, Velocity, 1);
for (int i = 0; i < it.count; i ++) {
p[i].x += v[i].x;
p[i].y += v[i].y;
}
}
ecs_field
#define ecs_field(it, T, index)
Get field data for a component.
Definition flecs_c.h:727
ecs_iter_t::count
int32_t count
Number of entities to iterate.
Definition flecs.h:1177

The world passed into the operation must be either the actual world or the current stage, when iterating from a system. The stage is accessible through the it.world member.

Example:

void MySystem(ecs_iter_t *it) {
ecs_query_t *q = it->ctx; // Query passed as system context
// Create query iterator from system stage
ecs_iter_t qit = ecs_query_iter(it->world, q);
while (ecs_query_next(&qit)) {
// Iterate as usual
}
}
ecs_iter_t::ctx
void * ctx
System context.
Definition flecs.h:1208
ecs_iter_t::world
ecs_world_t * world
The world.
Definition flecs.h:1172
ecs_query_t
Queries are lists of constraints (terms) that match entities.
Definition flecs.h:838

If query iteration is stopped without the last call to ecs_query_next() returning false, iterator resources need to be cleaned up explicitly with ecs_iter_fini().

Example:

ecs_iter_t it = ecs_query_iter(world, q);
while (ecs_query_next(&it)) {
if (!ecs_field_is_set(&it, 0)) {
ecs_iter_fini(&it); // Free iterator resources
break;
}
for (int i = 0; i < it.count; i ++) {
// ...
}
}
ecs_field_is_set
bool ecs_field_is_set(const ecs_iter_t *it, int8_t index)
Test whether a field is set.

Parameters

  world | The world.
  query | The query.

Returns
  An iterator.

See also
  ecs_query_next()

## ◆ ecs_query_match_count()

int32_t ecs_query_match_count | ( | const ecs_query_t * | query | ) |

Return how often a match event happened for a cached query.

This operation can be used to determine whether the query cache has been updated with new tables.

Parameters

  query | The query.

Returns
  The number of match events that happened.

## ◆ ecs_query_next()

bool ecs_query_next | ( | ecs_iter_t * | it | ) |

Progress a query iterator.

Parameters

  it | The iterator.

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

See also
  ecs_query_iter()

## ◆ ecs_query_plan()

char * ecs_query_plan | ( | const ecs_query_t * | query | ) |

Convert a query to a string.

This will convert the query program to a string, which can aid in debugging the behavior of a query.

The returned string must be freed with ecs_os_free().

Parameters

  query | The query.

Returns
  The query plan.

## ◆ ecs_query_plan_w_profile()

char * ecs_query_plan_w_profile | ( | const ecs_query_t * | query,
|  | const ecs_iter_t * | it )

Convert a query to a string with a profile.

To use this, you must set the EcsIterProfile flag on an iterator before starting iteration:

it.flags |= EcsIterProfile;

The returned string must be freed with ecs_os_free().

Parameters

  query | The query.
  it | The iterator with profile data.

Returns
  The query plan with profile data.

## ◆ ecs_query_plans()

char * ecs_query_plans | ( | const ecs_query_t * | query | ) |

Same as ecs_query_plan(), but includes the plan for populating the cache (if any).

Parameters

  query | The query.

Returns
  The query plan.

## ◆ ecs_query_str()

char * ecs_query_str | ( | const ecs_query_t * | query | ) |

Convert a query to a string expression.

Convert a query to a string expression. The resulting expression can be parsed to create the same query.

Parameters

  query | The query.

Returns
  The query converted to a string.

## ◆ ecs_query_update()

ecs_query_t * ecs_query_update | ( | ecs_world_t * | world,
|  | ecs_entity_t | entity,
|  | const ecs_query_desc_t * | desc )

Replace the query on an existing entity.

Removes the query currently attached to the entity and creates a new one from the descriptor. Any handles to the previous query become invalid; use the returned handle for subsequent iteration.

Parameters

  world | The world.
  entity | The entity that holds the query to replace.
  desc | The descriptor (see ecs_query_desc_t).

Returns
  The new query, or NULL if the operation failed.

## ◆ ecs_query_var_is_entity()

bool ecs_query_var_is_entity | ( | const ecs_query_t * | query,
|  | int32_t | var_id )

Test if a variable is an entity.

Internally, the query engine has entity variables and table variables. When iterating through query variables (by using ecs_query_t::var_count) only the values for entity variables are accessible. This operation enables an application to check if a variable is an entity variable.

Parameters

  query | The query.
  var_id | The variable ID.

Returns
  Whether the variable is an entity variable.

## ◆ ecs_query_var_name()

const char * ecs_query_var_name | ( | const ecs_query_t * | query,
|  | int32_t | var_id )

Get the variable name.

This operation returns the variable name for an index.

Parameters

  query | The query.
  var_id | The variable index.

Returns
  The variable name.

## ◆ ecs_term_is_initialized()

bool ecs_term_is_initialized | ( | const ecs_term_t * | term | ) |

Test whether a term is set.

This operation can be used to test whether a term has been initialized with values or whether it is empty.

An application generally does not need to invoke this operation. It is useful when initializing a 0-initialized array of terms (like in ecs_query_desc_t), as this operation can be used to find the last initialized element.

Parameters

  term | The term.

Returns
  True when set, false when not set.

## ◆ ecs_term_match_0()

bool ecs_term_match_0 | ( | const ecs_term_t * | term | ) |

Is a term matched on a 0 source.

This operation checks whether a term is matched on a 0 source. A 0 source is a term that isn't matched against anything, and can be used just to pass (component) IDs to a query iterator.

A term has a 0 source when:

- ecs_term_t::src::id is 0
- ecs_term_t::src::flags has EcsIsEntity set

Parameters

  term | The term.

Returns
  True if the term has a 0 source, false if not.

## ◆ ecs_term_match_this()

bool ecs_term_match_this | ( | const ecs_term_t * | term | ) |

Is a term matched on the $this variable.

This operation checks whether a term is matched on the $this variable, which is the default source for queries.

A term has a $this source when:

- ecs_term_t::src::id is EcsThis
- ecs_term_t::src::flags is EcsIsVariable

If ecs_term_t::src is not populated, it will be automatically initialized to the $this source for the created query.

Parameters

  term | The term.

Returns
  True if the term matches $this, false if not.

## ◆ ecs_term_ref_is_set()

bool ecs_term_ref_is_set | ( | const ecs_term_ref_t * | ref | ) |

Test whether a term ref is set.

A term ref is a reference to an entity, component, or variable for one of the three parts of a term (src, first, second).

Parameters

  ref | The term ref.

Returns
  True when set, false when not set.

## ◆ ecs_term_str()

char * ecs_term_str | ( | const ecs_world_t * | world,
|  | const ecs_term_t * | term )

Convert a term to a string expression.

Convert a term to a string expression. The resulting expression is equivalent to the same term, with the exception of And and Or operators.

Parameters

  world | The world.
  term | The term.

Returns
  The term converted to a string.