Struct net::url::URL

pub struct URL {
    pub force_query: bool,
    pub fragment: String,
    pub host: String,
    pub path: String,
    pub opaque: String,
    pub raw_fragment: String,
    pub raw_path: String,
    pub raw_query: String,
    pub scheme: String,
    pub user: Option<UserInfo>,
}

A URL represents a parsed URL (technically, a URI reference).

The general form represented is:

[scheme:][//[userinfo@]host][/]path[?query][#fragment]

URLs that do not start with a slash after the scheme are interpreted as:

scheme:opaque[?query][#fragment]

Note that the path field is stored in decoded form: /%47%6f%2f becomes /Go/. A consequence is that it is impossible to tell which slashes in the path were slashes in the raw URL and which were %2f. This distinction is rarely important, but when it is, the code should use raw_path, an optional field which only gets set if the default encoding is different from path.

URL's String method uses the escaped_path method to obtain the path. See the escaped_path method for more details.

Example

fn main() {
    let mut u = net::url::parse("http://bing.com/search?q=dotnet").unwrap();

    u.scheme = "https".to_string();
    u.host = "google.com".to_string();

    let mut q = u.query();
    q.set("q", "golang");

    u.raw_query = q.encode();

    const EXPECTED: &str = "https://google.com/search?q=golang";
    assert_eq!(EXPECTED, u.to_string());
}

Example

fn main() {
    let u = net::url::parse("https://example.com/foo%2fbar").unwrap();

    assert_eq!("/foo/bar", u.path, "invalid path");
    assert_eq!("/foo%2fbar", u.raw_path, "invalid raw_path");
    assert_eq!(
        "https://example.com/foo%2fbar",
        u.to_string(),
        "invalid to_string() output"
    );
}

Fields

force_query: bool

append a query ('?') even if raw_query is empty

fragment: String

fragment for references, without '#'

host: String

host or host:port

path: String

path (relative paths may omit leading slash)

opaque: String

encoded opaque data

raw_fragment: String

encoded fragment hint (see escaped_fragment method)

raw_path: String

encoded path hint (see escaped_path method)

raw_query: String

encoded query values, without '?'

scheme: String

user: Option<UserInfo>

username and password information

Implementations

impl URL

pub fn escaped_fragment(&self) -> String

escaped_fragment returns the escaped form of self.fragment. In general there are multiple possible escaped forms of any fragment. escaped_fragment returns self.raw_fragment when it is a valid escaping of self.fragment. Otherwise escaped_fragment ignores self.raw_fragment and computes an escaped form on its own. The String method uses escaped_fragment to construct its result. In general, code should call escaped_fragment instead of reading self.raw_fragment directly.

Example

fn main() {
    let u = net::url::parse("http://example.com/#x/y%2Fz").unwrap();

    assert_eq!("x/y/z", u.fragment, "invalid fragment");
    assert_eq!("x/y%2Fz", u.raw_fragment, "invalid raw fragment");
    assert_eq!("x/y%2Fz", u.escaped_fragment(), "invalid escaped fragment");
}

pub fn escaped_path(&self) -> String

escaped_path returns the escaped form of self.path. In general there are multiple possible escaped forms of any path. escaped_path returns self.raw_path when it is a valid escaping of self.path. Otherwise escaped_path ignores self.raw_path and computes an escaped form on its own. The Display::fmt and request_uri methods use escaped_path to construct their results. In general, code should call escaped_path instead of reading self.raw_path directly.

Example

fn main() {
    let u = net::url::parse("http://example.com/x/y%2Fz").unwrap();

    assert_eq!("/x/y/z", u.path, "invalid path");
    assert_eq!("/x/y%2Fz", u.raw_path, "invalid raw path");
    assert_eq!("/x/y%2Fz", u.escaped_path(), "invalid escaped path");
}

pub fn hostname(&self) -> &str

hostname returns self.host, stripping any valid port number if present.

If the result is enclosed in square brackets, as literal IPv6 addresses are, the square brackets are removed from the result.

Example

fn main() {
    let u = net::url::parse("https://example.org:8000/path").unwrap();
    assert_eq!("example.org", u.hostname());

    let u = net::url::parse("https://[2001:0db8:85a3:0000:0000:8a2e:0370:7334]:17000").unwrap();
    assert_eq!("2001:0db8:85a3:0000:0000:8a2e:0370:7334", u.hostname());
}

pub fn is_abs(&self) -> bool

is_abs reports whether the URL is absolute. Absolute means that it has a non-empty scheme.

Example

use net::url::URL;

fn main() {
    let mut u = URL {
        host: "example.com".to_string(),
        path: "foo".to_string(),
        ..Default::default()
    };

    assert!(!u.is_abs());

    u.scheme = "http".to_string();

    assert!(u.is_abs());
}

pub fn parse(&self, reference: &str) -> Result<Self, Error>

parse parses a URL in the context of the receiver. The provided URL may be relative or absolute. Parse returns nil, err on parse failure, otherwise its return value is the same as resolve_reference.

pub fn port(&self) -> &str

port returns the port part of self.host, without the leading colon.

If self.host doesn't contain a valid numeric port, port returns an empty string.

Example

use net::url;

fn main() {
    let u = url::parse("https://example.org").unwrap();
    assert_eq!("", u.port());

    let u = url::parse("https://example.org:8080").unwrap();
    assert_eq!("8080", u.port());
}

pub fn query(&self) -> Values

query parses raw_query and returns the corresponding values. It silently discards malformed value pairs. To check errors use net::url::parse_query.

Example

fn main() {
    let q = net::url::parse("https://example.org/?a=1&a=2&b=&=3&&&&")
        .unwrap()
        .query();

    assert_eq!(vec!["1".to_string(), "2".to_string()], q.0["a"]);
    assert_eq!("", q.get("b").unwrap());
    assert_eq!("3", q.get("").unwrap());
}

pub fn redacted(&self) -> String

redacted is like to_string() but replaces any password with "xxxxx". Only the password in self.user is redacted.

Example

use net::url::{self, URL};

fn main() {
    let mut u = URL {
        scheme: "https".to_string(),
        user: Some(url::user_password("user", "password")),
        host: "example.com".to_string(),
        path: "foo/bar".to_string(),
        ..Default::default()
    };

    assert_eq!("https://user:xxxxx@example.com/foo/bar", u.redacted());

    u.user = Some(url::user_password("me", "new_password"));

    assert_eq!("https://me:xxxxx@example.com/foo/bar", u.redacted());
}

pub fn request_uri(&self) -> String

request_uri returns the encoded path?query or opaque?query string that would be used in an HTTP request for self.

Example

fn main() {
    let u = net::url::parse("https://example.org/path?foo=bar").unwrap();
    assert_eq!("/path?foo=bar", u.request_uri());
}

pub fn resolve_reference(&self, r: &Self) -> Self

resolve_reference resolves a URI reference to an absolute URI from an absolute base URI u, per RFC 3986 Section 5.2. The URI reference may be relative or absolute. resolve_reference always returns a new URL instance, even if the returned URL is identical to either the base or reference. If ref is an absolute URL, then resolve_reference ignores base and returns a copy of ref.

Example

use net::url;

fn main() {
    let u = url::parse("../../..//search?q=dotnet").unwrap();
    let base = url::parse("http://example.com/directory/").unwrap();

    let got = base.resolve_reference(&u);
    const EXPECTED: &str = "http://example.com/search?q=dotnet";
    assert_eq!(EXPECTED, got.to_string());
}

Trait Implementations

impl Clone for URL

fn clone(&self) -> URL

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for URL

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Default for URL

fn default() -> URL

Returns the "default value" for a type.

impl<'de> Deserialize<'de> for URL

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error> where
    __D: Deserializer<'de>, 

Deserialize this value from the given Serde deserializer.

impl Display for URL

fn fmt(&self, f: &mut Formatter) -> Result

fmt reassembles the URL into a valid URL string. The general form of the result is one of:

scheme:opaque?query#fragment scheme://userinfo@host/path?query#fragment

If self.opaque is non-empty, fmt uses the first form; otherwise it uses the second form. Any non-ASCII characters in host are escaped. To obtain the path, String uses self.escaped_path().

In the second form, the following rules apply:

• if self.scheme is empty, scheme: is omitted.
• if self.user is None, userinfo@ is omitted.
• if self.host is empty, host/ is omitted.
• if self.scheme and self.host are empty and self.user is None, the entire scheme://userinfo@host/ is omitted.
• if self.host is non-empty and u.Path begins with a /, the form host/path does not add its own /.
• if self.raw_query is empty, ?query is omitted.
• if self.fragment is empty, #fragment is omitted.

Example

use net::url::{self, URL};

fn main() {
    let mut u = URL {
        scheme: "https".to_string(),
        user: Some(url::user_password("me", "pass")),
        host: "example.com".to_string(),
        path: "foo/bar".to_string(),
        raw_query: "x=1&y=2".to_string(),
        fragment: "anchor".to_string(),
        ..Default::default()
    };

    assert_eq!(
        "https://me:pass@example.com/foo/bar?x=1&y=2#anchor",
        u.to_string()
    );

    u.opaque = "opaque".to_string();
    assert_eq!("https:opaque?x=1&y=2#anchor", u.to_string());
}

impl PartialEq<URL> for URL

fn eq(&self, other: &URL) -> bool

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

fn ne(&self, other: &URL) -> bool

This method tests for !=.

impl Serialize for URL

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error> where
    __S: Serializer, 

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for URL