Rename get_many() to many(), making it consistent with single()

[BD103]

Objective

There is a pretty glaring inconsistency between Query::single() and Query::get_many()'s naming. Although they both return a Result, the later was not renamed into many(). This inconsistency is problematic because it makes it more difficult to developers to understand what it's doing.

Here's an example: across the Rust ecosystem, it's pretty much standard for conversion methods starting with as_ to be cheap, while methods starting with to_ to be expensive. (See str::as_bytes() vs. Path::to_str().) This is documented in the Rust API Guidelines, and is considered "good practice".

Bevy also has its own conventions and practices, I even wrote bevy_lint to help enforce these. Before better error handling was introduced, we had the following convention for panicking methods: get_foo() returned a Result, while foo() panicked. There are 17 examples of this in World, Query, and QueryState alone.

With Bevy 0.16, this convention is being changed. The panicking methods of old are no longer a thing, having been deprecated or replaced. Query::single() now returns a Result instead of panicking, with the old Query::get_single() being deprecated as an alias. This treatment wasn't given to Query::many(), however, because "folks weren't sold on the name many (get_many is clearer, and this is rare), and that PR is much more complex" (#18183).

Yes, the name get_many() is clearer that it returns a Result, but so is get_single()! Why should one method be given the ✨special✨ treatment just because it is more useful? There are too many parallels between single() and many() to cause such a large rift like this. For example, look at the Accessing query items table:

Even the wording is the same! The only differences are making "item" and "entity" plural.

So here's my point: developers will see the similarity between single() and get_many(), but will be confused why their naming is different when the do the exact same thing.

For additional context, see #18120 and #18183.

Solution

• Delete the original panicking many() and many_mut().
• Rename all get_many_*() methods (including get_many() and get_many_mut()) to many_*().
• Create a new version of get_many() and get_many_mut() that are simply deprecated aliases to many() and many_mut(). (This is not needed for get_many_unique_mut() and friends because they are a new addition to 0.16.)
• Fix all leftover references to get_many() and friends.

Testing

I relied heavily on cargo check, cargo test, and ripgrep to verify my changes were thorough. CI should catch anything I missed, but feel free to do you own checks!

---

Migration Guide

This migration guide should be merged with the original one that make Query::single() return a Result, and will replace #18183's migration guide.

Query::many() and Query::many_mut() (and the QueryState versions) now return a Result instead of panicking. Query::get_many() and Query::get_many_mut() are now deprecated.

[github-actions]

It looks like your PR is a breaking change, but you didn't provide a migration guide.

Please review the instructions for writing migration guides, then expand or revise the content in the migration guides directory to reflect your changes.

[alice-i-cecile]

You missed some in doc tests :) I'm going to mark this as X-Controversial. I'm in favor of this, but reverted it due to pushback in the linked PR.

[NthTensor]

I'm personally on side get_many/get_single rather than many/single, because it organizes all the accessors under the get_ prefix. But what matters here is consistency, so I'll take either.

[Victoronz]

My issue with this is that many should not be seen as a counterpart to single, but as a counterpart to get.
The name single is a bevy convention, and as a name and functionality, doesn't directly exist in std.
get_many is a name taken originally from slice::get_many_mut (there is no immutable counterpart in the stdlib).

Their names are counterparts in natural language, but that is not quite the case here! get/get_many more so align with iter/iter_many.

As an example, you show the docs of Query, but show get and get_many. I think my argument is clearer when including single in it:

get is "give me x"
get_many is "give me x, y, z in an array"

single more so represents "if length is 1, give me that item"

As a sidenote, the docs for Query are outdated, they should be updated with the new API surface.

[BD103]

My issue with this is that many should not be seen as a counterpart to single, but as a counterpart to get.
The name single is a bevy convention, and as a name and functionality, and doesn't directly exist in std.
get_many is a name taken originally from slice::get_many_mut (there is no immutable counterpart in the stdlib).

Honestly, I'm convinced. The image I included even supports your argument lol; I must've been tired while writing up this PR.

In that case, I think this is a major documentation problem. We currently present single() and get_many() side-by-side, when really it should be get() and get_many(). I'm going to close this, then try to improve the docs as best as I can.