add note to `lines` docs about empty str behavior#148912

msmoiz · 2025-11-13T16:43:14Z

This pull request adds a short note to the documentation for str::lines that describes the behavior of the resulting iterator when called on an empty string. I tripped over this a few days ago because I thought (incorrectly) that the iterator would return a single line with an empty string. I don't doubt that the actual behavior (return no lines) is the correct behavior, but in the absence of explicit documentation describing it, I came to the wrong conclusion about it and maybe others will too. If this is so obvious as to be not worth including, I'm happy to withdraw the pull request! Thanks for taking a look.

rustbot · 2025-11-13T16:43:19Z

r? @scottmcm

rustbot has assigned @scottmcm.
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

Kivooeo · 2025-11-13T17:09:27Z

library/core/src/str/mod.rs

    /// ending will return the same lines as an otherwise identical string
    /// without a final line ending.
    ///
+    /// An empty string returns no lines.


imho, "no lines" feels not obvious what does that mean, like, would it be better to have wording like "returns None"?

Hmm, I think that might be a bit confusing since the method itself returns a Lines object instead of an Option and saying "returns None" makes it sound like it returns an Option. A few possible alternatives:

"An empty string returns an empty iterator"

"Returns an empty iterator when called on an empty string"

"Empty strings produce no lines"

Ah, sure it's an iterator

Empty iterator instead None then, should be clear enough

Okay cool, updated

scottmcm · 2025-11-17T03:47:59Z

Sounds good -- agreed this is really useful to have as an explicit # Example.

@bors r+ rollup

bors · 2025-11-17T03:48:02Z

📌 Commit e628b05 has been approved by scottmcm

It is now in the queue for this repository.

add note to `lines` docs about empty str behavior This pull request adds a short note to the documentation for `str::lines` that describes the behavior of the resulting iterator when called on an empty string. I tripped over this a few days ago because I thought (incorrectly) that the iterator would return a single line with an empty string. I don't doubt that the actual behavior (return no lines) is the correct behavior, but in the absence of explicit documentation describing it, I came to the wrong conclusion about it and maybe others will too. If this is so obvious as to be not worth including, I'm happy to withdraw the pull request! Thanks for taking a look.

Rollup of 11 pull requests Successful merges: - #148505 (add larger test for `proc_macro` `FromStr` implementations) - #148752 (Constify `ManuallyDrop::take`) - #148757 (Constify `mem::take`) - #148855 (Error if an autodiff user does not set lto=fat) - #148912 (add note to `lines` docs about empty str behavior) - #148958 (Run codegen tests on a 32-bit target in PR CI) - #148994 (Abi compatibility test cleanup) - #148999 (Tweak Motor OS linker preset, fix `remote-test-server` for Motor OS) - #149004 (compiletest: Avoid race condition in file deletion) - #149008 (triagebot: remove jsha from notifications for rustdoc HTML) - #149010 (compiletest: Remove the "wasm32-bare" alias for `wasm32-unknown-unknown`) r? `@ghost` `@rustbot` modify labels: rollup

Rollup merge of #148912 - msmoiz:main, r=scottmcm add note to `lines` docs about empty str behavior This pull request adds a short note to the documentation for `str::lines` that describes the behavior of the resulting iterator when called on an empty string. I tripped over this a few days ago because I thought (incorrectly) that the iterator would return a single line with an empty string. I don't doubt that the actual behavior (return no lines) is the correct behavior, but in the absence of explicit documentation describing it, I came to the wrong conclusion about it and maybe others will too. If this is so obvious as to be not worth including, I'm happy to withdraw the pull request! Thanks for taking a look.

Rollup of 11 pull requests Successful merges: - rust-lang/rust#148505 (add larger test for `proc_macro` `FromStr` implementations) - rust-lang/rust#148752 (Constify `ManuallyDrop::take`) - rust-lang/rust#148757 (Constify `mem::take`) - rust-lang/rust#148855 (Error if an autodiff user does not set lto=fat) - rust-lang/rust#148912 (add note to `lines` docs about empty str behavior) - rust-lang/rust#148958 (Run codegen tests on a 32-bit target in PR CI) - rust-lang/rust#148994 (Abi compatibility test cleanup) - rust-lang/rust#148999 (Tweak Motor OS linker preset, fix `remote-test-server` for Motor OS) - rust-lang/rust#149004 (compiletest: Avoid race condition in file deletion) - rust-lang/rust#149008 (triagebot: remove jsha from notifications for rustdoc HTML) - rust-lang/rust#149010 (compiletest: Remove the "wasm32-bare" alias for `wasm32-unknown-unknown`) r? `@ghost` `@rustbot` modify labels: rollup

add note to `lines` docs about empty str behavior This pull request adds a short note to the documentation for `str::lines` that describes the behavior of the resulting iterator when called on an empty string. I tripped over this a few days ago because I thought (incorrectly) that the iterator would return a single line with an empty string. I don't doubt that the actual behavior (return no lines) is the correct behavior, but in the absence of explicit documentation describing it, I came to the wrong conclusion about it and maybe others will too. If this is so obvious as to be not worth including, I'm happy to withdraw the pull request! Thanks for taking a look.

Rollup of 11 pull requests Successful merges: - rust-lang#148505 (add larger test for `proc_macro` `FromStr` implementations) - rust-lang#148752 (Constify `ManuallyDrop::take`) - rust-lang#148757 (Constify `mem::take`) - rust-lang#148855 (Error if an autodiff user does not set lto=fat) - rust-lang#148912 (add note to `lines` docs about empty str behavior) - rust-lang#148958 (Run codegen tests on a 32-bit target in PR CI) - rust-lang#148994 (Abi compatibility test cleanup) - rust-lang#148999 (Tweak Motor OS linker preset, fix `remote-test-server` for Motor OS) - rust-lang#149004 (compiletest: Avoid race condition in file deletion) - rust-lang#149008 (triagebot: remove jsha from notifications for rustdoc HTML) - rust-lang#149010 (compiletest: Remove the "wasm32-bare" alias for `wasm32-unknown-unknown`) r? `@ghost` `@rustbot` modify labels: rollup

add note to lines docs about empty str behavior

4996edc

rustbot assigned scottmcm Nov 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 Nov 13, 2025

Kivooeo reviewed Nov 13, 2025

View reviewed changes

update language from "no lines" to "empty iterator"

e628b05

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 Nov 17, 2025

JaclynCodes mentioned this pull request Nov 17, 2025

Rollup of 8 pull requests #149011

Closed

Zalathar mentioned this pull request Nov 17, 2025

Rollup of 8 pull requests #149012

Closed

Zalathar mentioned this pull request Nov 17, 2025

Rollup of 11 pull requests #149013

Merged

bors merged commit 47585c9 into rust-lang:main Nov 17, 2025
11 checks passed

rustbot added this to the 1.93.0 milestone Nov 17, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

add note to `lines` docs about empty str behavior#148912