# url - Rust
API documentation for the Rust `url` crate.
Keywords: rust, rustlang, rust-lang, url

# Crate url [−] [src]

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

# 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, Position};
    let issue_list_url = Url::parse(
        "https://github.com/rust-lang/rust/issues?labels=E-easy&state=open"
    )?;

    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[Position::BeforePath..] == "/rust-lang/rust/issues?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#")?;

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

## Serde

Enable the `serde` feature to include `Deserialize` and `Serialize` implementations for `url::Url`.

# Base URL

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

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

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

# Feature: `serde`

If you enable the `serde` feature, `Url` will implement `serde::Serialize` and `serde::Deserialize`. See serde documentation for more information.

    url = { version = "2", features = ["serde"] }

## Re-exports

`pub use form_urlencoded;`

## Structs

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.
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.
SyntaxViolation | Non-fatal syntax violations that can occur during parsing.

## Type Definitions

EncodingOverride |