Crate url [] [src]

Fork me on GitHub

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

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

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

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.

PathSegmentsMut

Exposes methods to manipulate the path of an URL that is not cannot-be-base.

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.