Improve doc of some methods that take ranges #140983

tkr-sh · 2025-05-13T23:09:40Z

Some methods that were taking some range in parameter were a bit inconsistent / unclear in the panic documentation.

Here is the recap:

Replaced "start/end point" by "start/end bound" to be coherent with RangeBounds naming (it's also easier to understand I think)
Previously, it was written "[...] or if the end point is greater than the length of [...]", but this is not entirely true! Actually, you can have a start bound that is greater than the length, with an end bound that is unbounded and it will also panic. Therefore I think that "[...] one of the range bound is bounded and greater than the length of [...]" is better!
String methods weren't mentionning that the method panics if start_bound > end_bound but it actually does! It uses slice::range which panics when start > end. (https://doc.rust-lang.org/stable/src/alloc/string.rs.html#1932-1934, https://doc.rust-lang.org/stable/src/core/slice/index.rs.html#835-837).
You can also test it with:

struct MyRange;
impl std::ops::RangeBounds<usize> for MyRange {
    fn start_bound(&self) -> std::ops::Bound<&usize> {
        std::ops::Bound::Included(&3usize)
    }
    fn end_bound(&self) -> std::ops::Bound<&usize> {
        std::ops::Bound::Included(&1usize)
    }
}

fn main() {
    let mut s = String::from("I love Rust!");
    s.drain(MyRange); // panics!
}

rustbot · 2025-05-13T23:09:45Z

r? @ibraheemdev

rustbot has assigned @ibraheemdev.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

tkr-sh · 2025-05-13T23:11:18Z

@rustbot label +A-docs

library/alloc/src/collections/vec_deque/mod.rs

tkr-sh · 2025-05-27T07:52:13Z

r? @hkBst

rustbot · 2025-05-27T07:52:16Z

Failed to set assignee to hkBst: invalid assignee

Note: Only org members with at least the repository "read" role, users with write permissions, or people who have commented on the PR may be assigned.

hkBst

I'm happy with this.

library/alloc/src/collections/vec_deque/mod.rs

alex-semenyuk · 2025-08-10T06:57:25Z

@tkr-sh
Thanks for your contribution.
Form wg-triage. Any updates on this PR?

tgross35 · 2025-08-10T10:46:58Z

Please no emojis in commit messages

tkr-sh · 2025-08-10T10:47:38Z

hello @alex-semenyuk !
I just commited changes that should make this PR approved I think.
Sorry for the delay btw.

@rustbot review

rustbot · 2025-08-10T10:47:40Z

Requested reviewer is already assigned to this pull request.

Please choose another assignee.

tkr-sh · 2025-08-10T10:51:57Z

@tgross35 is there a guideline in the rustc dev book that says to not do that ? If not, I don't see any reason why I should not do it.

ibraheemdev · 2025-08-18T15:59:18Z

Could you please squash the commits? This looks good after that's done.

tgross35 · 2025-08-18T18:28:14Z

@tgross35 is there a guideline in the rustc dev book that says to not do that ? If not, I don't see any reason why I should not do it.

Ideally everything like that would be documented, but we assume that if things aren't mentioned then existing conventions will be followed. This is where reviewers come in :)

Dylan-DPC · 2025-09-19T10:56:55Z

@tkr-sh any updates on this? the only item pending is to squash the commits.

rustbot · 2025-09-20T10:18:42Z

This PR was rebased onto a different master commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

tkr-sh · 2025-09-20T10:21:53Z

@rustbot review

ibraheemdev · 2025-09-20T21:18:08Z

Thanks. @bors r+ rollup

bors · 2025-09-20T21:18:11Z

📌 Commit ac3c480 has been approved by ibraheemdev

It is now in the queue for this repository.

Improve doc of some methods that take ranges Some methods that were taking some range in parameter were a bit inconsistent / unclear in the panic documentation. Here is the recap: - Replaced "start/end point" by "start/end bound" to be coherent with [`RangeBounds`](https://doc.rust-lang.org/stable/std/ops/trait.RangeBounds.html) naming (it's also easier to understand I think) - Previously, it was written "_[...] or if the end point is greater than the length of [...]_", but this is not entirely true! Actually, you can have a start bound that is greater than the length, with an end bound that is unbounded and it will also panic. Therefore I think that "_[...] one of the range bound is bounded and greater than the length of [...]_" is better! - `String` methods weren't mentionning that the method panics if `start_bound > end_bound` but it actually does! It uses `slice::range` which panics when `start > end`. (https://doc.rust-lang.org/stable/src/alloc/string.rs.html#1932-1934, https://doc.rust-lang.org/stable/src/core/slice/index.rs.html#835-837). You can also test it with: ```rs struct MyRange; impl std::ops::RangeBounds<usize> for MyRange { fn start_bound(&self) -> std::ops::Bound<&usize> { std::ops::Bound::Included(&3usize) } fn end_bound(&self) -> std::ops::Bound<&usize> { std::ops::Bound::Included(&1usize) } } fn main() { let mut s = String::from("I love Rust!"); s.drain(MyRange); // panics! } ```

Rollup of 6 pull requests Successful merges: - #140983 (Improve doc of some methods that take ranges) - #144091 (Stabilize `new_zeroed_alloc`) - #145664 (Stabilize `std::panic::Location::file_as_c_str`) - #146744 (Deref related cleanups in ref_prop) - #146793 (naked_asm: emit a label starting with `func_end`) - #146822 (Fix old typo in lang_start_internal comment) r? `@ghost` `@rustbot` modify labels: rollup

Rollup of 8 pull requests Successful merges: - #140983 (Improve doc of some methods that take ranges) - #144091 (Stabilize `new_zeroed_alloc`) - #145664 (Stabilize `std::panic::Location::file_as_c_str`) - #146551 (fix issue with `cmse-nonsecure-entry` ABI being both async and c-variadic) - #146744 (Deref related cleanups in ref_prop) - #146793 (naked_asm: emit a label starting with `func_end`) - #146820 (Add unstable attribute to BTreeMap-related allocator generics) - #146822 (Fix old typo in lang_start_internal comment) r? `@ghost` `@rustbot` modify labels: rollup

Rollup merge of #140983 - tkr-sh:master, r=ibraheemdev Improve doc of some methods that take ranges Some methods that were taking some range in parameter were a bit inconsistent / unclear in the panic documentation. Here is the recap: - Replaced "start/end point" by "start/end bound" to be coherent with [`RangeBounds`](https://doc.rust-lang.org/stable/std/ops/trait.RangeBounds.html) naming (it's also easier to understand I think) - Previously, it was written "_[...] or if the end point is greater than the length of [...]_", but this is not entirely true! Actually, you can have a start bound that is greater than the length, with an end bound that is unbounded and it will also panic. Therefore I think that "_[...] one of the range bound is bounded and greater than the length of [...]_" is better! - `String` methods weren't mentionning that the method panics if `start_bound > end_bound` but it actually does! It uses `slice::range` which panics when `start > end`. (https://doc.rust-lang.org/stable/src/alloc/string.rs.html#1932-1934, https://doc.rust-lang.org/stable/src/core/slice/index.rs.html#835-837). You can also test it with: ```rs struct MyRange; impl std::ops::RangeBounds<usize> for MyRange { fn start_bound(&self) -> std::ops::Bound<&usize> { std::ops::Bound::Included(&3usize) } fn end_bound(&self) -> std::ops::Bound<&usize> { std::ops::Bound::Included(&1usize) } } fn main() { let mut s = String::from("I love Rust!"); s.drain(MyRange); // panics! } ```

Improve doc of some methods that take ranges Some methods that were taking some range in parameter were a bit inconsistent / unclear in the panic documentation. Here is the recap: - Replaced "start/end point" by "start/end bound" to be coherent with [`RangeBounds`](https://doc.rust-lang.org/stable/std/ops/trait.RangeBounds.html) naming (it's also easier to understand I think) - Previously, it was written "_[...] or if the end point is greater than the length of [...]_", but this is not entirely true! Actually, you can have a start bound that is greater than the length, with an end bound that is unbounded and it will also panic. Therefore I think that "_[...] one of the range bound is bounded and greater than the length of [...]_" is better! - `String` methods weren't mentionning that the method panics if `start_bound > end_bound` but it actually does! It uses `slice::range` which panics when `start > end`. (https://doc.rust-lang.org/stable/src/alloc/string.rs.html#1932-1934, https://doc.rust-lang.org/stable/src/core/slice/index.rs.html#835-837). You can also test it with: ```rs struct MyRange; impl std::ops::RangeBounds<usize> for MyRange { fn start_bound(&self) -> std::ops::Bound<&usize> { std::ops::Bound::Included(&3usize) } fn end_bound(&self) -> std::ops::Bound<&usize> { std::ops::Bound::Included(&1usize) } } fn main() { let mut s = String::from("I love Rust!"); s.drain(MyRange); // panics! } ```

Rollup of 8 pull requests Successful merges: - rust-lang#140983 (Improve doc of some methods that take ranges) - rust-lang#144091 (Stabilize `new_zeroed_alloc`) - rust-lang#145664 (Stabilize `std::panic::Location::file_as_c_str`) - rust-lang#146551 (fix issue with `cmse-nonsecure-entry` ABI being both async and c-variadic) - rust-lang#146744 (Deref related cleanups in ref_prop) - rust-lang#146793 (naked_asm: emit a label starting with `func_end`) - rust-lang#146820 (Add unstable attribute to BTreeMap-related allocator generics) - rust-lang#146822 (Fix old typo in lang_start_internal comment) r? `@ghost` `@rustbot` modify labels: rollup

Improve doc of some methods that take ranges Some methods that were taking some range in parameter were a bit inconsistent / unclear in the panic documentation. Here is the recap: - Replaced "start/end point" by "start/end bound" to be coherent with [`RangeBounds`](https://doc.rust-lang.org/stable/std/ops/trait.RangeBounds.html) naming (it's also easier to understand I think) - Previously, it was written "_[...] or if the end point is greater than the length of [...]_", but this is not entirely true! Actually, you can have a start bound that is greater than the length, with an end bound that is unbounded and it will also panic. Therefore I think that "_[...] one of the range bound is bounded and greater than the length of [...]_" is better! - `String` methods weren't mentionning that the method panics if `start_bound > end_bound` but it actually does! It uses `slice::range` which panics when `start > end`. (https://doc.rust-lang.org/stable/src/alloc/string.rs.html#1932-1934, https://doc.rust-lang.org/stable/src/core/slice/index.rs.html#835-837). You can also test it with: ```rs struct MyRange; impl std::ops::RangeBounds<usize> for MyRange { fn start_bound(&self) -> std::ops::Bound<&usize> { std::ops::Bound::Included(&3usize) } fn end_bound(&self) -> std::ops::Bound<&usize> { std::ops::Bound::Included(&1usize) } } fn main() { let mut s = String::from("I love Rust!"); s.drain(MyRange); // panics! } ```

rustbot assigned ibraheemdev May 13, 2025

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-libs Relevant to the library team, which will review and decide on the PR/issue. labels May 13, 2025

rustbot added the A-docs Area: Documentation for any part of the project, including the compiler, standard library, and tools label May 13, 2025

hkBst reviewed May 15, 2025

View reviewed changes

library/alloc/src/collections/vec_deque/mod.rs Outdated Show resolved Hide resolved

hkBst reviewed May 15, 2025

View reviewed changes

library/alloc/src/collections/vec_deque/mod.rs Show resolved Hide resolved

hkBst approved these changes May 27, 2025

View reviewed changes

tgross35 reviewed May 28, 2025

View reviewed changes

library/alloc/src/collections/vec_deque/mod.rs Outdated Show resolved Hide resolved

ibraheemdev requested changes Jun 15, 2025

View reviewed changes

library/alloc/src/collections/vec_deque/mod.rs Outdated Show resolved Hide resolved

rustbot added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Jun 15, 2025

This comment has been minimized.

Sign in to view

tkr-sh force-pushed the master branch from a8efc51 to 52f0b6a Compare August 10, 2025 10:40

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Aug 10, 2025

ibraheemdev added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Aug 19, 2025

tkr-sh force-pushed the master branch from 5c2a36e to f32d583 Compare September 20, 2025 10:14

This comment has been minimized.

Sign in to view

docs: improve doc of some methods w/ ranges

ac3c480

tkr-sh force-pushed the master branch from f32d583 to ac3c480 Compare September 20, 2025 10:18

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Sep 20, 2025

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Sep 20, 2025

tgross35 mentioned this pull request Sep 20, 2025

Rollup of 9 pull requests #146824

Closed

tgross35 mentioned this pull request Sep 20, 2025

Rollup of 6 pull requests #146825

Closed

Zalathar mentioned this pull request Sep 21, 2025

Rollup of 8 pull requests #146830

Merged

bors merged commit d253318 into rust-lang:master Sep 21, 2025
10 checks passed

rustbot added this to the 1.92.0 milestone Sep 21, 2025

Uh oh!

Improve doc of some methods that take ranges #140983

Improve doc of some methods that take ranges #140983

Uh oh!

Conversation

tkr-sh commented May 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rustbot commented May 13, 2025

Uh oh!

tkr-sh commented May 13, 2025

Uh oh!

Uh oh!

Uh oh!

tkr-sh commented May 27, 2025

Uh oh!

rustbot commented May 27, 2025

Uh oh!

hkBst left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

alex-semenyuk commented Aug 10, 2025

Uh oh!

This comment has been minimized.

tgross35 commented Aug 10, 2025

Uh oh!

tkr-sh commented Aug 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rustbot commented Aug 10, 2025

Uh oh!

tkr-sh commented Aug 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ibraheemdev commented Aug 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tgross35 commented Aug 18, 2025

Uh oh!

Dylan-DPC commented Sep 19, 2025

Uh oh!

This comment has been minimized.

rustbot commented Sep 20, 2025

Uh oh!

tkr-sh commented Sep 20, 2025

Uh oh!

ibraheemdev commented Sep 20, 2025

Uh oh!

bors commented Sep 20, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

tkr-sh commented May 13, 2025 •

edited

Loading

tkr-sh commented Aug 10, 2025 •

edited

Loading

tkr-sh commented Aug 10, 2025 •

edited

Loading

ibraheemdev commented Aug 18, 2025 •

edited

Loading