# Struct reqwest::Url [−] [src]

    pub struct Url { /* fields omitted */ }

A parsed URL record.

## Implementations

### `impl Url` [src]

#### `pub fn parse(input: &str) -> Result<Url, ParseError>` [src]

Parse an absolute URL from a string.

# Examples

    use url::Url;

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

# Errors

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

#### `pub fn parse_with_params<I, K, V>(
input: &str,
iter: I
) -> Result<Url, ParseError> where
V: AsRef<str>,
K: AsRef<str>,
I: IntoIterator,
<I as IntoIterator>::Item: Borrow<(K, V)>,` [src]

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());

# Errors

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

#### `pub fn join(&self, input: &str) -> Result<Url, ParseError>` [src]

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

Note: 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:

# Examples

    use url::Url;

    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

    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");

# 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.

#### `pub fn options<'a>() -> ParseOptions<'a>` [src]

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");

#### `pub fn as_str(&self) -> &str` [src]

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);

#### `pub fn into_string(self) -> String` [src]

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!(url.into_string(), url_str);

#### `pub fn origin(&self) -> Origin` [src]

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));

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));

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());

URL with other scheme:

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

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

#### `pub fn scheme(&self) -> &str` [src]

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");

#### `pub fn has_authority(&self) -> bool` [src]

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`.

# 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());

#### `pub fn cannot_be_a_base(&self) -> bool` [src]

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());

#### `pub fn username(&self) -> &str` [src]

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(), "");

#### `pub fn password(&self) -> Option<&str>` [src]

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);

#### `pub fn has_host(&self) -> bool` [src]

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());

#### `pub fn host_str(&self) -> Option<&str>` [src]

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("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);

#### `pub fn host(&self) -> Option<Host<&str>>` [src]

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());

#### `pub fn domain(&self) -> Option<&str>` [src]

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"));

#### `pub fn port(&self) -> Option<u16>` [src]

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));

#### `pub fn port_or_known_default(&self) -> Option<u16>` [src]

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));

#### `pub fn socket_addrs(
&self,
default_port_number: impl Fn() -> Option<u16>
) -> Result<Vec<SocketAddr, Global>, Error>` [src]

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

    let url = url::Url::parse("https://example.net/").unwrap();
    let addrs = url.socket_addrs(|| None).unwrap();
    std::net::TcpStream::connect(&*addrs)

    /// 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,
        })
    }

#### `pub fn path(&self) -> &str` [src]

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");

#### `pub fn path_segments(&self) -> Option<Split<'_, char>>` [src]

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"));

#### `pub fn query(&self) -> Option<&str>` [src]

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"));

#### `pub fn query_pairs(&self) -> Parse<'_>` [src]

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"))));

#### `pub fn fragment(&self) -> Option<&str>` [src]

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"));

#### `pub fn set_fragment(&mut self, fragment: Option<&str>)` [src]

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());

#### `pub fn set_query(&mut self, query: Option<&str>)` [src]

Change this URL’s query string.

# 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"));

#### `pub fn query_pairs_mut(&mut self) -> Serializer<'_, UrlQuery<'_>>` [src]

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");

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.

#### `pub fn set_path(&mut self, path: &str)` [src]

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");

#### `pub fn path_segments_mut(&mut self) -> Result<PathSegmentsMut<'_>, ()>` [src]

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

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

#### `pub fn set_port(&mut self, port: Option<u16>) -> Result<(), ()>` [src]

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/");

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());

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());

#### `pub fn set_host(&mut self, host: Option<&str>) -> Result<(), ParseError>` [src]

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/");

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:/");

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/");

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");

# Errors

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

#### `pub fn set_ip_host(&mut self, address: IpAddr) -> Result<(), ()>` [src]

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/");

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());

#### `pub fn set_password(&mut self, password: Option<&str>) -> Result<(), ()>` [src]

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"));

#### `pub fn set_username(&mut self, username: &str) -> Result<(), ()>` [src]

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());

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/");

#### `pub fn set_scheme(&mut self, scheme: &str) -> Result<(), ()>` [src]

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 `foo`:

    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());

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());

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());

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());

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());

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());

