Update canonicalize docs by Screwtapello · Pull Request #50602 · rust-lang/rust (original) (raw)

I was recently working with file-paths in Rust, and I felt let down by the std::fs::canonicalize docs, so I figured I should submit a PR with some suggestions.

I was looking for a method to turn a relative path into an absolute path. The canonicalize docs didn't mention the words "relative" or "absolute", but they did mention resolving symlinks (which is a kind of canonicalisation and does not imply converting to absolute), so I assumed that's all it did. To remedy this, I've added the word "absolute" to the description of both std::fs::canonicalize and std::path::Path::canonicalize.

After calling canonicalize on Windows, I ran into a bunch of other problems I would not have expected from the function's behaviour on Linux. Specifically, if you call canonicalize on a path:

• it's allowed to be much longer than it otherwise would
• .join("a/slash/delimited/path") gives you a broken path that Windows can't use, where the same operation would have worked perfectly without canonicalize (if the path were short enough)
• the resulting path may confuse other Windows programs if you pass it to them on the command-line, or write it to a config file that they read, etc.

...so I tried to summarize those behaviours too.

If I understand correctly, those behaviours are a side-effect of calling GetFinalPathNameByHandle, and the documentation says canonicalize might not call that function in future, so maybe those side-effects shouldn't be part of the function's documentation. However, I bet there's a lot of applications deliberately calling canonicalize just for the path-length-extension alone, so that particular side-effect is de-facto part of the canonicalize interface.