url

url

rust-url is an implementation of the URL Standard for the Rust programming language.

URL parsing and data structures

First, URL parsing may fail for various reasons and therefore returns a Result.

use url::{Url, ParseError};

assert!(Url::parse("http://[:::1]") == Err(ParseError::InvalidIpv6Address))
Run

Let’s parse a valid URL and look at its components.

use url::{Url, Host, Position};
let issue_list_url = Url::parse(
    "https://github.com/rust-lang/rust/issues?labels=E-easy&state=open"
)?;


assert!(issue_list_url.scheme() == "https");
assert!(issue_list_url.username() == "");
assert!(issue_list_url.password() == None);
assert!(issue_list_url.host_str() == Some("github.com"));
assert!(issue_list_url.host() == Some(Host::Domain("github.com")));
assert!(issue_list_url.port() == None);
assert!(issue_list_url.path() == "/rust-lang/rust/issues");
assert!(issue_list_url.path_segments().map(|c| c.collect::<Vec<_>>()) ==
        Some(vec!["rust-lang", "rust", "issues"]));
assert!(issue_list_url.query() == Some("labels=E-easy&state=open"));
assert!(&issue_list_url[Position::BeforePath..] == "/rust-lang/rust/issues?labels=E-easy&state=open");
assert!(issue_list_url.fragment() == None);
assert!(!issue_list_url.cannot_be_a_base());
Run

Some URLs are said to be cannot-be-a-base: they don’t have a username, password, host, or port, and their "path" is an arbitrary string rather than slash-separated segments:

use url::Url;

let data_url = Url::parse("data:text/plain,Hello?World#")?;

assert!(data_url.cannot_be_a_base());
assert!(data_url.scheme() == "data");
assert!(data_url.path() == "text/plain,Hello");
assert!(data_url.path_segments().is_none());
assert!(data_url.query() == Some("World"));
assert!(data_url.fragment() == Some(""));
Run

Default Features

Versions <= 2.5.2 of the crate have no default features. Versions > 2.5.2 have the default feature 'std'. If you are upgrading across this boundary and you have specified default-features = false, then you will need to add the 'std' feature or the 'alloc' feature to your dependency. The 'std' feature has the same behavior as the previous versions. The 'alloc' feature provides no_std support.

Serde

Enable the serde feature to include Deserialize and Serialize implementations for url::Url.

Base URL

Many contexts allow URL references that can be relative to a base URL:

<link rel="stylesheet" href="../main.css">

Since parsed URLs are absolute, giving a base is required for parsing relative URLs:

use url::{Url, ParseError};

assert!(Url::parse("../main.css") == Err(ParseError::RelativeUrlWithoutBase))
Run

Use the join method on an Url to use it as a base URL:

use url::Url;

let this_document = Url::parse("http://servo.github.io/rust-url/url/index.html")?;
let css_url = this_document.join("../main.css")?;
assert_eq!(css_url.as_str(), "http://servo.github.io/rust-url/main.css");
Run

Feature: serde

If you enable the serde feature, Url will implement serde::Serialize and serde::Deserialize. See serde documentation for more information.

url = { version = "2", features = ["serde"] }

Feature: debugger_visualizer

If you enable the debugger_visualizer feature, the url crate will include a natvis file for Visual Studio that allows you to view Url objects in the debugger.

This feature requires Rust 1.71 or later.

url = { version = "2", features = ["debugger_visualizer"] }

Structs §

Url §

pub struct url::Url { /* ... */ }

A parsed URL record.

Implementations §

impl Url
parse
fn parse(input: &str) -> Result<Self, crate::ParseError>

Parse an absolute URL from a string.

Examples
use url::Url;

let url = Url::parse("https://example.net")?;
Run
Errors

If the function can not parse an absolute URL from the given string, a ParseError variant will be returned.

parse_with_params
fn parse_with_params(input: &str, iter: I) -> Result<Self, crate::ParseError>

Parse an absolute URL from a string and add params to its query string.

Existing params are not removed.

Examples
use url::Url;

let url = Url::parse_with_params("https://example.net?dont=clobberme",
                                 &[("lang", "rust"), ("browser", "servo")])?;
assert_eq!("https://example.net/?dont=clobberme&lang=rust&browser=servo", url.as_str());
Run
Errors

If the function can not parse an absolute URL from the given string, a ParseError variant will be returned.

join
fn join(self: &Self, input: &str) -> Result<Self, crate::ParseError>

Parse a string as an URL, with this URL as the base URL.

The inverse of this is make_relative.

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.
  • A scheme relative special URL 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
use url::Url;

// Base without a trailing slash
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 base url relative special URL
let base = Url::parse("https://alice.com/a")?;
let url = base.join("/v1/meta")?;
assert_eq!(url.as_str(), "https://alice.com/v1/meta");

// 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
Run
Errors

If the function can not parse an URL from the given string with this URL as the base URL, a ParseError variant will be returned.

make_relative
fn make_relative(self: &Self, url: &Self) -> Option<String>

Creates a relative URL if possible, with this URL as the base URL.

This is the inverse of join.

Examples
use url::Url;

let base = Url::parse("https://example.net/a/b.html")?;
let url = Url::parse("https://example.net/a/c.png")?;
let relative = base.make_relative(&url);
assert_eq!(relative.as_ref().map(|s| s.as_str()), Some("c.png"));

