#parse-url #whatwg #parser #standard

url

URL library for Rust, based on the WHATWG URL Standard

80 releases (29 stable)

2.5.0 Nov 22, 2023
2.4.0 Jun 5, 2023
2.3.1 Sep 8, 2022
2.2.2 May 7, 2021
0.2.1 Nov 24, 2014

#5 in Parser implementations

Download history 1620007/week @ 2023-11-26 1581877/week @ 2023-12-03 1577097/week @ 2023-12-10 1391645/week @ 2023-12-17 853112/week @ 2023-12-24 1317359/week @ 2023-12-31 1572889/week @ 2024-01-07 1625616/week @ 2024-01-14 1716314/week @ 2024-01-21 1851846/week @ 2024-01-28 1898815/week @ 2024-02-04 1846040/week @ 2024-02-11 1835457/week @ 2024-02-18 1962137/week @ 2024-02-25 1954989/week @ 2024-03-03 754768/week @ 2024-03-10

6,630,849 downloads per month
Used in 24,228 crates (5,312 directly)

MIT/Apache

790KB
17K SLoC

rust-url

Build status Coverage Chat License: MIT License: Apache 2.0

URL library for Rust, based on the URL Standard.

Documentation

Please see UPGRADING.md if you are upgrading from a previous version.


lib.rs:

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"] }

Feature: debugger_visualizer

If you enable the debugger_visualizer feature, the url crate will include a natvis file for Visual Studio that allows you to view Url objects in the debugger.

This feature requires Rust 1.71 or later.

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

Dependencies

~0.8–1.2MB
~47K SLoC