User experience of Url::join is surprising

[schneems]

The name "join" implies an addition to the existing URL, while the API https://docs.rs/url/latest/url/struct.Url.html#method.join will replace/reduce the original url. I find this behavior to be surprising:

let base = Url::parse("https://alice.com/a")?;
let url = base.join("//eve.com/b")?;
assert_eq!(url.as_str(), "https://eve.com/b")

let base = Url::parse("https://alice.com/a")?;
let url = base.join("/v1/meta")?;
assert_eq!(url.as_str(), "https://alice.com/v1/meta");

The behavior I want when reaching for a "join" api is best represented by the mutable push syntax:

url.path_segments_mut()
    .expect("valid base URL")
    .push(base_image.name())
    .push(&tgz_name);

However. Even having written similar code many times. I still sometimes accidentally use Url::join by habit, as coming from other languages such as Ruby's File.join, and when I didn't carefully consider one of the variants of inputs, I have to spend significant time debugging to figure out why the program doesn't behave the way I anticipated/expected.

Suggestions

The above isn't really a bug as the code is behaving as expected/documented. But the user experience of the API is quite difficult; it requires the developer to consider all possible variants when using it. Things like prepending a slash to a path in code might be common, and a change to the input might have it already have a slash, and then suddenly the behavior of the join call changes (as there would be two slashes).

As this API has been around for a long time, I don't suggest changing the behavior, as that would break existing code. However, possibly deprecating the function to guard against accidental use could be an option.