Examples
Doctests
Aggregated doctests across the workspace.
Doctests
67 runnable examples.
url::path_segments::PathSegmentsMut
use url::Url;
let mut url = Url::parse("mailto:me@example.com")?;
assert!(url.path_segments_mut().is_err());
let mut url = Url::parse("http://example.net/foo/index.html")?;
url.path_segments_mut().map_err(|_| "cannot be base")?
.pop().push("img").push("2/100%.png");
assert_eq!(url.as_str(), "http://example.net/foo/img/2%2F100%25.png");
clear
use url::Url;
let mut url = Url::parse("https://github.com/servo/rust-url/")?;
url.path_segments_mut().map_err(|_| "cannot be base")?
.clear().push("logout");
assert_eq!(url.as_str(), "https://github.com/logout");
pop_if_empty
use url::Url;
let mut url = Url::parse("https://github.com/servo/rust-url/")?;
url.path_segments_mut().map_err(|_| "cannot be base")?
.push("pulls");
assert_eq!(url.as_str(), "https://github.com/servo/rust-url//pulls");
let mut url = Url::parse("https://github.com/servo/rust-url/")?;
url.path_segments_mut().map_err(|_| "cannot be base")?
.pop_if_empty().push("pulls");
assert_eq!(url.as_str(), "https://github.com/servo/rust-url/pulls");
extend
use url::Url;
let mut url = Url::parse("https://github.com/")?;
let org = "servo";
let repo = "rust-url";
let issue_number = "188";
url.path_segments_mut().map_err(|_| "cannot be base")?
.extend(&[org, repo, "issues", issue_number]);
assert_eq!(url.as_str(), "https://github.com/servo/rust-url/issues/188");
extend
use url::Url;
let mut url = Url::parse("https://github.com/servo")?;
url.path_segments_mut().map_err(|_| "cannot be base")?
.extend(&["..", "rust-url", ".", "pulls"]);
assert_eq!(url.as_str(), "https://github.com/servo/rust-url/pulls");
url::slicing::Position
let serialization: &str = &some_url[..];
let serialization_without_fragment: &str = &some_url[..Position::AfterQuery];
let authority: &str = &some_url[Position::BeforeUsername..Position::AfterPort];
let data_url_payload: &str = &some_url[Position::BeforePath..Position::AfterQuery];
let scheme_relative: &str = &some_url[Position::BeforeUsername..];
parse
use url::Url;
let url = Url::parse("https://example.net")?;
parse_with_params
use url::Url;
let url = Url::parse_with_params("https://example.net?dont=clobberme",
&[("lang", "rust"), ("browser", "servo")])?;
assert_eq!("https://example.net/?dont=clobberme&lang=rust&browser=servo", url.as_str());
join
use url::Url;
// Base without a trailing slash
let base = Url::parse("https://example.net/a/b.html")?;
let url = base.join("c.png")?;
assert_eq!(url.as_str(), "https://example.net/a/c.png"); // Not /a/b.html/c.png
// Base with a trailing slash
let base = Url::parse("https://example.net/a/b/")?;
let url = base.join("c.png")?;
assert_eq!(url.as_str(), "https://example.net/a/b/c.png");
// Input as scheme relative special URL
let base = Url::parse("https://alice.com/a")?;
let url = base.join("//eve.com/b")?;
assert_eq!(url.as_str(), "https://eve.com/b");
// Input as base url relative special URL
let base = Url::parse("https://alice.com/a")?;
let url = base.join("/v1/meta")?;
assert_eq!(url.as_str(), "https://alice.com/v1/meta");
// Input as absolute URL
let base = Url::parse("https://alice.com/a")?;
let url = base.join("http://eve.com/b")?;
assert_eq!(url.as_str(), "http://eve.com/b"); // http instead of https
make_relative
use url::Url;
let base = Url::parse("https://example.net/a/b.html")?;
let url = Url::parse("https://example.net/a/c.png")?;
let relative = base.make_relative(&url);
assert_eq!(relative.as_ref().map(|s| s.as_str()), Some("c.png"));
let base = Url::parse("https://example.net/a/b/")?;
let url = Url::parse("https://example.net/a/b/c.png")?;
let relative = base.make_relative(&url);
assert_eq!(relative.as_ref().map(|s| s.as_str()), Some("c.png"));
let base = Url::parse("https://example.net/a/b/")?;
let url = Url::parse("https://example.net/a/d/c.png")?;
let relative = base.make_relative(&url);
assert_eq!(relative.as_ref().map(|s| s.as_str()), Some("../d/c.png"));
let base = Url::parse("https://example.net/a/b.html?c=d")?;
let url = Url::parse("https://example.net/a/b.html?e=f")?;
let relative = base.make_relative(&url);
assert_eq!(relative.as_ref().map(|s| s.as_str()), Some("?e=f"));
options
use url::Url;
let options = Url::options();
let api = Url::parse("https://api.example.com")?;
let base_url = options.base_url(Some(&api));
let version_url = base_url.parse("version.json")?;
assert_eq!(version_url.as_str(), "https://api.example.com/version.json");
as_str
use url::Url;
let url_str = "https://example.net/";
let url = Url::parse(url_str)?;
assert_eq!(url.as_str(), url_str);
into_string
use url::Url;
let url_str = "https://example.net/";
let url = Url::parse(url_str)?;
assert_eq!(String::from(url), url_str);
origin
use url::{Host, Origin, Url};
let url = Url::parse("ftp://example.com/foo")?;
assert_eq!(url.origin(),
Origin::Tuple("ftp".into(),
Host::Domain("example.com".into()),
21));
origin
use url::{Host, Origin, Url};
let url = Url::parse("blob:https://example.com/foo")?;
assert_eq!(url.origin(),
Origin::Tuple("https".into(),
Host::Domain("example.com".into()),
443));
origin
use url::{Host, Origin, Url};
let url = Url::parse("file:///tmp/foo")?;
assert!(!url.origin().is_tuple());
let other_url = Url::parse("file:///tmp/foo")?;
assert!(url.origin() != other_url.origin());
origin
use url::{Host, Origin, Url};
let url = Url::parse("foo:bar")?;
assert!(!url.origin().is_tuple());
scheme
use url::Url;
let url = Url::parse("file:///tmp/foo")?;
assert_eq!(url.scheme(), "file");
is_special
use url::Url;
assert!(Url::parse("http:///tmp/foo")?.is_special());
assert!(Url::parse("file:///tmp/foo")?.is_special());
assert!(!Url::parse("moz:///tmp/foo")?.is_special());
has_authority
use url::Url;
let url = Url::parse("ftp://rms@example.com")?;
assert!(url.has_authority());
let url = Url::parse("unix:/run/foo.socket")?;
assert!(!url.has_authority());
let url = Url::parse("data:text/plain,Stuff")?;
assert!(!url.has_authority());
authority
use url::Url;
let url = Url::parse("unix:/run/foo.socket")?;
assert_eq!(url.authority(), "");
let url = Url::parse("file:///tmp/foo")?;
assert_eq!(url.authority(), "");
let url = Url::parse("https://user:password@example.com/tmp/foo")?;
assert_eq!(url.authority(), "user:password@example.com");
let url = Url::parse("irc://àlex.рф.example.com:6667/foo")?;
assert_eq!(url.authority(), "%C3%A0lex.%D1%80%D1%84.example.com:6667");
let url = Url::parse("http://àlex.рф.example.com:80/foo")?;
assert_eq!(url.authority(), "xn--lex-8ka.xn--p1ai.example.com");
cannot_be_a_base
use url::Url;
let url = Url::parse("ftp://rms@example.com")?;
assert!(!url.cannot_be_a_base());
let url = Url::parse("unix:/run/foo.socket")?;
assert!(!url.cannot_be_a_base());
let url = Url::parse("data:text/plain,Stuff")?;
assert!(url.cannot_be_a_base());
username
use url::Url;
let url = Url::parse("ftp://rms@example.com")?;
assert_eq!(url.username(), "rms");
let url = Url::parse("ftp://:secret123@example.com")?;
assert_eq!(url.username(), "");
let url = Url::parse("https://example.com")?;
assert_eq!(url.username(), "");
password
use url::Url;
let url = Url::parse("ftp://rms:secret123@example.com")?;
assert_eq!(url.password(), Some("secret123"));
let url = Url::parse("ftp://:secret123@example.com")?;
assert_eq!(url.password(), Some("secret123"));
let url = Url::parse("ftp://rms@example.com")?;
assert_eq!(url.password(), None);
let url = Url::parse("https://example.com")?;
assert_eq!(url.password(), None);
has_host
use url::Url;
let url = Url::parse("ftp://rms@example.com")?;
assert!(url.has_host());
let url = Url::parse("unix:/run/foo.socket")?;
assert!(!url.has_host());
let url = Url::parse("data:text/plain,Stuff")?;
assert!(!url.has_host());
host_str
use url::Url;
let url = Url::parse("https://127.0.0.1/index.html")?;
assert_eq!(url.host_str(), Some("127.0.0.1"));
let url = Url::parse("https://subdomain.example.com")?;
assert_eq!(url.host_str(), Some("subdomain.example.com"));
let url = Url::parse("ftp://rms@example.com")?;
assert_eq!(url.host_str(), Some("example.com"));
let url = Url::parse("unix:/run/foo.socket")?;
assert_eq!(url.host_str(), None);
let url = Url::parse("data:text/plain,Stuff")?;
assert_eq!(url.host_str(), None);
host
use url::Url;
let url = Url::parse("https://127.0.0.1/index.html")?;
assert!(url.host().is_some());
let url = Url::parse("ftp://rms@example.com")?;
assert!(url.host().is_some());
let url = Url::parse("unix:/run/foo.socket")?;
assert!(url.host().is_none());
let url = Url::parse("data:text/plain,Stuff")?;
assert!(url.host().is_none());
domain
use url::Url;
let url = Url::parse("https://127.0.0.1/")?;
assert_eq!(url.domain(), None);
let url = Url::parse("mailto:rms@example.net")?;
assert_eq!(url.domain(), None);
let url = Url::parse("https://example.com/")?;
assert_eq!(url.domain(), Some("example.com"));
let url = Url::parse("https://subdomain.example.com/")?;
assert_eq!(url.domain(), Some("subdomain.example.com"));
port
use url::Url;
let url = Url::parse("https://example.com")?;
assert_eq!(url.port(), None);
let url = Url::parse("https://example.com:443/")?;
assert_eq!(url.port(), None);
let url = Url::parse("ssh://example.com:22")?;
assert_eq!(url.port(), Some(22));
port_or_known_default
use url::Url;
let url = Url::parse("foo://example.com")?;
assert_eq!(url.port_or_known_default(), None);
let url = Url::parse("foo://example.com:1456")?;
assert_eq!(url.port_or_known_default(), Some(1456));
let url = Url::parse("https://example.com")?;
assert_eq!(url.port_or_known_default(), Some(443));
socket_addrs
no_run
let url = url::Url::parse("https://example.net/").unwrap();
let addrs = url.socket_addrs(|| None).unwrap();
std::net::TcpStream::connect(&*addrs)
socket_addrs
/// With application-specific known default port numbers
fn socket_addrs(url: url::Url) -> std::io::Result<Vec<std::net::SocketAddr>> {
url.socket_addrs(|| match url.scheme() {
"socks5" | "socks5h" => Some(1080),
_ => None,
})
}
path
use url::{Url, ParseError};
let url = Url::parse("https://example.com/api/versions?page=2")?;
assert_eq!(url.path(), "/api/versions");
let url = Url::parse("https://example.com")?;
assert_eq!(url.path(), "/");
let url = Url::parse("https://example.com/countries/việt nam")?;
assert_eq!(url.path(), "/countries/vi%E1%BB%87t%20nam");
path_segments
use url::Url;
let url = Url::parse("https://example.com/foo/bar")?;
let mut path_segments = url.path_segments().ok_or_else(|| "cannot be base")?;
assert_eq!(path_segments.next(), Some("foo"));
assert_eq!(path_segments.next(), Some("bar"));
assert_eq!(path_segments.next(), None);
let url = Url::parse("https://example.com")?;
let mut path_segments = url.path_segments().ok_or_else(|| "cannot be base")?;
assert_eq!(path_segments.next(), Some(""));
assert_eq!(path_segments.next(), None);
let url = Url::parse("data:text/plain,HelloWorld")?;
assert!(url.path_segments().is_none());
let url = Url::parse("https://example.com/countries/việt nam")?;
let mut path_segments = url.path_segments().ok_or_else(|| "cannot be base")?;
assert_eq!(path_segments.next(), Some("countries"));
assert_eq!(path_segments.next(), Some("vi%E1%BB%87t%20nam"));
query
use url::Url;
fn run() -> Result<(), ParseError> {
let url = Url::parse("https://example.com/products?page=2")?;
let query = url.query();
assert_eq!(query, Some("page=2"));
let url = Url::parse("https://example.com/products")?;
let query = url.query();
assert!(query.is_none());
let url = Url::parse("https://example.com/?country=español")?;
let query = url.query();
assert_eq!(query, Some("country=espa%C3%B1ol"));
query_pairs
use std::borrow::Cow;
use url::Url;
let url = Url::parse("https://example.com/products?page=2&sort=desc")?;
let mut pairs = url.query_pairs();
assert_eq!(pairs.count(), 2);
assert_eq!(pairs.next(), Some((Cow::Borrowed("page"), Cow::Borrowed("2"))));
assert_eq!(pairs.next(), Some((Cow::Borrowed("sort"), Cow::Borrowed("desc"))));
fragment
use url::Url;
let url = Url::parse("https://example.com/data.csv#row=4")?;
assert_eq!(url.fragment(), Some("row=4"));
let url = Url::parse("https://example.com/data.csv#cell=4,1-6,2")?;
assert_eq!(url.fragment(), Some("cell=4,1-6,2"));
set_fragment
use url::Url;
let mut url = Url::parse("https://example.com/data.csv")?;
assert_eq!(url.as_str(), "https://example.com/data.csv");
url.set_fragment(Some("cell=4,1-6,2"));
assert_eq!(url.as_str(), "https://example.com/data.csv#cell=4,1-6,2");
assert_eq!(url.fragment(), Some("cell=4,1-6,2"));
url.set_fragment(None);
assert_eq!(url.as_str(), "https://example.com/data.csv");
assert!(url.fragment().is_none());
set_query
use url::Url;
let mut url = Url::parse("https://example.com/products")?;
assert_eq!(url.as_str(), "https://example.com/products");
url.set_query(Some("page=2"));
assert_eq!(url.as_str(), "https://example.com/products?page=2");
assert_eq!(url.query(), Some("page=2"));
query_pairs_mut
let mut url = Url::parse("https://example.net?lang=fr#nav")?;
assert_eq!(url.query(), Some("lang=fr"));
url.query_pairs_mut().append_pair("foo", "bar");
assert_eq!(url.query(), Some("lang=fr&foo=bar"));
assert_eq!(url.as_str(), "https://example.net/?lang=fr&foo=bar#nav");
url.query_pairs_mut()
.clear()
.append_pair("foo", "bar & baz")
.append_pair("saisons", "\u{00C9}t\u{00E9}+hiver");
assert_eq!(url.query(), Some("foo=bar+%26+baz&saisons=%C3%89t%C3%A9%2Bhiver"));
assert_eq!(url.as_str(),
"https://example.net/?foo=bar+%26+baz&saisons=%C3%89t%C3%A9%2Bhiver#nav");
set_path
use url::Url;
let mut url = Url::parse("https://example.com")?;
url.set_path("api/comments");
assert_eq!(url.as_str(), "https://example.com/api/comments");
assert_eq!(url.path(), "/api/comments");
let mut url = Url::parse("https://example.com/api")?;
url.set_path("data/report.csv");
assert_eq!(url.as_str(), "https://example.com/data/report.csv");
assert_eq!(url.path(), "/data/report.csv");
// `set_path` percent-encodes the given string if it's not already percent-encoded.
let mut url = Url::parse("https://example.com")?;
url.set_path("api/some comments");
assert_eq!(url.as_str(), "https://example.com/api/some%20comments");
assert_eq!(url.path(), "/api/some%20comments");
// `set_path` will not double percent-encode the string if it's already percent-encoded.
let mut url = Url::parse("https://example.com")?;
url.set_path("api/some%20comments");
assert_eq!(url.as_str(), "https://example.com/api/some%20comments");
assert_eq!(url.path(), "/api/some%20comments");
set_port
use url::Url;
let mut url = Url::parse("ssh://example.net:2048/")?;
url.set_port(Some(4096)).map_err(|_| "cannot be base")?;
assert_eq!(url.as_str(), "ssh://example.net:4096/");
url.set_port(None).map_err(|_| "cannot be base")?;
assert_eq!(url.as_str(), "ssh://example.net/");
set_port
use url::Url;
let mut url = Url::parse("https://example.org/")?;
url.set_port(Some(443)).map_err(|_| "cannot be base")?;
assert!(url.port().is_none());
set_port
use url::Url;
let mut url = Url::parse("mailto:rms@example.net")?;
let result = url.set_port(Some(80));
assert!(result.is_err());
let result = url.set_port(None);
assert!(result.is_err());
set_host
use url::Url;
let mut url = Url::parse("https://example.net")?;
let result = url.set_host(Some("rust-lang.org"));
assert!(result.is_ok());
assert_eq!(url.as_str(), "https://rust-lang.org/");
set_host
use url::Url;
let mut url = Url::parse("foo://example.net")?;
let result = url.set_host(None);
assert!(result.is_ok());
assert_eq!(url.as_str(), "foo:/");
set_host
use url::Url;
let mut url = Url::parse("https://example.net")?;
let result = url.set_host(None);
assert!(result.is_err());
assert_eq!(url.as_str(), "https://example.net/");
set_host
use url::Url;
let mut url = Url::parse("mailto:rms@example.net")?;
let result = url.set_host(Some("rust-lang.org"));
assert!(result.is_err());
assert_eq!(url.as_str(), "mailto:rms@example.net");
let result = url.set_host(None);
assert!(result.is_err());
assert_eq!(url.as_str(), "mailto:rms@example.net");
set_ip_host
use url::{Url, ParseError};
let mut url = Url::parse("http://example.com")?;
url.set_ip_host("127.0.0.1".parse().unwrap());
assert_eq!(url.host_str(), Some("127.0.0.1"));
assert_eq!(url.as_str(), "http://127.0.0.1/");
set_ip_host
use url::{Url, ParseError};
let mut url = Url::parse("mailto:rms@example.com")?;
let result = url.set_ip_host("127.0.0.1".parse().unwrap());
assert_eq!(url.as_str(), "mailto:rms@example.com");
assert!(result.is_err());
set_password
use url::{Url, ParseError};
let mut url = Url::parse("mailto:rmz@example.com")?;
let result = url.set_password(Some("secret_password"));
assert!(result.is_err());
let mut url = Url::parse("ftp://user1:secret1@example.com")?;
let result = url.set_password(Some("secret_password"));
assert_eq!(url.password(), Some("secret_password"));
let mut url = Url::parse("ftp://user2:@example.com")?;
let result = url.set_password(Some("secret2"));
assert!(result.is_ok());
assert_eq!(url.password(), Some("secret2"));
set_username
use url::{Url, ParseError};
let mut url = Url::parse("mailto:rmz@example.com")?;
let result = url.set_username("user1");
assert_eq!(url.as_str(), "mailto:rmz@example.com");
assert!(result.is_err());
set_username
use url::{Url, ParseError};
let mut url = Url::parse("ftp://:secre1@example.com/")?;
let result = url.set_username("user1");
assert!(result.is_ok());
assert_eq!(url.username(), "user1");
assert_eq!(url.as_str(), "ftp://user1:secre1@example.com/");
set_scheme
use url::Url;
let mut url = Url::parse("https://example.net")?;
let result = url.set_scheme("http");
assert_eq!(url.as_str(), "http://example.net/");
assert!(result.is_ok());
set_scheme
use url::Url;
let mut url = Url::parse("foo://example.net")?;
let result = url.set_scheme("bar");
assert_eq!(url.as_str(), "bar://example.net");
assert!(result.is_ok());
set_scheme
use url::Url;
let mut url = Url::parse("https://example.net")?;
let result = url.set_scheme("foõ");
assert_eq!(url.as_str(), "https://example.net/");
assert!(result.is_err());
set_scheme
use url::Url;
let mut url = Url::parse("mailto:rms@example.net")?;
let result = url.set_scheme("https");
assert_eq!(url.as_str(), "mailto:rms@example.net");
assert!(result.is_err());
set_scheme
use url::Url;
let mut url = Url::parse("foo://example.net")?;
let result = url.set_scheme("https");
assert_eq!(url.as_str(), "foo://example.net");
assert!(result.is_err());
set_scheme
use url::Url;
let mut url = Url::parse("http://example.net")?;
let result = url.set_scheme("foo");
assert_eq!(url.as_str(), "http://example.net/");
assert!(result.is_err());
from_file_path
use url::Url;
let url = Url::from_file_path("/tmp/foo.txt")?;
assert_eq!(url.as_str(), "file:///tmp/foo.txt");
let url = Url::from_file_path("../foo.txt");
assert!(url.is_err());
let url = Url::from_file_path("https://google.com/");
assert!(url.is_err());
to_file_path
let path = url.to_file_path();
syntax_violation_callback
use std::cell::RefCell;
use url::{Url, SyntaxViolation};
let violations = RefCell::new(Vec::new());
let url = Url::options()
.syntax_violation_callback(Some(&|v| violations.borrow_mut().push(v)))
.parse("https:////example.com")?;
assert_eq!(url.as_str(), "https://example.com/");
assert_eq!(violations.into_inner(),
vec!(SyntaxViolation::ExpectedDoubleSlash));
url
use url::{Url, ParseError};
assert!(Url::parse("http://[:::1]") == Err(ParseError::InvalidIpv6Address))
url
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());
url
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(""));
url
use url::{Url, ParseError};
assert!(Url::parse("../main.css") == Err(ParseError::RelativeUrlWithoutBase))
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");