std::path::Path::starts_with documentation unclear

[0X1A]

The current documentation for std::path::Path::starts_with does not specify that it uses components as base. For example as described in the current documentation I expected to be able to use characters as base to find hidden files/directories as such:

fn is_dot(dir: &PathBuf) -> bool {
    if dir.starts_with(".") {
        return true;
    } else {
        return false
    }
}

fn main() {
    let path = PathBuf::from("/home/user/.dotfile");
    let rel_path = path.relative_from("/home/user").unwrap();
    println!("{}", path.display());
    println!("{}", rel_path.display());
    if is_dot(&PathBuf::from(rel_path)) {
        println!("{} is dot", rel_path.display());
    }
}

As described in the documentation I expected is_dot(&PathBuf::from(rel_path)) to be evaluated as true when it does not

[steveklabnik]

Huh. This is very strange. @alexcrichton do you have any insight here?

[alexcrichton]

Yes this is because everything's based around the iterators which need to be consumes exhaustively for matches like this to return true. I have also been bitten by this in the past though!

cc @aturon

[aturon]

The way I look at it is that the path API works with parsed, normalized paths, which consist of a number of components (between path separators). The entire API surface works this way. So starts_with, for example, implies that you could use join to get from the base path to the extended path -- and join likewise works at the component level, inserting a separator for each call.

I would rather add a starts_with method to OsStr, and then you can use as_os_str() to drop from a path view to a string view when you want that functionality.

[0X1A]

@aturon I think a starts_with in OsStr that behaves like that of str's as you described would be very helpful. I still think the documentation for Path's starts_with should be more clear on how it operates using path components

[lilyball]

I agree with @aturon, the current behavior of starts_with is correct, it just needs better documentation and perhaps a separate starts_with added to OsStr.