ACP: `Path::is_empty`

[ChrisDenton]

Proposal

Problem statement

There's not a straight forward way to check if a path is empty.

Motivating examples or use cases

An empty path is almost never valid. For example, passing it to most OS filesystem APIs will always result in an error. Moreover it is a potential footgun when joining paths. At most it will append a /, otherwise it's a no-op. This can be a (albeit limited) form of path traversal attack, like . or .. where you end up addressing the parent instead of the child you assumed.

Solution sketch

impl Path {
   fn is_empty(&self) -> bool;
}

This is just a helper; it does not add anything that can't be done today (see alternatives). It is however more convenient and provides a place to hang some documentation on the issue.

Alternatives

Don't add this. There is already path.components().next().is_none() and path.as_os_str().is_empty().

Links and related work

This was previously rejected back in 2016, see rust-lang/rust#31877 (comment).

Querying a Path should exclusively go through the components iterator as that's basically how a path is always interpreted. Querying the backing storage can always be done via as_os_str (as pointed out), and that's likely good enough for now.

Put another way, testing whether a path is empty by looking at the length of the underlying bytes is probably "just the wrong question to ask", and instead the components iterator should be queried to see if it's empty.

But I'm not aware of a case where components would return empty but as_os_str wouldn't (or vice versa). Please do correct me if I'm wrong.

Github shows ~8.3k results for .as_os_str().is_empty(). While not all of them may be to do with Path, from my cursory look it does seem Path dominates the results.

What happens now?

This issue contains an API change proposal (or ACP) and is part of the libs-api team feature lifecycle. Once this issue is filed, the libs-api team will review open proposals as capability becomes available. Current response times do not have a clear estimate, but may be up to several months.

Possible responses