#### `pub fn from_file_path<P>(path: P) -> Result<Url, ()> where
P: AsRef<Path>,` [src]

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());

#### `pub fn from_directory_path<P>(path: P) -> Result<Url, ()> where
P: AsRef<Path>,` [src]

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()`).

#### `pub fn to_file_path(&self) -> Result<PathBuf, ()>` [src]

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();

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.)

## Trait Implementations

### `impl AsRef<str> for Url` [src]

Return the serialization of this URL.

#### `pub fn as_ref(&self) -> &str` [src]

Performs the conversion.

### `impl Clone for Url` [src]

#### `pub fn clone(&self) -> Url` [src]

Returns a copy of the value. Read more

#### `pub fn clone_from(&mut self, source: &Self)`1.0.0 [src]

Performs copy-assignment from `source`. Read more

### `impl Debug for Url` [src]

Debug the serialization of this URL.

#### `pub fn fmt(&self, formatter: &mut Formatter<'_>) -> Result<(), Error>` [src]

Formats the value using the given formatter. Read more

### `impl Display for Url` [src]

Display the serialization of this URL.

#### `pub fn fmt(&self, formatter: &mut Formatter<'_>) -> Result<(), Error>` [src]

Formats the value using the given formatter. Read more

### `impl Eq for Url` [src]

URLs compare like their serialization.

### `impl FromStr for Url` [src]

Parse a string as an URL, without a base URL or encoding override.

#### `type Err = ParseError`

The associated error which can be returned from parsing.

#### `pub fn from_str(input: &str) -> Result<Url, ParseError>` [src]

Parses a string `s` to return a value of this type. Read more

### `impl Hash for Url` [src]

URLs hash like their serialization.

#### `pub fn hash<H>(&self, state: &mut H) where
H: Hasher,` [src]

Feeds this value into the given `Hasher`. Read more

#### `pub fn hash_slice<H>(data: &[Self], state: &mut H) where
H: Hasher,` 1.3.0 [src]

Feeds a slice of this type into the given `Hasher`. Read more

### `impl Index<Range<Position>> for Url` [src]

#### `type Output = str`

The returned type after indexing.

#### `pub fn index(&self, range: Range<Position>) -> &str` [src]

Performs the indexing (`container[index]`) operation.

### `impl Index<RangeFrom<Position>> for Url` [src]

#### `type Output = str`

The returned type after indexing.

#### `pub fn index(&self, range: RangeFrom<Position>) -> &str` [src]

Performs the indexing (`container[index]`) operation.

### `impl Index<RangeFull> for Url` [src]

#### `type Output = str`

The returned type after indexing.

#### `pub fn index(&self, RangeFull) -> &str` [src]

Performs the indexing (`container[index]`) operation.

### `impl Index<RangeTo<Position>> for Url` [src]

#### `type Output = str`

The returned type after indexing.

#### `pub fn index(&self, range: RangeTo<Position>) -> &str` [src]

Performs the indexing (`container[index]`) operation.

### `impl IntoUrl for Url` [src]

### `impl Ord for Url` [src]

URLs compare like their serialization.

#### `pub fn cmp(&self, other: &Url) -> Ordering` [src]

This method returns an `Ordering` between `self` and `other`. Read more

#### `#[must_use]pub fn max(self, other: Self) -> Self` 1.21.0 [src]

Compares and returns the maximum of two values. Read more

#### `#[must_use]pub fn min(self, other: Self) -> Self` 1.21.0 [src]

Compares and returns the minimum of two values. Read more

#### `#[must_use]pub fn clamp(self, min: Self, max: Self) -> Self` 1.50.0 [src]

Restrict a value to a certain interval. Read more

### `impl PartialEq<Url> for Url` [src]

URLs compare like their serialization.

#### `pub fn eq(&self, other: &Url) -> bool` [src]

This method tests for `self` and `other` values to be equal, and is used by `==`. Read more

#### `#[must_use]pub fn ne(&self, other: &Rhs) -> bool` 1.0.0 [src]

This method tests for `!=`.

