Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Mention in docs about the query iteration order and result uniqueness. #12400

Merged
merged 3 commits into from
Mar 11, 2024

Conversation

james7132
Copy link
Member

Objective

Fix #10876. Improve Query and QueryState's docs.

Solution

Explicitly denote that Query is always guaranteed to return results from all matching entities once and only once for each entity, and that iteration order is not guaranteed in any way.

@james7132 james7132 added C-Docs An addition or correction to our documentation A-ECS Entities, components, systems, and events labels Mar 10, 2024
@james7132 james7132 changed the title Mention in docs about the query iteration order and result uniquness. Mention in docs about the query iteration order and result uniqueness. Mar 10, 2024
@@ -730,6 +730,9 @@ impl<D: QueryData, F: QueryFilter> QueryState<D, F> {
}

/// Returns an [`Iterator`] over the query results for the given [`World`].
///
/// This iterator is always guaranteed to return results from each matching entity once and only once.
/// Iteration order is not guaranteed.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was curious about this: Is the iteration order random at some length? Or do it choose as first some archetypes rather than others?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Right now it's in archetype ID order, but adding and removing components moves entities around both on tables and archetypes.

The exact iteration order should not be mentioned as it's not guaranteed in any form and subject to change at any time.

@mockersf mockersf added the S-Ready-For-Final-Review This PR has been approved by the community. It's ready for a maintainer to consider merging it label Mar 11, 2024
@mockersf mockersf added this pull request to the merge queue Mar 11, 2024
Merged via the queue into bevyengine:main with commit 879b170 Mar 11, 2024
26 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-ECS Entities, components, systems, and events C-Docs An addition or correction to our documentation S-Ready-For-Final-Review This PR has been approved by the community. It's ready for a maintainer to consider merging it
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Query.iter does not indicate that it iterates over unique entities
4 participants