The libs team may respond in various different ways. First, the team will consider the problem (this doesn't require any concrete solution or alternatives to have been proposed):

• We think this problem seems worth solving, and the standard library might be the right place to solve it.
• We think that this probably doesn't belong in the standard library.

Second, if there's a concrete solution:

• We think this specific solution looks roughly right, approved, you or someone else should implement this. (Further review will still happen on the subsequent implementation PR.)
• We're not sure this is the right solution, and the alternatives or other materials don't give us enough information to be sure about that. Here are some questions we have that aren't answered, or rough ideas about alternatives we'd want to see discussed.

[sskyblue1010]

Here is a concise proposal problem statement you can use, with sections aligned to a typical ACP (API Change Proposal) structure. It preserves your core ideas while clarifying scope, impact, and evaluation.Title Proposal to add Path::is_empty to the standard library path APIProblem statement There is no straightforward, canonical way to determine whether a path is empty. Current methods rely on inspecting internal representations (e.g., length checks on the underlying OS string) or using the components iterator in a way that is not as explicit or discoverable as a dedicated API. This can lead to inconsistent usage, reduced readability, and potential edge-case mistakes when validating paths before performing filesystem operations.MotivationClarity: A direct is_empty method expresses the intent clearly, improving code readability.Safety: A dedicated check provides a single place to document the semantics and edge cases, reducing the risk of misinterpretation when a path is empty.Consistency: Encourages uniform handling of empty paths across the standard library APIs and downstream crates.Documentation: A dedicated API offers a convenient hook to document the exact semantics (e.g., what counts as “empty” in different platforms, encoding considerations, and interaction with components).ScopeAdd a method to Path (or the appropriate path-type in the standard library) with signature similar to: fn is_empty(&self) -> bool;Semantics: Return true if the path has no components; equivalent behavior should align with path.components().next().is_none()Runtime behavior: No allocation; O(1) in the number of components scanned; consistent with existing path APIs.Compatibility: Must not change existing behavior or APIs for non-empty paths; provide a clear deprecation or migration path if any existing edge-case behavior relies on underlying length/bytes directly.Proposed solutionImplement Path::is_empty(&self) -> bool that delegates to path.components().next().is_none().Document the semantics thoroughly, including:How this interacts with absolute vs. relative paths.Behavior on platform-specific path representations (e.g., NUL bytes, separators).Interaction with paths that are syntactically non-empty but contain only meaningless components (if such cases exist on a given platform).Consider an accompanying lint or guidance in documentation to discourage reliance on backing storage length for emptiness checks, guiding users toward using is_empty for clarity.AlternativesDo nothing: Rely on existing primitives (path.components().next().is_none() or path.as_os_str().is_empty()).Add a more specialized method, such as Path::is_nonempty, if the primary need is a negative check, though is_empty is typically more idiomatic.Introduce a trait-based approach for path emptiness in crates outside the standard library, to avoid API surface growth.Impact analysisAPI surface: Adds one method to Path; minimal impact.Maintenance: Requires adding tests across platforms to ensure consistent semantics.Security: Reduces footguns by making emptiness explicit; no new exposure of otherwise sensitive internals.Compatibility: Should be a non-breaking addition; existing code will continue to work as before.Proposed evaluation criteriaCorrectness: is_empty() returns true exactly when path.components().next().is_none().Ergonomics: Developer feedback indicates improved clarity and reduced boilerplate in common patterns.Performance: Constant time check; no significant overhead.Compatibility: No breaking changes; clear upgrade path for users who rely on internal length checks.Implementation notesMirror existing conventions in the standard library for naming and documentation style.Ensure tests cover edge cases such as root paths, empty paths, and paths with only redundant components.Include cross-platform tests to verify consistent behavior with components iteration.Questions for discussion (to accompany the proposal)Is there any platform-specific nuance where is_empty could diverge from components().next().is_none()?Should the method be added as a method on Path or as a trait extension to allow optional behind-feature gating?How should doc comments express the semantics for callers who might rely on underlying encoding or OS-specific behaviors?If you’d like, I can tailor this into a formal pull request description or CRED (Rust Lang-style) ACP format with sections labeled exactly as the Rust community expects, including a proposed PR title, motivation, rationale, and a concrete test plan. SS sky Blue 🔵

…

On Fri, Oct 31, 2025, 10:56 Chris Denton ***@***.***> wrote: *ChrisDenton* created an issue (rust-lang/libs-team#687) <#687> Proposal Problem statement There's not a straight forward way to check if a path is empty. Motivating examples or use cases An empty path is almost never valid. For example, passing it to most OS filesystem APIs will always result in an error. Moreover it is a potential footgun when joining paths. At most it will append a /, otherwise it's a no-op. This can be a (albeit limited) form of path traversal attack, like . or .. where you end up addressing the parent instead of the child you assumed. Solution sketch impl Path { fn is_empty(&self) -> bool;} This is just a helper; it does not add anything that can't be done today (see alternatives). It is however more convenient and provides a place to hang some documentation on the issue. Alternatives Don't add this. There is already path.components().next().is_none() and path.as_os_str().is_empty(). Links and related work This was previously rejected back in 2016, see rust-lang/rust#31877 (comment) <rust-lang/rust#31877 (comment)>. Querying a Path should exclusively go through the components iterator as that's basically how a path is always interpreted. Querying the backing storage can always be done via as_os_str (as pointed out), and that's likely good enough for now. Put another way, testing whether a path is empty by looking at the length of the underlying bytes is probably "just the wrong question to ask", and instead the components iterator should be queried to see if it's empty. But I'm not aware of a case where components would return empty but as_os_str wouldn't (or vice versa). Please do correct me if I'm wrong. What happens now? This issue contains an API change proposal (or ACP) and is part of the libs-api team feature lifecycle <https://std-dev-guide.rust-lang.org/development/feature-lifecycle.html>. Once this issue is filed, the libs-api team will review open proposals as capability becomes available. Current response times do not have a clear estimate, but may be up to several months. Possible responses The libs team may respond in various different ways. First, the team will consider the *problem* (this doesn't require any concrete solution or alternatives to have been proposed): - We think this problem seems worth solving, and the standard library might be the right place to solve it. - We think that this probably doesn't belong in the standard library. Second, if there's a concrete solution: - We think this specific solution looks roughly right, approved, you or someone else should implement this. (Further review will still happen on the subsequent implementation PR.) - We're not sure this is the right solution, and the alternatives or other materials don't give us enough information to be sure about that. Here are some questions we have that aren't answered, or rough ideas about alternatives we'd want to see discussed. — Reply to this email directly, view it on GitHub <#687>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BNI3L3KARKPMGQRUWJKM3XD32MW3HAVCNFSM6AAAAACKYHHOLCVHI2DSMVQWIX3LMV43ASLTON2WKOZTGU3TIMRRGE3DGOA> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[programmerjake]

@sskyblue1010 thanks for your effort but the ACP is already fine as written. @ChrisDenton is already quite familiar with the requirements for writing ACPs since they've written quite a few already over the last several years: https://github.com/rust-lang/libs-team/issues?q=is%3Aissue%20author%3Achrisdenton

[Amanieu]

Accepted in @rust-lang/libs-api meeting.

Please open a tracking issue and open a PR to rust-lang/rust to add it as an unstable feature. You can close this ACP once the tracking issue has been created.

[ChrisDenton]

Tracking issue: rust-lang/rust#148494