Crate url [stability]
[-]
[+]
[src]
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()].as_slice())); 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());
Reexports
pub use percent_encoding::{percent_decode, percent_decode_to, percent_encode, percent_encode_to, utf8_percent_encode, utf8_percent_encode_to, lossy_utf8_percent_decode, SIMPLE_ENCODE_SET, QUERY_ENCODE_SET, DEFAULT_ENCODE_SET, USERINFO_ENCODE_SET, PASSWORD_ENCODE_SET, USERNAME_ENCODE_SET, FORM_URLENCODED_ENCODE_SET, EncodeSet}; |
Modules
form_urlencoded | Parser and serializer for the |
format | Formatting utilities for URLs. |
percent_encoding | |
punycode | Punycode (RFC 3492) implementation. |
Structs
Ipv6Address | A 128 bit IPv6 address |
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. |
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. |
Traits
FromUrlPath | |
ToUrlPath |
Functions
parse_path | Parse |
whatwg_scheme_type_mapper |
Type Definitions
ErrorHandler | This is called on non-fatal parse errors. |
ParseResult |