let base = Url::parse("https://example.net/a/b/")?;
let url = Url::parse("https://example.net/a/b/c.png")?;
let relative = base.make_relative(&url);
assert_eq!(relative.as_ref().map(|s| s.as_str()), Some("c.png"));

let base = Url::parse("https://example.net/a/b/")?;
let url = Url::parse("https://example.net/a/d/c.png")?;
let relative = base.make_relative(&url);
assert_eq!(relative.as_ref().map(|s| s.as_str()), Some("../d/c.png"));

let base = Url::parse("https://example.net/a/b.html?c=d")?;
let url = Url::parse("https://example.net/a/b.html?e=f")?;
let relative = base.make_relative(&url);
assert_eq!(relative.as_ref().map(|s| s.as_str()), Some("?e=f"));
Run
Errors

If this URL can't be a base for the given URL, None is returned. This is for example the case if the scheme, host or port are not the same.

options
fn options() -> ParseOptions<'a>

Return a default ParseOptions that can fully configure the URL parser.

Examples

Get default ParseOptions, then change base url

use url::Url;
let options = Url::options();
let api = Url::parse("https://api.example.com")?;
let base_url = options.base_url(Some(&api));
let version_url = base_url.parse("version.json")?;
assert_eq!(version_url.as_str(), "https://api.example.com/version.json");
Run
as_str
fn as_str(self: &Self) -> &str

Return the serialization of this URL.

This is fast since that serialization is already stored in the Url struct.

Examples
use url::Url;

let url_str = "https://example.net/";
let url = Url::parse(url_str)?;
assert_eq!(url.as_str(), url_str);
Run
into_string
fn into_string(self: Self) -> String
👎 Deprecated since 2.3.0: use Into<String>

Return the serialization of this URL.

This consumes the Url and takes ownership of the String stored in it.

Examples
use url::Url;

let url_str = "https://example.net/";
let url = Url::parse(url_str)?;
assert_eq!(String::from(url), url_str);
Run
origin
fn origin(self: &Self) -> Origin

