[go: up one dir, main page]

Crate url

source ·
Expand description

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

Modules§

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 Aliases§