Skip to content

Commit

Permalink
Document possible replacements of the base URL (#926)
Browse files Browse the repository at this point in the history
  • Loading branch information
mo8it authored Apr 15, 2024
1 parent 8b8431b commit de947ab
Showing 1 changed file with 23 additions and 2 deletions.
25 changes: 23 additions & 2 deletions url/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -219,6 +219,9 @@ pub struct ParseOptions<'a> {

impl<'a> ParseOptions<'a> {
/// Change the base URL
///
/// See the notes of [`Url::join`] for more details about how this base is considered
/// when parsing.
pub fn base_url(mut self, new: Option<&'a Url>) -> Self {
self.base_url = new;
self
Expand Down Expand Up @@ -370,24 +373,42 @@ impl Url {
///
/// The inverse of this is [`make_relative`].
///
/// Note: a trailing slash is significant.
/// # Notes
///
/// - A trailing slash is significant.
/// Without it, the last path component is considered to be a “file” name
/// to be removed to get at the “directory” that is used as the base:
/// to be removed to get at the “directory” that is used as the base.
/// - A [scheme relative special URL](https://url.spec.whatwg.org/#scheme-relative-special-url-string)
/// as input replaces everything in the base URL after the scheme.
/// - An absolute URL (with a scheme) as input replaces the whole base URL (even the scheme).
///
/// # Examples
///
/// ```rust
/// use url::Url;
/// # use url::ParseError;
///
/// // Base without a trailing slash
/// # fn run() -> Result<(), ParseError> {
/// let base = Url::parse("https://example.net/a/b.html")?;
/// let url = base.join("c.png")?;
/// assert_eq!(url.as_str(), "https://example.net/a/c.png"); // Not /a/b.html/c.png
///
/// // Base with a trailing slash
/// let base = Url::parse("https://example.net/a/b/")?;
/// let url = base.join("c.png")?;
/// assert_eq!(url.as_str(), "https://example.net/a/b/c.png");
///
/// // Input as scheme relative special URL
/// let base = Url::parse("https://alice.com/a")?;
/// let url = base.join("//eve.com/b")?;
/// assert_eq!(url.as_str(), "https://eve.com/b");
///
/// // Input as absolute URL
/// let base = Url::parse("https://alice.com/a")?;
/// let url = base.join("http://eve.com/b")?;
/// assert_eq!(url.as_str(), "http://eve.com/b"); // http instead of https

/// # Ok(())
/// # }
/// # run().unwrap();
Expand Down

0 comments on commit de947ab

Please sign in to comment.