Return the origin of this URL (https://url.spec.whatwg.org/#origin)

Note: this returns an opaque origin for file: URLs, which causes url.origin() != url.origin().

Examples

URL with ftp scheme:

use url::{Host, Origin, Url};

let url = Url::parse("ftp://example.com/foo")?;
assert_eq!(url.origin(),
           Origin::Tuple("ftp".into(),
                         Host::Domain("example.com".into()),
                         21));
Run

URL with blob scheme:

use url::{Host, Origin, Url};

let url = Url::parse("blob:https://example.com/foo")?;
assert_eq!(url.origin(),
           Origin::Tuple("https".into(),
                         Host::Domain("example.com".into()),
                         443));
Run

URL with file scheme:

use url::{Host, Origin, Url};

let url = Url::parse("file:///tmp/foo")?;
assert!(!url.origin().is_tuple());

let other_url = Url::parse("file:///tmp/foo")?;
assert!(url.origin() != other_url.origin());
Run

URL with other scheme:

use url::{Host, Origin, Url};

let url = Url::parse("foo:bar")?;
assert!(!url.origin().is_tuple());
Run
scheme
fn scheme(self: &Self) -> &str

Return the scheme of this URL, lower-cased, as an ASCII string without the ':' delimiter.

Examples
use url::Url;

let url = Url::parse("file:///tmp/foo")?;
assert_eq!(url.scheme(), "file");
Run
is_special
fn is_special(self: &Self) -> bool

Return whether the URL is special (has a special scheme)

Examples
use url::Url;

assert!(Url::parse("http:///tmp/foo")?.is_special());
assert!(Url::parse("file:///tmp/foo")?.is_special());
assert!(!Url::parse("moz:///tmp/foo")?.is_special());
Run
has_authority
fn has_authority(self: &Self) -> bool

Return whether the URL has an 'authority', which can contain a username, password, host, and port number.

URLs that do not are either path-only like unix:/run/foo.socket or cannot-be-a-base like data:text/plain,Stuff.

See also the authority method.

Examples
use url::Url;

let url = Url::parse("ftp://rms@example.com")?;
assert!(url.has_authority());

let url = Url::parse("unix:/run/foo.socket")?;
assert!(!url.has_authority());

let url = Url::parse("data:text/plain,Stuff")?;
assert!(!url.has_authority());
Run
authority
fn authority(self: &Self) -> &str

Return the authority of this URL as an ASCII string.

Non-ASCII domains are punycode-encoded per IDNA if this is the host of a special URL, or percent encoded for non-special URLs. IPv6 addresses are given between [ and ] brackets. Ports are omitted if they match the well known port of a special URL.

Username and password are percent-encoded.

See also the has_authority method.

Examples
use url::Url;

let url = Url::parse("unix:/run/foo.socket")?;
assert_eq!(url.authority(), "");
let url = Url::parse("file:///tmp/foo")?;
assert_eq!(url.authority(), "");
let url = Url::parse("https://user:password@example.com/tmp/foo")?;
assert_eq!(url.authority(), "user:password@example.com");
let url = Url::parse("irc://àlex.рф.example.com:6667/foo")?;
assert_eq!(url.authority(), "%C3%A0lex.%D1%80%D1%84.example.com:6667");
let url = Url::parse("http://àlex.рф.example.com:80/foo")?;
assert_eq!(url.authority(), "xn--lex-8ka.xn--p1ai.example.com");
Run
cannot_be_a_base
fn cannot_be_a_base(self: &Self) -> bool

Return whether this URL is a cannot-be-a-base URL, meaning that parsing a relative URL string with this URL as the base will return an error.

This is the case if the scheme and : delimiter are not followed by a / slash, as is typically the case of data: and mailto: URLs.

Examples
use url::Url;

let url = Url::parse("ftp://rms@example.com")?;
assert!(!url.cannot_be_a_base());

let url = Url::parse("unix:/run/foo.socket")?;
assert!(!url.cannot_be_a_base());

let url = Url::parse("data:text/plain,Stuff")?;
assert!(url.cannot_be_a_base());
Run
username
fn username(self: &Self) -> &str

Return the username for this URL (typically the empty string) as a percent-encoded ASCII string.

Examples
use url::Url;

let url = Url::parse("ftp://rms@example.com")?;
assert_eq!(url.username(), "rms");

let url = Url::parse("ftp://:secret123@example.com")?;
assert_eq!(url.username(), "");

let url = Url::parse("https://example.com")?;
assert_eq!(url.username(), "");
Run
password
fn password(self: &Self) -> Option<&str>

Return the password for this URL, if any, as a percent-encoded ASCII string.

Examples
use url::Url;

let url = Url::parse("ftp://rms:secret123@example.com")?;
assert_eq!(url.password(), Some("secret123"));

let url = Url::parse("ftp://:secret123@example.com")?;
assert_eq!(url.password(), Some("secret123"));

let url = Url::parse("ftp://rms@example.com")?;
assert_eq!(url.password(), None);

let url = Url::parse("https://example.com")?;
assert_eq!(url.password(), None);
Run
has_host
fn has_host(self: &Self) -> bool

Equivalent to url.host().is_some().

Examples
use url::Url;

let url = Url::parse("ftp://rms@example.com")?;
assert!(url.has_host());

let url = Url::parse("unix:/run/foo.socket")?;
assert!(!url.has_host());

let url = Url::parse("data:text/plain,Stuff")?;
assert!(!url.has_host());
Run
host_str
fn host_str(self: &Self) -> Option<&str>

Return the string representation of the host (domain or IP address) for this URL, if any.

Non-ASCII domains are punycode-encoded per IDNA if this is the host of a special URL, or percent encoded for non-special URLs. IPv6 addresses are given between [ and ] brackets.

Cannot-be-a-base URLs (typical of data: and mailto:) and some file: URLs don’t have a host.

See also the host method.

Examples
use url::Url;

let url = Url::parse("https://127.0.0.1/index.html")?;
assert_eq!(url.host_str(), Some("127.0.0.1"));

let url = Url::parse("https://subdomain.example.com")?;
assert_eq!(url.host_str(), Some("subdomain.example.com"));

let url = Url::parse("ftp://rms@example.com")?;
assert_eq!(url.host_str(), Some("example.com"));

let url = Url::parse("unix:/run/foo.socket")?;
assert_eq!(url.host_str(), None);

let url = Url::parse("data:text/plain,Stuff")?;
assert_eq!(url.host_str(), None);
Run
host
fn host(self: &Self) -> Option<Host<&str>>

Return the parsed representation of the host for this URL. Non-ASCII domain labels are punycode-encoded per IDNA if this is the host of a special URL, or percent encoded for non-special URLs.

Cannot-be-a-base URLs (typical of data: and mailto:) and some file: URLs don’t have a host.

See also the host_str method.

Examples
use url::Url;

let url = Url::parse("https://127.0.0.1/index.html")?;
assert!(url.host().is_some());

let url = Url::parse("ftp://rms@example.com")?;
assert!(url.host().is_some());

let url = Url::parse("unix:/run/foo.socket")?;
assert!(url.host().is_none());

let url = Url::parse("data:text/plain,Stuff")?;
assert!(url.host().is_none());
Run
domain
fn domain(self: &Self) -> Option<&str>

If this URL has a host and it is a domain name (not an IP address), return it. Non-ASCII domains are punycode-encoded per IDNA if this is the host of a special URL, or percent encoded for non-special URLs.

Examples
use url::Url;

let url = Url::parse("https://127.0.0.1/")?;
assert_eq!(url.domain(), None);

let url = Url::parse("mailto:rms@example.net")?;
assert_eq!(url.domain(), None);

let url = Url::parse("https://example.com/")?;
assert_eq!(url.domain(), Some("example.com"));

let url = Url::parse("https://subdomain.example.com/")?;
assert_eq!(url.domain(), Some("subdomain.example.com"));
Run
port
fn port(self: &Self) -> Option<u16>

Return the port number for this URL, if any.

Note that default port numbers are never reflected by the serialization, use the port_or_known_default() method if you want a default port number returned.

Examples
use url::Url;

let url = Url::parse("https://example.com")?;
assert_eq!(url.port(), None);

let url = Url::parse("https://example.com:443/")?;
assert_eq!(url.port(), None);

let url = Url::parse("ssh://example.com:22")?;
assert_eq!(url.port(), Some(22));
Run
port_or_known_default
fn port_or_known_default(self: &Self) -> Option<u16>

Return the port number for this URL, or the default port number if it is known.

This method only knows the default port number of the http, https, ws, wss and ftp schemes.

For URLs in these schemes, this method always returns Some(_). For other schemes, it is the same as Url::port().

Examples
use url::Url;

let url = Url::parse("foo://example.com")?;
assert_eq!(url.port_or_known_default(), None);

let url = Url::parse("foo://example.com:1456")?;
assert_eq!(url.port_or_known_default(), Some(1456));

let url = Url::parse("https://example.com")?;
assert_eq!(url.port_or_known_default(), Some(443));
Run
socket_addrs
fn socket_addrs( self: &Self, default_port_number: impl Fn() -> Option<u16> ) -> io::Result<alloc::vec::Vec<SocketAddr>>

Resolve a URL’s host and port number to SocketAddr.

If the URL has the default port number of a scheme that is unknown to this library, default_port_number provides an opportunity to provide the actual port number. In non-example code this should be implemented either simply as || None, or by matching on the URL’s .scheme().

If the host is a domain, it is resolved using the standard library’s DNS support.

Examples
no_run
let url = url::Url::parse("https://example.net/").unwrap();
let addrs = url.socket_addrs(|| None).unwrap();
std::net::TcpStream::connect(&*addrs)
Run
/// With application-specific known default port numbers
fn socket_addrs(url: url::Url) -> std::io::Result<Vec<std::net::SocketAddr>> {
    url.socket_addrs(|| match url.scheme() {
        "socks5" | "socks5h" => Some(1080),
        _ => None,
    })
}
Run
path
fn path(self: &Self) -> &str

Return the path for this URL, as a percent-encoded ASCII string. For cannot-be-a-base URLs, this is an arbitrary string that doesn’t start with '/'. For other URLs, this starts with a '/' slash and continues with slash-separated path segments.

Examples
use url::{Url, ParseError};

let url = Url::parse("https://example.com/api/versions?page=2")?;
assert_eq!(url.path(), "/api/versions");

let url = Url::parse("https://example.com")?;
assert_eq!(url.path(), "/");

let url = Url::parse("https://example.com/countries/việt nam")?;
assert_eq!(url.path(), "/countries/vi%E1%BB%87t%20nam");
Run
path_segments
fn path_segments(self: &Self) -> Option<str::Split<'_, char>>

Unless this URL is cannot-be-a-base, return an iterator of '/' slash-separated path segments, each as a percent-encoded ASCII string.

Return None for cannot-be-a-base URLs.

When Some is returned, the iterator always contains at least one string (which may be empty).

Examples
use url::Url;


let url = Url::parse("https://example.com/foo/bar")?;
let mut path_segments = url.path_segments().ok_or_else(|| "cannot be base")?;
assert_eq!(path_segments.next(), Some("foo"));
assert_eq!(path_segments.next(), Some("bar"));
assert_eq!(path_segments.next(), None);

let url = Url::parse("https://example.com")?;
let mut path_segments = url.path_segments().ok_or_else(|| "cannot be base")?;
assert_eq!(path_segments.next(), Some(""));
assert_eq!(path_segments.next(), None);

let url = Url::parse("data:text/plain,HelloWorld")?;
assert!(url.path_segments().is_none());

let url = Url::parse("https://example.com/countries/việt nam")?;
let mut path_segments = url.path_segments().ok_or_else(|| "cannot be base")?;
assert_eq!(path_segments.next(), Some("countries"));
assert_eq!(path_segments.next(), Some("vi%E1%BB%87t%20nam"));
Run
query
fn query(self: &Self) -> Option<&str>

Return this URL’s query string, if any, as a percent-encoded ASCII string.

Examples
use url::Url;

fn run() -> Result<(), ParseError> {
let url = Url::parse("https://example.com/products?page=2")?;
let query = url.query();
assert_eq!(query, Some("page=2"));

let url = Url::parse("https://example.com/products")?;
let query = url.query();
assert!(query.is_none());

let url = Url::parse("https://example.com/?country=español")?;
let query = url.query();
assert_eq!(query, Some("country=espa%C3%B1ol"));
Run
query_pairs
fn query_pairs(self: &Self) -> form_urlencoded::Parse<'_>

Parse the URL’s query string, if any, as application/x-www-form-urlencoded and return an iterator of (key, value) pairs.

Examples
use std::borrow::Cow;

use url::Url;

let url = Url::parse("https://example.com/products?page=2&sort=desc")?;
let mut pairs = url.query_pairs();

assert_eq!(pairs.count(), 2);

assert_eq!(pairs.next(), Some((Cow::Borrowed("page"), Cow::Borrowed("2"))));
assert_eq!(pairs.next(), Some((Cow::Borrowed("sort"), Cow::Borrowed("desc"))));
Run
fragment
fn fragment(self: &Self) -> Option<&str>

Return this URL’s fragment identifier, if any.

A fragment is the part of the URL after the # symbol. The fragment is optional and, if present, contains a fragment identifier that identifies a secondary resource, such as a section heading of a document.

In HTML, the fragment identifier is usually the id attribute of a an element that is scrolled to on load. Browsers typically will not send the fragment portion of a URL to the server.

Note: the parser did not percent-encode this component, but the input may have been percent-encoded already.

Examples
use url::Url;

let url = Url::parse("https://example.com/data.csv#row=4")?;

assert_eq!(url.fragment(), Some("row=4"));

let url = Url::parse("https://example.com/data.csv#cell=4,1-6,2")?;

assert_eq!(url.fragment(), Some("cell=4,1-6,2"));
Run
set_fragment
fn set_fragment(self: &mut Self, fragment: Option<&str>)

Change this URL’s fragment identifier.

Examples
use url::Url;

let mut url = Url::parse("https://example.com/data.csv")?;
assert_eq!(url.as_str(), "https://example.com/data.csv");

url.set_fragment(Some("cell=4,1-6,2"));
assert_eq!(url.as_str(), "https://example.com/data.csv#cell=4,1-6,2");
assert_eq!(url.fragment(), Some("cell=4,1-6,2"));

url.set_fragment(None);
assert_eq!(url.as_str(), "https://example.com/data.csv");
assert!(url.fragment().is_none());
Run
set_query
fn set_query(self: &mut Self, query: Option<&str>)

Change this URL’s query string. If query is None, this URL's query string will be cleared.

Examples
use url::Url;

let mut url = Url::parse("https://example.com/products")?;
assert_eq!(url.as_str(), "https://example.com/products");

url.set_query(Some("page=2"));
assert_eq!(url.as_str(), "https://example.com/products?page=2");
assert_eq!(url.query(), Some("page=2"));
Run
query_pairs_mut
fn query_pairs_mut(self: &mut Self) -> form_urlencoded::Serializer<'_, UrlQuery<'_>>

Manipulate this URL’s query string, viewed as a sequence of name/value pairs in application/x-www-form-urlencoded syntax.

The return value has a method-chaining API:


let mut url = Url::parse("https://example.net?lang=fr#nav")?;
assert_eq!(url.query(), Some("lang=fr"));

url.query_pairs_mut().append_pair("foo", "bar");
assert_eq!(url.query(), Some("lang=fr&foo=bar"));
assert_eq!(url.as_str(), "https://example.net/?lang=fr&foo=bar#nav");

url.query_pairs_mut()
    .clear()
    .append_pair("foo", "bar & baz")
    .append_pair("saisons", "\u{00C9}t\u{00E9}+hiver");
assert_eq!(url.query(), Some("foo=bar+%26+baz&saisons=%C3%89t%C3%A9%2Bhiver"));
assert_eq!(url.as_str(),
           "https://example.net/?foo=bar+%26+baz&saisons=%C3%89t%C3%A9%2Bhiver#nav");
Run

Note: url.query_pairs_mut().clear(); is equivalent to url.set_query(Some("")), not url.set_query(None).

The state of Url is unspecified if this return value is leaked without being dropped.

set_path
fn set_path(self: &mut Self, path: &str)

Change this URL’s path.

Examples
use url::Url;

let mut url = Url::parse("https://example.com")?;
url.set_path("api/comments");
assert_eq!(url.as_str(), "https://example.com/api/comments");
assert_eq!(url.path(), "/api/comments");

let mut url = Url::parse("https://example.com/api")?;
url.set_path("data/report.csv");
assert_eq!(url.as_str(), "https://example.com/data/report.csv");
assert_eq!(url.path(), "/data/report.csv");

// `set_path` percent-encodes the given string if it's not already percent-encoded.
let mut url = Url::parse("https://example.com")?;
url.set_path("api/some comments");
assert_eq!(url.as_str(), "https://example.com/api/some%20comments");
assert_eq!(url.path(), "/api/some%20comments");

// `set_path` will not double percent-encode the string if it's already percent-encoded.
let mut url = Url::parse("https://example.com")?;
url.set_path("api/some%20comments");
assert_eq!(url.as_str(), "https://example.com/api/some%20comments");
assert_eq!(url.path(), "/api/some%20comments");
Run
path_segments_mut
fn path_segments_mut(self: &mut Self) -> Result<PathSegmentsMut<'_>, ()>

Return an object with methods to manipulate this URL’s path segments.

Return Err(()) if this URL is cannot-be-a-base.

set_port
fn set_port(self: &mut Self, port: Option<u16>) -> Result<(), ()>

Change this URL’s port number.

Note that default port numbers are not reflected in the serialization.

If this URL is cannot-be-a-base, does not have a host, or has the file scheme; do nothing and return Err.

Examples
use url::Url;


let mut url = Url::parse("ssh://example.net:2048/")?;

url.set_port(Some(4096)).map_err(|_| "cannot be base")?;
assert_eq!(url.as_str(), "ssh://example.net:4096/");

url.set_port(None).map_err(|_| "cannot be base")?;
assert_eq!(url.as_str(), "ssh://example.net/");
Run

Known default port numbers are not reflected:

use url::Url;


let mut url = Url::parse("https://example.org/")?;

url.set_port(Some(443)).map_err(|_| "cannot be base")?;
assert!(url.port().is_none());
Run

Cannot set port for cannot-be-a-base URLs:

use url::Url;

let mut url = Url::parse("mailto:rms@example.net")?;

let result = url.set_port(Some(80));
assert!(result.is_err());

let result = url.set_port(None);
assert!(result.is_err());
Run
set_host
fn set_host(self: &mut Self, host: Option<&str>) -> Result<(), ParseError>

Change this URL’s host.

Removing the host (calling this with None) will also remove any username, password, and port number.

Examples

Change host:

use url::Url;

let mut url = Url::parse("https://example.net")?;
let result = url.set_host(Some("rust-lang.org"));
assert!(result.is_ok());
assert_eq!(url.as_str(), "https://rust-lang.org/");
Run

Remove host:

use url::Url;

let mut url = Url::parse("foo://example.net")?;
let result = url.set_host(None);
assert!(result.is_ok());
assert_eq!(url.as_str(), "foo:/");
Run

Cannot remove host for 'special' schemes (e.g. http):

use url::Url;

let mut url = Url::parse("https://example.net")?;
let result = url.set_host(None);
assert!(result.is_err());
assert_eq!(url.as_str(), "https://example.net/");
Run

Cannot change or remove host for cannot-be-a-base URLs:

use url::Url;

let mut url = Url::parse("mailto:rms@example.net")?;

let result = url.set_host(Some("rust-lang.org"));
assert!(result.is_err());
assert_eq!(url.as_str(), "mailto:rms@example.net");

let result = url.set_host(None);
assert!(result.is_err());
assert_eq!(url.as_str(), "mailto:rms@example.net");
Run
Errors

If this URL is cannot-be-a-base or there is an error parsing the given host, a ParseError variant will be returned.

set_ip_host
fn set_ip_host(self: &mut Self, address: IpAddr) -> Result<(), ()>

Change this URL’s host to the given IP address.

If this URL is cannot-be-a-base, do nothing and return Err.

Compared to Url::set_host, this skips the host parser.

Examples
use url::{Url, ParseError};

let mut url = Url::parse("http://example.com")?;
url.set_ip_host("127.0.0.1".parse().unwrap());
assert_eq!(url.host_str(), Some("127.0.0.1"));
assert_eq!(url.as_str(), "http://127.0.0.1/");
Run

Cannot change URL's from mailto(cannot-be-base) to ip:

use url::{Url, ParseError};

let mut url = Url::parse("mailto:rms@example.com")?;
let result = url.set_ip_host("127.0.0.1".parse().unwrap());

assert_eq!(url.as_str(), "mailto:rms@example.com");
assert!(result.is_err());
Run
set_password
fn set_password(self: &mut Self, password: Option<&str>) -> Result<(), ()>

Change this URL’s password.

If this URL is cannot-be-a-base or does not have a host, do nothing and return Err.

Examples
use url::{Url, ParseError};

let mut url = Url::parse("mailto:rmz@example.com")?;
let result = url.set_password(Some("secret_password"));
assert!(result.is_err());

let mut url = Url::parse("ftp://user1:secret1@example.com")?;
let result = url.set_password(Some("secret_password"));
assert_eq!(url.password(), Some("secret_password"));

let mut url = Url::parse("ftp://user2:@example.com")?;
let result = url.set_password(Some("secret2"));
assert!(result.is_ok());
assert_eq!(url.password(), Some("secret2"));
Run
set_username
fn set_username(self: &mut Self, username: &str) -> Result<(), ()>

Change this URL’s username.

If this URL is cannot-be-a-base or does not have a host, do nothing and return Err.

Examples

Cannot setup username from mailto(cannot-be-base)

use url::{Url, ParseError};

let mut url = Url::parse("mailto:rmz@example.com")?;
let result = url.set_username("user1");
assert_eq!(url.as_str(), "mailto:rmz@example.com");
assert!(result.is_err());
Run

Setup username to user1

use url::{Url, ParseError};

let mut url = Url::parse("ftp://:secre1@example.com/")?;
let result = url.set_username("user1");
assert!(result.is_ok());
assert_eq!(url.username(), "user1");
assert_eq!(url.as_str(), "ftp://user1:secre1@example.com/");
Run
set_scheme
fn set_scheme(self: &mut Self, scheme: &str) -> Result<(), ()>

Change this URL’s scheme.

Do nothing and return Err under the following circumstances:

  • If the new scheme is not in [a-zA-Z][a-zA-Z0-9+.-]+
  • If this URL is cannot-be-a-base and the new scheme is one of http, https, ws, wss or ftp
  • If either the old or new scheme is http, https, ws, wss or ftp and the other is not one of these
  • If the new scheme is file and this URL includes credentials or has a non-null port
  • If this URL's scheme is file and its host is empty or null

See also the URL specification's section on legal scheme state overrides.

Examples

Change the URL’s scheme from https to http:

use url::Url;

let mut url = Url::parse("https://example.net")?;
let result = url.set_scheme("http");
assert_eq!(url.as_str(), "http://example.net/");
assert!(result.is_ok());
Run

Change the URL’s scheme from foo to bar:

use url::Url;

let mut url = Url::parse("foo://example.net")?;
let result = url.set_scheme("bar");
assert_eq!(url.as_str(), "bar://example.net");
assert!(result.is_ok());
Run

Cannot change URL’s scheme from https to foõ:

use url::Url;

let mut url = Url::parse("https://example.net")?;
let result = url.set_scheme("foõ");
assert_eq!(url.as_str(), "https://example.net/");
assert!(result.is_err());
Run

Cannot change URL’s scheme from mailto (cannot-be-a-base) to https:

use url::Url;

let mut url = Url::parse("mailto:rms@example.net")?;
let result = url.set_scheme("https");
assert_eq!(url.as_str(), "mailto:rms@example.net");
assert!(result.is_err());
Run

Cannot change the URL’s scheme from foo to https:

use url::Url;

let mut url = Url::parse("foo://example.net")?;
let result = url.set_scheme("https");
assert_eq!(url.as_str(), "foo://example.net");
assert!(result.is_err());
Run

Cannot change the URL’s scheme from http to foo:

use url::Url;

let mut url = Url::parse("http://example.net")?;
let result = url.set_scheme("foo");
assert_eq!(url.as_str(), "http://example.net/");
assert!(result.is_err());
Run
from_file_path
fn from_file_path(path: P) -> Result<Self, ()>

Convert a file name as std::path::Path into an URL in the file scheme.

This returns Err if the given path is not absolute or, on Windows, if the prefix is not a disk prefix (e.g. C:) or a UNC prefix (\\).

Examples

On Unix-like platforms:

use url::Url;

let url = Url::from_file_path("/tmp/foo.txt")?;
assert_eq!(url.as_str(), "file:///tmp/foo.txt");

let url = Url::from_file_path("../foo.txt");
assert!(url.is_err());

let url = Url::from_file_path("https://google.com/");
assert!(url.is_err());
Run

This method is only available if the std Cargo feature is enabled.

from_directory_path
fn from_directory_path(path: P) -> Result<Self, ()>

Convert a directory name as std::path::Path into an URL in the file scheme.

This returns Err if the given path is not absolute or, on Windows, if the prefix is not a disk prefix (e.g. C:) or a UNC prefix (\\).

Compared to from_file_path, this ensure that URL’s the path has a trailing slash so that the entire path is considered when using this URL as a base URL.

For example:

  • "index.html" parsed with Url::from_directory_path(Path::new("/var/www")) as the base URL is file:///var/www/index.html
  • "index.html" parsed with Url::from_file_path(Path::new("/var/www")) as the base URL is file:///var/index.html, which might not be what was intended.

Note that std::path does not consider trailing slashes significant and usually does not include them (e.g. in Path::parent()).

This method is only available if the std Cargo feature is enabled.

to_file_path
fn to_file_path(self: &Self) -> Result<PathBuf, ()>

Assuming the URL is in the file scheme or similar, convert its path to an absolute std::path::Path.

Note: This does not actually check the URL’s scheme, and may give nonsensical results for other schemes. It is the user’s responsibility to check the URL’s scheme before calling this.

let path = url.to_file_path();
Run

Returns Err if the host is neither empty nor "localhost" (except on Windows, where file: URLs may have a non-local host), or if Path::new_opt() returns None. (That is, if the percent-decoded path contains a NUL byte or, for a Windows path, is not UTF-8.)

This method is only available if the std Cargo feature is enabled.

Trait Implementations §

impl Borrow for Url
borrow
fn borrow(self: &Self) -> &T
impl BorrowMut for Url
borrow_mut
fn borrow_mut(self: &mut Self) -> &mut T
impl CloneToUninit for Url
clone_to_uninit
unsafe fn clone_to_uninit(self: &Self, dest: *mut u8)
impl Into for Url
into
fn into(self: Self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

impl From for Url
from
fn from(t: T) -> T

Returns the argument unchanged.

impl TryInto for Url
Error
try_into
fn try_into(self: Self) -> Result<U, <U as TryFrom<T>>::Error>
impl TryFrom for Url
Error
try_from
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
impl Any for Url
type_id
fn type_id(self: &Self) -> TypeId
impl ToOwned for Url
Owned
to_owned
fn to_owned(self: &Self) -> T
clone_into
fn clone_into(self: &Self, target: &mut T)
impl ToString for Url
to_string
fn to_string(self: &Self) -> String
impl Index for crate::Url
Output
index
fn index(self: &Self, _: RangeFull) -> &str
impl Index for crate::Url
Output
index
fn index(self: &Self, range: RangeFrom<Position>) -> &str
impl Index for crate::Url
Output
index
fn index(self: &Self, range: RangeTo<Position>) -> &str
impl Index for crate::Url
Output
index
fn index(self: &Self, range: Range<Position>) -> &str
impl Clone for Url
clone
fn clone(self: &Self) -> Url
impl FromStr for Url
Err
from_str
fn from_str(input: &str) -> Result<Self, crate::ParseError>
impl TryFrom for Url
Error
try_from
fn try_from(s: &'a str) -> Result<Self, <Self as >::Error>
impl Display for Url
fmt
fn fmt(self: &Self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result
impl From for alloc::string::String
from
fn from(value: Url) -> Self
impl Debug for Url
fmt
fn fmt(self: &Self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result
impl PartialEq for Url
eq
fn eq(self: &Self, other: &Self) -> bool
impl Ord for Url
cmp
fn cmp(self: &Self, other: &Self) -> cmp::Ordering
impl PartialOrd for Url
partial_cmp
fn partial_cmp(self: &Self, other: &Self) -> Option<cmp::Ordering>
impl Hash for Url
hash
fn hash(self: &Self, state: &mut H)
impl AsRef for Url
as_ref
fn as_ref(self: &Self) -> &str
impl Send for Url
impl Sync for Url
impl Freeze for Url
impl UnsafeUnpin for Url
impl Unpin for Url
impl UnwindSafe for Url
impl RefUnwindSafe for Url
impl Eq for Url

ParseOptions §

pub struct url::ParseOptions { /* ... */ }
#[must_use]

Full configuration for the URL parser.

Implementations §

impl ParseOptions
base_url
fn base_url(self: Self, new: Option<&'a Url>) -> Self

Change the base URL

See the notes of Url::join for more details about how this base is considered when parsing.

encoding_override
fn encoding_override(self: Self, new: EncodingOverride<'a>) -> Self

Override the character encoding of query strings. This is a legacy concept only relevant for HTML.

syntax_violation_callback
fn syntax_violation_callback(self: Self, new: Option<&'a dyn Fn(SyntaxViolation)>) -> Self

Call the provided function or closure for a non-fatal SyntaxViolation when it occurs during parsing. Note that since the provided function is Fn, the caller might need to utilize interior mutability, such as with a RefCell, to collect the violations.

Example
use std::cell::RefCell;
use url::{Url, SyntaxViolation};
let violations = RefCell::new(Vec::new());
let url = Url::options()
    .syntax_violation_callback(Some(&|v| violations.borrow_mut().push(v)))
    .parse("https:////example.com")?;
assert_eq!(url.as_str(), "https://example.com/");
assert_eq!(violations.into_inner(),
           vec!(SyntaxViolation::ExpectedDoubleSlash));
Run
parse
fn parse(self: Self, input: &str) -> Result<Url, crate::ParseError>

Parse an URL string with the configuration so far.

Trait Implementations §

impl Borrow for ParseOptions
borrow
fn borrow(self: &Self) -> &T
impl BorrowMut for ParseOptions
borrow_mut
fn borrow_mut(self: &mut Self) -> &mut T
impl CloneToUninit for ParseOptions
clone_to_uninit
unsafe fn clone_to_uninit(self: &Self, dest: *mut u8)
impl Into for ParseOptions
into
fn into(self: Self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

impl From for ParseOptions
from
fn from(t: T) -> T

Returns the argument unchanged.

impl TryInto for ParseOptions
Error
try_into
fn try_into(self: Self) -> Result<U, <U as TryFrom<T>>::Error>
impl TryFrom for ParseOptions
Error
try_from
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
impl Any for ParseOptions
type_id
fn type_id(self: &Self) -> TypeId
impl ToOwned for ParseOptions
Owned
to_owned
fn to_owned(self: &Self) -> T
clone_into
fn clone_into(self: &Self, target: &mut T)
impl Clone for ParseOptions
clone
fn clone(self: &Self) -> ParseOptions<'a>
impl Send for ParseOptions
impl Sync for ParseOptions
impl Freeze for ParseOptions
impl UnsafeUnpin for ParseOptions
impl Unpin for ParseOptions
impl UnwindSafe for ParseOptions
impl RefUnwindSafe for ParseOptions
impl Copy for ParseOptions

UrlQuery §

pub struct url::UrlQuery { /* ... */ }

Implementation detail of Url::query_pairs_mut. Typically not used directly.

Trait Implementations §

impl Borrow for UrlQuery
borrow
fn borrow(self: &Self) -> &T
impl BorrowMut for UrlQuery
borrow_mut
fn borrow_mut(self: &mut Self) -> &mut T
impl Into for UrlQuery
into
fn into(self: Self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

impl From for UrlQuery
from
fn from(t: T) -> T

Returns the argument unchanged.

impl TryInto for UrlQuery
Error
try_into
fn try_into(self: Self) -> Result<U, <U as TryFrom<T>>::Error>
impl TryFrom for UrlQuery
Error
try_from
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
impl Any for UrlQuery
type_id
fn type_id(self: &Self) -> TypeId
impl Debug for UrlQuery
fmt
fn fmt(self: &Self, f: &mut $crate::fmt::Formatter<'_>) -> $crate::fmt::Result
impl Target for UrlQuery
as_mut_string
fn as_mut_string(self: &mut Self) -> &mut String
finish
fn finish(self: Self) -> &'a mut Url
Finished
impl Drop for UrlQuery
drop
fn drop(self: &mut Self)
impl Send for UrlQuery
impl Sync for UrlQuery
impl Freeze for UrlQuery
impl UnsafeUnpin for UrlQuery
impl Unpin for UrlQuery
impl UnwindSafe for UrlQuery
impl RefUnwindSafe for UrlQuery

Re-exports §

form_urlencoded §

pub use form_urlencoded;

Host §

pub use crate::host::Host;

OpaqueOrigin §

pub use crate::origin::OpaqueOrigin;

Origin §

pub use crate::origin::Origin;

ParseError §

pub use crate::parser::ParseError;

SyntaxViolation §

pub use crate::parser::SyntaxViolation;

PathSegmentsMut §

pub use crate::path_segments::PathSegmentsMut;

Position §

pub use crate::slicing::Position;

EncodingOverride §

pub use form_urlencoded::EncodingOverride;
Docs by Sourcey
↑↓ navigate↵ selectesc close