Add std::path::Path::ancestors

[teiesti]

Tracking issue: #48581

This pull request adds a method called parents ancestors to std::path::Path. parents ancestors is a generalized version of parent. While parent returns the path without its final component, parents ancestors returns an iterator that yields every ancestor. This includes the path itself, the parent, the grandparent and so on. This is done by repeatedly calling parent. In case parent returns None, the iterator returned by parents ancestors does likewise.

Why is such a method useful?
A method like parents ancestors is especially useful, if a task has to be done for the current directory and every directory up the tree. (Think of Cargo searching for the Cargo.toml!)

Why does the iterator yield the original path instead of starting with the parent?
It is easier to skip the original path with .skip(1) than it is to add the original path if necessary.

Why is the method called parents instead of ancestors?
When sorted , parents comes right after parent. It is therefore grouped with its more specific counterpart within the documentation.

Why is the method called ancestors instead of parents?

1. As @alexcrichton pointed out, Cargo has a similar method called ancestors.
2. As @sfackler pointed out, it might be weird that an iterator called Ancestor yields the current path. It is more reasonable that the current path is a "null ancestor" than a "null parent".
3. As @zackmdavis pointed out, the name parents might be misleading.

Two more notes:

1. Since this is my first contribution to the standard library, I am actually not sure if an RFC is required!
2. Since I am not a native speaker, someone should double-check my English!

[nagisa]

This hasn’t been assigned a reviewer, so assigning first person from T-libs, I can think of

r? @BurntSushi

[BurntSushi]

It might be useful to explicitly clarify here that the iterator returned will always yield at least one value.

[BurntSushi]

I do agree with the utility of this function, and I've certainly had to write this iterator out by hand before.

So I think this seems fine to me, but let's see if anyone has any objections before merging. cc @rust-lang/libs

[teiesti]

This line raises two open questions for me:

1. Is the feature name appropriate?
2. What issue number can I use?

[BurntSushi]

The feature name seems OK to me, as long as it is distinct from any other feature name. :-)

I believe that if we decide to merge this, you need to create a tracking issue for stabilizing this feature, and that's the number that goes here.

I also think there is some docs where features are documented. But I don't know where it is.

[alexcrichton]

Sounds like a great idea to me! We've actually got basically this method already in Cargo

[sfackler]

The name parents seems a bit weird given that the path itself is included, but I agree that behavior seems reasonable. I can't really think of a better name though :(

[zackmdavis]

When sorted , parents comes right after parent. It is therefore grouped with its more specific counterpart within the documentation.

This seems like a weak justification for choosing parents over ancestors. (Before reading the description, I expected parents to somehow reverse-follow hardlinks to yield all immediate-parent directories that linked the same file. I also have an easier time accepting the path itself as the "null ancestor" than as the "null parent".) If we just want someone reading the documentation of one method to be made aware of the other, a "See also .parents()" link should suffice.

[teiesti]

I like these arguments. I will prepare a commit that changes the name to ancestors.

[eav]

maybe paths() ?

[teiesti]

I think, paths is a little bit too generic. Someone could believe that a methods called paths creates an iterator that descends through all the paths in a directory just like the walkdir crate does.

[eav]

well, I think the name should be more or less generic, because it lists all paths, documentation should clarify the meaning though, another option segments

[teiesti]

well, I think the name should be more or less generic, because it lists all paths

The method does not list all paths at all. It lists all paths that are ancestors of self. This might sound like a small distinction but it is actually crucial. Consider the following directory structure:

/
└── grandparent
    ├── aunt
    └── parent
        ├── self
        │   ├── child1
        │   │   └── grandchild
        │   └── child2
        └── silbling

Calling ancestors on self would lead to

/grandparent/parent/self
/grandparent/parent
/grandparent
/

while all paths would (in my understanding of the term) be something like

/
/grandparent
/grandparent/parent
/grandparent/parent/self
/grandparent/parent/self/child1
/grandparent/parent/self/child1/grandchild
/grandparent/parent/self/child2
/grandparent/parent/silbling
/grandparent/aunt

another option segments

In my opinion, something like parent/self would also be a segment.

@eav I really appreciate your ideas! But what is so wrong with ancestors?

[BurntSushi]

Either ancestors or parents seem suitable to me. I'm opposed to paths. Let's move on from it. The name can be further debated during stabilization.

[BurntSushi]

@teiesti Could you squash this down to one commit? Then I think this should be good to go!

[teiesti]

@BurntSushi Done.

[eav]

for me parents or ancestors sound like they return paths without self

/grandparent/parent
/grandparent
/

[BurntSushi]

@bors r+

[bors]

📌 Commit b9e9b4a has been approved by BurntSushi

[BurntSushi]

@teiesti Thanks!

@eav But neither paths nor segments are clearly better. The concept of "something is its own parent" is common enough that it's not an entirely arcane meaning, and in the absence of a better name, it seems appropriate. Let's please move naming discussion to the tracking issue.