Lines Matching full:url
1 // Copyright 2013-2015 The rust-url developers.
11 rust-url is an implementation of the [URL Standard](http://url.spec.whatwg.org/)
15 # URL parsing and data structures
17 First, URL parsing may fail for various reasons and therefore returns a `Result`.
20 use url::{Url, ParseError};
22 assert!(Url::parse("http://[:::1]") == Err(ParseError::InvalidIpv6Address))
25 Let’s parse a valid URL and look at its components.
28 use url::{Url, Host, Position};
29 # use url::ParseError;
31 let issue_list_url = Url::parse(
59 use url::Url;
60 # use url::ParseError;
63 let data_url = Url::parse("data:text/plain,Hello?World#")?;
78 Enable the `serde` feature to include `Deserialize` and `Serialize` implementations for `url::Url`.
80 # Base URL
82 Many contexts allow URL *references* that can be relative to a *base URL*:
91 use url::{Url, ParseError};
93 assert!(Url::parse("../main.css") == Err(ParseError::RelativeUrlWithoutBase))
96 Use the `join` method on an `Url` to use it as a base URL:
99 use url::Url;
100 # use url::ParseError;
103 let this_document = Url::parse("http://servo.github.io/rust-url/url/index.html")?;
105 assert_eq!(css_url.as_str(), "http://servo.github.io/rust-url/main.css");
113 If you enable the `serde` feature, [`Url`](struct.Url.html) will implement
119 url = { version = "2", features = ["serde"] }
123 #![doc(html_root_url = "https://docs.rs/url/2.2.2")]
164 /// A parsed URL record.
166 pub struct Url { struct
169 /// url = scheme ":" [ hierarchical | non-hierarchical ] [ "?" query ]? [ "#" fragment ]?
190 /// Full configuration for the URL parser.
193 base_url: Option<&'a Url>, argument
199 /// Change the base URL
200 pub fn base_url(mut self, new: Option<&'a Url>) -> Self { in base_url()
220 /// use url::{Url, SyntaxViolation};
221 /// # use url::ParseError;
222 /// # fn run() -> Result<(), url::ParseError> {
224 /// let url = Url::options()
227 /// assert_eq!(url.as_str(), "https://example.com/");
239 /// Parse an URL string with the configuration so far.
240 pub fn parse(self, input: &str) -> Result<Url, crate::ParseError> { in parse() argument
252 impl Url { implementation
253 /// Parse an absolute URL from a string.
258 /// use url::Url;
259 /// # use url::ParseError;
262 /// let url = Url::parse("https://example.net")?;
270 /// If the function can not parse an absolute URL from the given string,
275 pub fn parse(input: &str) -> Result<Url, crate::ParseError> { in parse() argument
276 Url::options().parse(input) in parse()
279 /// Parse an absolute URL from a string and add params to its query string.
286 /// use url::Url;
287 /// # use url::ParseError;
290 /// let url = Url::parse_with_params("https://example.net?dont=clobberme",
292 /// assert_eq!("https://example.net/?dont=clobberme&lang=rust&browser=servo", url.as_str());
300 /// If the function can not parse an absolute URL from the given string,
305 pub fn parse_with_params<I, K, V>(input: &str, iter: I) -> Result<Url, crate::ParseError> in parse_with_params() argument
312 let mut url = Url::options().parse(input); in parse_with_params() localVariable
314 if let Ok(ref mut url) = url { in parse_with_params()
315 url.query_pairs_mut().extend_pairs(iter); in parse_with_params()
318 url in parse_with_params()
321 /// Parse a string as an URL, with this URL as the base URL.
332 /// use url::Url;
333 /// # use url::ParseError;
336 /// let base = Url::parse("https://example.net/a/b.html")?;
337 /// let url = base.join("c.png")?;
338 /// assert_eq!(url.as_str(), "https://example.net/a/c.png"); // Not /a/b.html/c.png
340 /// let base = Url::parse("https://example.net/a/b/")?;
341 /// let url = base.join("c.png")?;
342 /// assert_eq!(url.as_str(), "https://example.net/a/b/c.png");
350 /// If the function can not parse an URL from the given string
351 /// with this URL as the base URL, a [`ParseError`] variant will be returned.
356 pub fn join(&self, input: &str) -> Result<Url, crate::ParseError> { in join() argument
357 Url::options().base_url(Some(self)).parse(input) in join()
360 /// Creates a relative URL if possible, with this URL as the base URL.
367 /// use url::Url;
368 /// # use url::ParseError;
371 /// let base = Url::parse("https://example.net/a/b.html")?;
372 /// let url = Url::parse("https://example.net/a/c.png")?;
373 /// let relative = base.make_relative(&url);
376 /// let base = Url::parse("https://example.net/a/b/")?;
377 /// let url = Url::parse("https://example.net/a/b/c.png")?;
378 /// let relative = base.make_relative(&url);
381 /// let base = Url::parse("https://example.net/a/b/")?;
382 /// let url = Url::parse("https://example.net/a/d/c.png")?;
383 /// let relative = base.make_relative(&url);
386 /// let base = Url::parse("https://example.net/a/b.html?c=d")?;
387 /// let url = Url::parse("https://example.net/a/b.html?e=f")?;
388 /// let relative = base.make_relative(&url);
397 /// If this URL can't be a base for the given URL, `None` is returned.
401 pub fn make_relative(&self, url: &Url) -> Option<String> { in make_relative()
407 if self.scheme() != url.scheme() || self.host() != url.host() || self.port() != url.port() { in make_relative()
428 let (url_path, url_filename) = extract_path_filename(url.path()); in make_relative()
479 if let Some(query) = url.query() { in make_relative()
484 if let Some(fragment) = url.fragment() { in make_relative()
492 /// Return a default `ParseOptions` that can fully configure the URL parser.
496 /// Get default `ParseOptions`, then change base url
499 /// use url::Url;
500 /// # use url::ParseError;
502 /// let options = Url::options();
503 /// let api = Url::parse("https://api.example.com")?;
519 /// Return the serialization of this URL.
521 /// This is fast since that serialization is already stored in the `Url` struct.
526 /// use url::Url;
527 /// # use url::ParseError;
531 /// let url = Url::parse(url_str)?;
532 /// assert_eq!(url.as_str(), url_str);
542 /// Return the serialization of this URL.
544 /// This consumes the `Url` and takes ownership of the `String` stored in it.
549 /// use url::Url;
550 /// # use url::ParseError;
554 /// let url = Url::parse(url_str)?;
555 /// assert_eq!(String::from(url), url_str);
568 /// Methods of the `Url` struct assume a number of invariants.
570 /// This is for testing rust-url itself.
577 "!( {} ) for URL {:?}", in check_invariants()
591 return Err(format!("{:?} != {:?} ({} != {}) for URL {:?}", in check_invariants()
608 // URL with authority in check_invariants()
650 // Anarchist URL (no authority) in check_invariants()
670 let other = Url::parse(self.as_str()).expect("Failed to parse myself?"); in check_invariants()
679 // See https://github.com/whatwg/url/issues/79 in check_invariants()
689 /// Return the origin of this URL (<https://url.spec.whatwg.org/#origin>)
692 /// `url.origin() != url.origin()`.
696 /// URL with `ftp` scheme:
699 /// use url::{Host, Origin, Url};
700 /// # use url::ParseError;
703 /// let url = Url::parse("ftp://example.com/foo")?;
704 /// assert_eq!(url.origin(),
713 /// URL with `blob` scheme:
716 /// use url::{Host, Origin, Url};
717 /// # use url::ParseError;
720 /// let url = Url::parse("blob:https://example.com/foo")?;
721 /// assert_eq!(url.origin(),
730 /// URL with `file` scheme:
733 /// use url::{Host, Origin, Url};
734 /// # use url::ParseError;
737 /// let url = Url::parse("file:///tmp/foo")?;
738 /// assert!(!url.origin().is_tuple());
740 /// let other_url = Url::parse("file:///tmp/foo")?;
741 /// assert!(url.origin() != other_url.origin());
747 /// URL with other scheme:
750 /// use url::{Host, Origin, Url};
751 /// # use url::ParseError;
754 /// let url = Url::parse("foo:bar")?;
755 /// assert!(!url.origin().is_tuple());
765 /// Return the scheme of this URL, lower-cased, as an ASCII string without the ':' delimiter.
770 /// use url::Url;
771 /// # use url::ParseError;
774 /// let url = Url::parse("file:///tmp/foo")?;
775 /// assert_eq!(url.scheme(), "file");
785 /// Return whether the URL has an 'authority',
794 /// use url::Url;
795 /// # use url::ParseError;
798 /// let url = Url::parse("ftp://rms@example.com")?;
799 /// assert!(url.has_authority());
801 /// let url = Url::parse("unix:/run/foo.socket")?;
802 /// assert!(!url.has_authority());
804 /// let url = Url::parse("data:text/plain,Stuff")?;
805 /// assert!(!url.has_authority());
816 /// Return whether this URL is a cannot-be-a-base URL,
817 /// meaning that parsing a relative URL string with this URL as the base will return an error.
825 /// use url::Url;
826 /// # use url::ParseError;
829 /// let url = Url::parse("ftp://rms@example.com")?;
830 /// assert!(!url.cannot_be_a_base());
832 /// let url = Url::parse("unix:/run/foo.socket")?;
833 /// assert!(!url.cannot_be_a_base());
835 /// let url = Url::parse("data:text/plain,Stuff")?;
836 /// assert!(url.cannot_be_a_base());
846 /// Return the username for this URL (typically the empty string)
852 /// use url::Url;
853 /// # use url::ParseError;
856 /// let url = Url::parse("ftp://rms@example.com")?;
857 /// assert_eq!(url.username(), "rms");
859 /// let url = Url::parse("ftp://:secret123@example.com")?;
860 /// assert_eq!(url.username(), "");
862 /// let url = Url::parse("https://example.com")?;
863 /// assert_eq!(url.username(), "");
877 /// Return the password for this URL, if any, as a percent-encoded ASCII string.
882 /// use url::Url;
883 /// # use url::ParseError;
886 /// let url = Url::parse("ftp://rms:secret123@example.com")?;
887 /// assert_eq!(url.password(), Some("secret123"));
889 /// let url = Url::parse("ftp://:secret123@example.com")?;
890 /// assert_eq!(url.password(), Some("secret123"));
892 /// let url = Url::parse("ftp://rms@example.com")?;
893 /// assert_eq!(url.password(), None);
895 /// let url = Url::parse("https://example.com")?;
896 /// assert_eq!(url.password(), None);
915 /// Equivalent to `url.host().is_some()`.
920 /// use url::Url;
921 /// # use url::ParseError;
924 /// let url = Url::parse("ftp://rms@example.com")?;
925 /// assert!(url.has_host());
927 /// let url = Url::parse("unix:/run/foo.socket")?;
928 /// assert!(!url.has_host());
930 /// let url = Url::parse("data:text/plain,Stuff")?;
931 /// assert!(!url.has_host());
940 /// Return the string representation of the host (domain or IP address) for this URL, if any.
943 /// of a special URL, or percent encoded for non-special URLs.
954 /// use url::Url;
955 /// # use url::ParseError;
958 /// let url = Url::parse("https://127.0.0.1/index.html")?;
959 /// assert_eq!(url.host_str(), Some("127.0.0.1"));
961 /// let url = Url::parse("ftp://rms@example.com")?;
962 /// assert_eq!(url.host_str(), Some("example.com"));
964 /// let url = Url::parse("unix:/run/foo.socket")?;
965 /// assert_eq!(url.host_str(), None);
967 /// let url = Url::parse("data:text/plain,Stuff")?;
968 /// assert_eq!(url.host_str(), None);
981 /// Return the parsed representation of the host for this URL.
983 /// of a special URL, or percent encoded for non-special URLs.
993 /// use url::Url;
994 /// # use url::ParseError;
997 /// let url = Url::parse("https://127.0.0.1/index.html")?;
998 /// assert!(url.host().is_some());
1000 /// let url = Url::parse("ftp://rms@example.com")?;
1001 /// assert!(url.host().is_some());
1003 /// let url = Url::parse("unix:/run/foo.socket")?;
1004 /// assert!(url.host().is_none());
1006 /// let url = Url::parse("data:text/plain,Stuff")?;
1007 /// assert!(url.host().is_none());
1021 /// If this URL has a host and it is a domain name (not an IP address), return it.
1023 /// of a special URL, or percent encoded for non-special URLs.
1028 /// use url::Url;
1029 /// # use url::ParseError;
1032 /// let url = Url::parse("https://127.0.0.1/")?;
1033 /// assert_eq!(url.domain(), None);
1035 /// let url = Url::parse("mailto:rms@example.net")?;
1036 /// assert_eq!(url.domain(), None);
1038 /// let url = Url::parse("https://example.com/")?;
1039 /// assert_eq!(url.domain(), Some("example.com"));
1051 /// Return the port number for this URL, if any.
1059 /// use url::Url;
1060 /// # use url::ParseError;
1063 /// let url = Url::parse("https://example.com")?;
1064 /// assert_eq!(url.port(), None);
1066 /// let url = Url::parse("https://example.com:443/")?;
1067 /// assert_eq!(url.port(), None);
1069 /// let url = Url::parse("ssh://example.com:22")?;
1070 /// assert_eq!(url.port(), Some(22));
1080 /// Return the port number for this URL, or the default port number if it is known.
1086 /// For other schemes, it is the same as `Url::port()`.
1091 /// use url::Url;
1092 /// # use url::ParseError;
1095 /// let url = Url::parse("foo://example.com")?;
1096 /// assert_eq!(url.port_or_known_default(), None);
1098 /// let url = Url::parse("foo://example.com:1456")?;
1099 /// assert_eq!(url.port_or_known_default(), Some(1456));
1101 /// let url = Url::parse("https://example.com")?;
1102 /// assert_eq!(url.port_or_known_default(), Some(443));
1112 /// Resolve a URL’s host and port number to `SocketAddr`.
1114 /// If the URL has the default port number of a scheme that is unknown to this library,
1117 /// or by matching on the URL’s `.scheme()`.
1124 /// let url = url::Url::parse("https://example.net/").unwrap();
1125 /// let addrs = url.socket_addrs(|| None).unwrap();
1132 /// fn socket_addrs(url: url::Url) -> std::io::Result<Vec<std::net::SocketAddr>> {
1133 /// url.socket_addrs(|| match url.scheme() {
1155 let host = io_result(self.host(), "No host name in the URL")?; in socket_addrs()
1158 "No port number in the URL", in socket_addrs()
1167 /// Return the path for this URL, as a percent-encoded ASCII string.
1175 /// use url::{Url, ParseError};
1178 /// let url = Url::parse("https://example.com/api/versions?page=2")?;
1179 /// assert_eq!(url.path(), "/api/versions");
1181 /// let url = Url::parse("https://example.com")?;
1182 /// assert_eq!(url.path(), "/");
1184 /// let url = Url::parse("https://example.com/countries/việt nam")?;
1185 /// assert_eq!(url.path(), "/countries/vi%E1%BB%87t%20nam");
1199 /// Unless this URL is cannot-be-a-base,
1211 /// use url::Url;
1215 /// let url = Url::parse("https://example.com/foo/bar")?;
1216 /// let mut path_segments = url.path_segments().ok_or_else(|| "cannot be base")?;
1221 /// let url = Url::parse("https://example.com")?;
1222 /// let mut path_segments = url.path_segments().ok_or_else(|| "cannot be base")?;
1226 /// let url = Url::parse("data:text/plain,HelloWorld")?;
1227 /// assert!(url.path_segments().is_none());
1229 /// let url = Url::parse("https://example.com/countries/việt nam")?;
1230 /// let mut path_segments = url.path_segments().ok_or_else(|| "cannot be base")?;
1247 /// Return this URL’s query string, if any, as a percent-encoded ASCII string.
1252 /// use url::Url;
1253 /// # use url::ParseError;
1256 /// let url = Url::parse("https://example.com/products?page=2")?;
1257 /// let query = url.query();
1260 /// let url = Url::parse("https://example.com/products")?;
1261 /// let query = url.query();
1264 /// let url = Url::parse("https://example.com/?country=español")?;
1265 /// let query = url.query();
1285 /// Parse the URL’s query string, if any, as `application/x-www-form-urlencoded`
1293 /// use url::Url;
1294 /// # use url::ParseError;
1297 /// let url = Url::parse("https://example.com/products?page=2&sort=desc")?;
1298 /// let mut pairs = url.query_pairs();
1314 /// Return this URL’s fragment identifier, if any.
1316 /// A fragment is the part of the URL after the `#` symbol.
1323 /// of a URL to the server.
1331 /// use url::Url;
1332 /// # use url::ParseError;
1335 /// let url = Url::parse("https://example.com/data.csv#row=4")?;
1337 /// assert_eq!(url.fragment(), Some("row=4"));
1339 /// let url = Url::parse("https://example.com/data.csv#cell=4,1-6,2")?;
1341 /// assert_eq!(url.fragment(), Some("cell=4,1-6,2"));
1360 /// Change this URL’s fragment identifier.
1365 /// use url::Url;
1366 /// # use url::ParseError;
1369 /// let mut url = Url::parse("https://example.com/data.csv")?;
1370 /// assert_eq!(url.as_str(), "https://example.com/data.csv");
1372 /// url.set_fragment(Some("cell=4,1-6,2"));
1373 /// assert_eq!(url.as_str(), "https://example.com/data.csv#cell=4,1-6,2");
1374 /// assert_eq!(url.fragment(), Some("cell=4,1-6,2"));
1376 /// url.set_fragment(None);
1377 /// assert_eq!(url.as_str(), "https://example.com/data.csv");
1378 /// assert!(url.fragment().is_none());
1417 /// Change this URL’s query string.
1422 /// use url::Url;
1423 /// # use url::ParseError;
1426 /// let mut url = Url::parse("https://example.com/products")?;
1427 /// assert_eq!(url.as_str(), "https://example.com/products");
1429 /// url.set_query(Some("page=2"));
1430 /// assert_eq!(url.as_str(), "https://example.com/products?page=2");
1431 /// assert_eq!(url.query(), Some("page=2"));
1463 /// Manipulate this URL’s query string, viewed as a sequence of name/value pairs
1469 /// # use url::{Url, ParseError};
1472 /// let mut url = Url::parse("https://example.net?lang=fr#nav")?;
1473 /// assert_eq!(url.query(), Some("lang=fr"));
1475 /// url.query_pairs_mut().append_pair("foo", "bar");
1476 /// assert_eq!(url.query(), Some("lang=fr&foo=bar"));
1477 /// assert_eq!(url.as_str(), "https://example.net/?lang=fr&foo=bar#nav");
1479 /// url.query_pairs_mut()
1483 /// assert_eq!(url.query(), Some("foo=bar+%26+baz&saisons=%C3%89t%C3%A9%2Bhiver"));
1484 /// assert_eq!(url.as_str(),
1491 /// Note: `url.query_pairs_mut().clear();` is equivalent to `url.set_query(Some(""))`,
1492 /// not `url.set_query(None)`.
1494 /// The state of `Url` is unspecified if this return value is leaked without being dropped.
1509 url: Some(self), in query_pairs_mut()
1526 /// Change this URL’s path.
1531 /// use url::Url;
1532 /// # use url::ParseError;
1535 /// let mut url = Url::parse("https://example.com")?;
1536 /// url.set_path("api/comments");
1537 /// assert_eq!(url.as_str(), "https://example.com/api/comments");
1538 /// assert_eq!(url.path(), "/api/comments");
1540 /// let mut url = Url::parse("https://example.com/api")?;
1541 /// url.set_path("data/report.csv");
1542 /// assert_eq!(url.as_str(), "https://example.com/data/report.csv");
1543 /// assert_eq!(url.path(), "/data/report.csv");
1569 /// Return an object with methods to manipulate this URL’s path segments.
1571 /// Return `Err(())` if this URL is cannot-be-a-base.
1596 /// Change this URL’s port number.
1600 /// If this URL is cannot-be-a-base, does not have a host, or has the `file` scheme;
1606 /// use url::Url;
1610 /// let mut url = Url::parse("ssh://example.net:2048/")?;
1612 /// url.set_port(Some(4096)).map_err(|_| "cannot be base")?;
1613 /// assert_eq!(url.as_str(), "ssh://example.net:4096/");
1615 /// url.set_port(None).map_err(|_| "cannot be base")?;
1616 /// assert_eq!(url.as_str(), "ssh://example.net/");
1625 /// use url::Url;
1629 /// let mut url = Url::parse("https://example.org/")?;
1631 /// url.set_port(Some(443)).map_err(|_| "cannot be base")?;
1632 /// assert!(url.port().is_none());
1641 /// use url::Url;
1642 /// # use url::ParseError;
1645 /// let mut url = Url::parse("mailto:rms@example.net")?;
1647 /// let result = url.set_port(Some(80));
1650 /// let result = url.set_port(None);
1708 /// Change this URL’s host.
1718 /// use url::Url;
1719 /// # use url::ParseError;
1722 /// let mut url = Url::parse("https://example.net")?;
1723 /// let result = url.set_host(Some("rust-lang.org"));
1725 /// assert_eq!(url.as_str(), "https://rust-lang.org/");
1734 /// use url::Url;
1735 /// # use url::ParseError;
1738 /// let mut url = Url::parse("foo://example.net")?;
1739 /// let result = url.set_host(None);
1741 /// assert_eq!(url.as_str(), "foo:/");
1750 /// use url::Url;
1751 /// # use url::ParseError;
1754 /// let mut url = Url::parse("https://example.net")?;
1755 /// let result = url.set_host(None);
1757 /// assert_eq!(url.as_str(), "https://example.net/");
1766 /// use url::Url;
1767 /// # use url::ParseError;
1770 /// let mut url = Url::parse("mailto:rms@example.net")?;
1772 /// let result = url.set_host(Some("rust-lang.org"));
1774 /// assert_eq!(url.as_str(), "mailto:rms@example.net");
1776 /// let result = url.set_host(None);
1778 /// assert_eq!(url.as_str(), "mailto:rms@example.net");
1786 /// If this URL is cannot-be-a-base or there is an error parsing the given `host`,
1890 /// Change this URL’s host to the given IP address.
1892 /// If this URL is cannot-be-a-base, do nothing and return `Err`.
1894 /// Compared to `Url::set_host`, this skips the host parser.
1899 /// use url::{Url, ParseError};
1902 /// let mut url = Url::parse("http://example.com")?;
1903 /// url.set_ip_host("127.0.0.1".parse().unwrap());
1904 /// assert_eq!(url.host_str(), Some("127.0.0.1"));
1905 /// assert_eq!(url.as_str(), "http://127.0.0.1/");
1911 /// Cannot change URL's from mailto(cannot-be-base) to ip:
1914 /// use url::{Url, ParseError};
1917 /// let mut url = Url::parse("mailto:rms@example.com")?;
1918 /// let result = url.set_ip_host("127.0.0.1".parse().unwrap());
1920 /// assert_eq!(url.as_str(), "mailto:rms@example.com");
1941 /// Change this URL’s password.
1943 /// If this URL is cannot-be-a-base or does not have a host, do nothing and return `Err`.
1948 /// use url::{Url, ParseError};
1951 /// let mut url = Url::parse("mailto:rmz@example.com")?;
1952 /// let result = url.set_password(Some("secret_password"));
1955 /// let mut url = Url::parse("ftp://user1:secret1@example.com")?;
1956 /// let result = url.set_password(Some("secret_password"));
1957 /// assert_eq!(url.password(), Some("secret_password"));
1959 /// let mut url = Url::parse("ftp://user2:@example.com")?;
1960 /// let result = url.set_password(Some("secret2"));
1962 /// assert_eq!(url.password(), Some("secret2"));
2025 /// Change this URL’s username.
2027 /// If this URL is cannot-be-a-base or does not have a host, do nothing and return `Err`.
2033 /// use url::{Url, ParseError};
2036 /// let mut url = Url::parse("mailto:rmz@example.com")?;
2037 /// let result = url.set_username("user1");
2038 /// assert_eq!(url.as_str(), "mailto:rmz@example.com");
2048 /// use url::{Url, ParseError};
2051 /// let mut url = Url::parse("ftp://:secre1@example.com/")?;
2052 /// let result = url.set_username("user1");
2054 /// assert_eq!(url.username(), "user1");
2055 /// assert_eq!(url.as_str(), "ftp://user1:secre1@example.com/");
2112 /// Change this URL’s scheme.
2117 /// * If this URL is cannot-be-a-base and the new scheme is one of
2121 /// * If the new scheme is `file` and this URL includes credentials
2123 /// * If this URL's scheme is `file` and its host is empty or null
2125 /// See also [the URL specification's section on legal scheme state
2126 /// overrides](https://url.spec.whatwg.org/#scheme-state).
2130 /// Change the URL’s scheme from `https` to `foo`:
2133 /// use url::Url;
2134 /// # use url::ParseError;
2137 /// let mut url = Url::parse("https://example.net")?;
2138 /// let result = url.set_scheme("http");
2139 /// assert_eq!(url.as_str(), "http://example.net/");
2145 /// Change the URL’s scheme from `foo` to `bar`:
2148 /// use url::Url;
2149 /// # use url::ParseError;
2152 /// let mut url = Url::parse("foo://example.net")?;
2153 /// let result = url.set_scheme("bar");
2154 /// assert_eq!(url.as_str(), "bar://example.net");
2161 /// Cannot change URL’s scheme from `https` to `foõ`:
2164 /// use url::Url;
2165 /// # use url::ParseError;
2168 /// let mut url = Url::parse("https://example.net")?;
2169 /// let result = url.set_scheme("foõ");
2170 /// assert_eq!(url.as_str(), "https://example.net/");
2177 /// Cannot change URL’s scheme from `mailto` (cannot-be-a-base) to `https`:
2180 /// use url::Url;
2181 /// # use url::ParseError;
2184 /// let mut url = Url::parse("mailto:rms@example.net")?;
2185 /// let result = url.set_scheme("https");
2186 /// assert_eq!(url.as_str(), "mailto:rms@example.net");
2192 /// Cannot change the URL’s scheme from `foo` to `https`:
2195 /// use url::Url;
2196 /// # use url::ParseError;
2199 /// let mut url = Url::parse("foo://example.net")?;
2200 /// let result = url.set_scheme("https");
2201 /// assert_eq!(url.as_str(), "foo://example.net");
2207 /// Cannot change the URL’s scheme from `http` to `foo`:
2210 /// use url::Url;
2211 /// # use url::ParseError;
2214 /// let mut url = Url::parse("http://example.net")?;
2215 /// let result = url.set_scheme("foo");
2216 /// assert_eq!(url.as_str(), "http://example.net/");
2228 // If url’s scheme is a special scheme and buffer is not a special scheme, then return. in set_scheme()
2230 // If url’s scheme is not a special scheme and buffer is a special scheme, then return. in set_scheme()
2232 … // If url includes credentials or has a non-null port, and buffer is "file", then return. in set_scheme()
2233 // If url’s scheme is "file" and its host is an empty host or null, then return. in set_scheme()
2274 /// Convert a file name as `std::path::Path` into an URL in the `file` scheme.
2285 /// use url::Url;
2288 /// let url = Url::from_file_path("/tmp/foo.txt")?;
2289 /// assert_eq!(url.as_str(), "file:///tmp/foo.txt");
2291 /// let url = Url::from_file_path("../foo.txt");
2292 /// assert!(url.is_err());
2294 /// let url = Url::from_file_path("https://google.com/");
2295 /// assert!(url.is_err());
2303 pub fn from_file_path<P: AsRef<Path>>(path: P) -> Result<Url, ()> { in from_file_path() argument
2307 Ok(Url { in from_file_path()
2321 /// Convert a directory name as `std::path::Path` into an URL in the `file` scheme.
2326 /// Compared to `from_file_path`, this ensure that URL’s the path has a trailing slash
2327 /// so that the entire path is considered when using this URL as a base URL.
2331 /// * `"index.html"` parsed with `Url::from_directory_path(Path::new("/var/www"))`
2332 /// as the base URL is `file:///var/www/index.html`
2333 /// * `"index.html"` parsed with `Url::from_file_path(Path::new("/var/www"))`
2334 /// as the base URL is `file:///var/index.html`, which might not be what was intended.
2340 pub fn from_directory_path<P: AsRef<Path>>(path: P) -> Result<Url, ()> { in from_directory_path() argument
2341 let mut url = Url::from_file_path(path)?; in from_directory_path() localVariable
2342 if !url.serialization.ends_with('/') { in from_directory_path()
2343 url.serialization.push('/') in from_directory_path()
2345 Ok(url) in from_directory_path()
2348 /// Serialize with Serde using the internal representation of the `Url` struct.
2363 let Url { in serialize_internal() localVariable
2390 /// Serialize with Serde using the internal representation of the `Url` struct.
2415 let url = Url { in deserialize_internal() localVariable
2428 url.check_invariants().map_err(|reason| { in deserialize_internal()
2433 Ok(url) in deserialize_internal()
2436 /// Assuming the URL is in the `file` scheme or similar,
2439 /// **Note:** This does not actually check the URL’s `scheme`,
2441 /// It is the user’s responsibility to check the URL’s scheme before calling this.
2444 /// # use url::Url;
2445 /// # let url = Url::parse("file:///etc/passwd").unwrap();
2446 /// let path = url.to_file_path();
2488 /// Parse a string as an URL, without a base URL or encoding override.
2489 impl str::FromStr for Url { implementation
2493 fn from_str(input: &str) -> Result<Url, crate::ParseError> { in from_str() argument
2494 Url::parse(input) in from_str()
2498 impl<'a> TryFrom<&'a str> for Url { implementation
2502 Url::parse(s) in try_from()
2506 /// Display the serialization of this URL.
2507 impl fmt::Display for Url { implementation
2515 impl From<Url> for String {
2516 fn from(value: Url) -> String { in from()
2521 /// Debug the serialization of this URL.
2522 impl fmt::Debug for Url { implementation
2526 .debug_struct("Url") in fmt()
2541 impl Eq for Url {} implementation
2544 impl PartialEq for Url { implementation
2552 impl Ord for Url { implementation
2560 impl PartialOrd for Url { implementation
2568 impl hash::Hash for Url { implementation
2578 /// Return the serialization of this URL.
2579 impl AsRef<str> for Url { implementation
2611 /// Serializes this URL into a `serde` stream.
2615 impl serde::Serialize for Url { implementation
2624 /// Deserializes this URL from a `serde` stream.
2628 impl<'de> serde::Deserialize<'de> for Url { implementation
2629 fn deserialize<D>(deserializer: D) -> Result<Url, D::Error> in deserialize() argument
2638 type Value = Url; in deserialize()
2641 formatter.write_str("a string representing an URL") in deserialize()
2648 Url::parse(s).map_err(|err| { in deserialize()
2680 // An URL’s path must not be empty. in path_to_file_url_segments()
2694 // Build this unconditionally to alleviate https://github.com/servo/rust-url/issues/102
2799 // Build this unconditionally to alleviate https://github.com/servo/rust-url/issues/102
2852 /// Implementation detail of `Url::query_pairs_mut`. Typically not used directly.
2855 url: Option<&'a mut Url>, field
2859 // `as_mut_string` string here exposes the internal serialization of an `Url`,
2866 // `Url::query_pairs_mut` which is `Serializer<UrlQuery>`
2871 &mut self.url.as_mut().unwrap().serialization in as_mut_string()
2874 fn finish(mut self) -> &'a mut Url { in finish() argument
2875 let url = self.url.take().unwrap(); in finish() localVariable
2876 url.restore_already_parsed_fragment(self.fragment.take()); in finish()
2877 url in finish()
2880 type Finished = &'a mut Url;
2885 if let Some(url) = self.url.take() { in drop()
2886 url.restore_already_parsed_fragment(self.fragment.take()) in drop()