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

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

use url::{Url, SchemeData};

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()][..]));
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 {
    SchemeData::Relative(..) => {},  // Expected
    SchemeData::NonRelative(..) => panic!(),
}

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, SchemeData};

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

assert!(data_url.scheme == "data".to_string());
assert!(data_url.scheme_data == SchemeData::NonRelative("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, ParseError};

assert!(Url::parse("../main.css") == Err(ParseError::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());

For convenience, the join method on Url is also provided to achieve the same result:

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!(&*css_url.serialize() == "http://servo.github.io/rust-url/main.css")

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.

urlutils

These methods are not meant for use in Rust code, only to help implement the JavaScript URLUtils API: http://url.spec.whatwg.org/#urlutils

Structs

OpaqueOrigin

Opaque identifier for URLs that have file or other schemes

RelativeSchemeData

Components for URLs in a relative scheme such as HTTP.

Url

The parsed representation of an absolute URL.

UrlParser

A set of optional parameters for URL parsing.

Enums

Host

The host name of an URL.

Origin

The origin of the 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.

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