### `impl PartialOrd<Url> for Url` [src]

URLs compare like their serialization.

#### `pub fn partial_cmp(&self, other: &Url) -> Option<Ordering>` [src]

This method returns an ordering between `self` and `other` values if one exists. Read more

#### `#[must_use]pub fn lt(&self, other: &Rhs) -> bool` 1.0.0 [src]

This method tests less than (for `self` and `other`) and is used by the `<` operator. Read more

#### `#[must_use]pub fn le(&self, other: &Rhs) -> bool` 1.0.0 [src]

This method tests less than or equal to (for `self` and `other`) and is used by the `<=` operator. Read more

#### `#[must_use]pub fn gt(&self, other: &Rhs) -> bool` 1.0.0 [src]

This method tests greater than (for `self` and `other`) and is used by the `>` operator. Read more

#### `#[must_use]pub fn ge(&self, other: &Rhs) -> bool` 1.0.0 [src]

This method tests greater than or equal to (for `self` and `other`) and is used by the `>=` operator. Read more

### `impl<'a> TryFrom<&'a str> for Url` [src]

#### `type Error = ParseError`

The type returned in the event of a conversion error.

#### `pub fn try_from(s: &'a str) -> Result<Url, <Url as TryFrom<&'a str>>::Error>` [src]

Performs the conversion.

## Auto Trait Implementations

### `impl RefUnwindSafe for Url`

### `impl Send for Url`

### `impl Sync for Url`

### `impl Unpin for Url`

### `impl UnwindSafe for Url`

## Blanket Implementations

### `impl<T> Any for T where
T: 'static + ?Sized,` [src]

#### `pub fn type_id(&self) -> TypeId` [src]

Gets the `TypeId` of `self`. Read more

### `impl<T> Borrow<T> for T where
T: ?Sized,` [src]

#### `pub fn borrow(&self) -> &T` [src]

Immutably borrows from an owned value. Read more

### `impl<T> BorrowMut<T> for T where
T: ?Sized,` [src]

#### `pub fn borrow_mut(&mut self) -> &mut T` [src]

Mutably borrows from an owned value. Read more

### `impl<Q, K> Equivalent<K> for Q where
K: Borrow<Q> + ?Sized,
Q: Eq + ?Sized,` [src]

#### `pub fn equivalent(&self, key: &K) -> bool` [src]

Compare self to `key` and return `true` if they are equal.

### `impl<T> From<T> for T` [src]

#### `pub fn from(t: T) -> T` [src]

Performs the conversion.

### `impl<T> Instrument for T` [src]

#### `pub fn instrument(self, span: Span) -> Instrumented<Self>` [src]

Instruments this type with the provided `Span`, returning an `Instrumented` wrapper. Read more

#### `pub fn in_current_span(self) -> Instrumented<Self>` [src]

Instruments this type with the current `Span`, returning an `Instrumented` wrapper. Read more

### `impl<T, U> Into<U> for T where
U: From<T>,` [src]

#### `pub fn into(self) -> U` [src]

Performs the conversion.

### `impl<T> ToOwned for T where
T: Clone,` [src]

#### `type Owned = T`

The resulting type after obtaining ownership.

#### `pub fn to_owned(&self) -> T` [src]

Creates owned data from borrowed data, usually by cloning. Read more

#### `pub fn clone_into(&self, target: &mut T)` [src]

🔬 This is a nightly-only experimental API. (`toowned_clone_into`)

recently added

Uses borrowed data to replace owned data, usually by cloning. Read more

### `impl<T> ToString for T where
T: Display + ?Sized,` [src]

#### `pub default fn to_string(&self) -> String` [src]

Converts the given value to a `String`. Read more

### `impl<T, U> TryFrom<U> for T where
U: Into<T>,` [src]

#### `type Error = Infallible`

The type returned in the event of a conversion error.

#### `pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>` [src]

Performs the conversion.

### `impl<T, U> TryInto<U> for T where
U: TryFrom<T>,` [src]

#### `type Error = <U as TryFrom<T>>::Error`

The type returned in the event of a conversion error.

#### `pub fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>` [src]

Performs the conversion.