Crate url [−] [src]

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

It builds with Cargo. To use it in your project, add this to your Cargo.toml file:

[dependencies.url]
git = "https://github.com/servo/rust-url"

Supporting encodings other than UTF-8 in query strings is an optional feature that requires rust-encoding and is off by default. You can enable it with Cargo’s features mechanism:

[dependencies.url]
git = "https://github.com/servo/rust-url"
features = ["query_encoding"]

… or by passing --cfg 'feature="query_encoding"' to rustc.

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

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

use url::{Url, Host};

let issue_list_url = Url::parse(
    "https://github.com/rust-lang/rust/issues?labels=E-easy&state=open"
).unwrap();


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.fragment() == None);
assert!(!issue_list_url.cannot_be_a_base());

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

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

Base URL

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

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

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

use url::{Url, ParseError};

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

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").unwrap();
let css_url = this_document.join("../main.css").unwrap();
assert_eq!(css_url.as_str(), "http://servo.github.io/rust-url/main.css")

Reexports

pub extern crate idna;

Modules

form_urlencoded	Parser and serializer for the `application/x-www-form-urlencoded` syntax, as used by HTML forms.
percent_encoding
quirks	Getters and setters for URL components implemented per https://url.spec.whatwg.org/#api

Macros

define_encode_set!

Define a new struct that implements the EncodeSet trait, for use in percent_decode() and related functions.

Structs

HostAndPort	This mostly exists because coherence rules don’t allow us to implement `ToSocketAddrs for (Host<S>, u16)`.
OpaqueOrigin	Opaque identifier for URLs that have file or other schemes
ParseOptions	Full configuration for the URL parser.
SocketAddrs	Socket addresses for an URL.
Url	A parsed URL record.
UrlQuery	Implementation detail of `Url::query_pairs_mut`. Typically not used directly.

Enums

Host	The host name of an URL.
Origin	The origin of an URL
ParseError	Errors that can occur during parsing.
Position	Indicates a position within a URL based on its components.