Crate url

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"

This will automatically pull in the rust-encoding dependency.

rust-url is a replacement of the url crate currently distributed with Rust. rust-url’s crate is also named url. Cargo will automatically resolve the name conflict, but that means that you can not also use the old url in the same crate.

If you’re not using Cargo, you’ll need to pass --extern url=/path/to/liburl.rlib explicitly to rustc.

URL parsing and data structures

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

use url::{Url, InvalidIpv6Address};

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

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

use url::{Url, RelativeSchemeData, NonRelativeSchemeData};

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".to_string());
assert!(issue_list_url.domain() == Some("github.com"));
assert!(issue_list_url.port() == None);
assert!(issue_list_url.path() == Some(["rust-lang".to_string(),
                                        "rust".to_string(),
                                        "issues".to_string()].as_slice()));
assert!(issue_list_url.query == Some("labels=E-easy&state=open".to_string()));
assert!(issue_list_url.fragment == None);
match issue_list_url.scheme_data {
    RelativeSchemeData(..) => {},  // Expected
    NonRelativeSchemeData(..) => fail!(),
}

The scheme, query, and fragment are directly fields of the Url struct: they apply to all URLs. Every other components has accessors because they only apply to URLs said to be “in a relative scheme”. https is a relative scheme, but data is not:

use url::{Url, NonRelativeSchemeData};

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

assert!(data_url.scheme == "data".to_string());
assert!(data_url.scheme_data == NonRelativeSchemeData("text/plain,Hello".to_string()));
assert!(data_url.non_relative_scheme_data() == Some("text/plain,Hello"));
assert!(data_url.query == None);
assert!(data_url.fragment == Some("".to_string()));

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:

use url::{Url, RelativeUrlWithoutBase};

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

UrlParser is a method-chaining API to provide various optional parameters to URL parsing, including a base URL.

use url::{Url, UrlParser};

let this_document = Url::parse("http://servo.github.io/rust-url/url/index.html").unwrap();
let css_url = UrlParser::new().base_url(&this_document).parse("../main.css").unwrap();
assert!(css_url.serialize() == "http://servo.github.io/rust-url/main.css".to_string());

Reexports

pub use host::{Domain, Ipv6};

pub use parser::{EmptyHost, InvalidScheme, InvalidPort, InvalidIpv6Address, InvalidDomainCharacter, InvalidCharacter, InvalidBackslash, InvalidPercentEncoded, InvalidAtSymbolInUser, ExpectedTwoSlashes, NonUrlCodePoint, RelativeUrlWithScheme, RelativeUrlWithoutBase, RelativeUrlWithNonRelativeBase, NonAsciiDomainsNotSupportedYet, CannotSetFileScheme, CannotSetJavascriptScheme, CannotSetNonRelativeScheme};

pub use percent_encoding::{percent_decode, percent_decode_to, percent_encode, percent_encode_to, utf8_percent_encode, utf8_percent_encode_to, lossy_utf8_percent_decode, SIMPLE_ENCODE_SET, QUERY_ENCODE_SET, DEFAULT_ENCODE_SET, USERINFO_ENCODE_SET, PASSWORD_ENCODE_SET, USERNAME_ENCODE_SET, FORM_URLENCODED_ENCODE_SET, EncodeSet};

Modules

form_urlencoded	Parser and serializer for the application/x-www-form-urlencoded format, as used by HTML forms.
format	Formatting utilities for URLs.
percent_encoding
punycode	Punycode (RFC 3492) implementation.

Structs

Ipv6Address	A 128 bit IPv6 address
Url	The parsed representation of an absolute URL.
UrlParser	A set of optional parameters for URL parsing.
UrlRelativeSchemeData	Components for URLs in a relative scheme such as HTTP.

Enums

Host	The host name of an URL.
ParseError	Errors that can occur during parsing.
SchemeData	The components of the URL whose representation depends on where the scheme is relative.
SchemeType	Determines the behavior of the URL parser for a given scheme.

Traits

FromUrlPath
ToUrlPath

Functions

parse_path	Parse input as a “standalone” URL path, with an optional query string and fragment identifier.
whatwg_scheme_type_mapper	http://url.spec.whatwg.org/#relative-scheme

Type Definitions

ErrorHandler	This is called on non-fatal parse errors.
ParseResult