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"] }
124 If you enable the `debugger_visualizer` feature, the `url` crate will include
127 [`Url`](struct.Url.html) objects in the debugger.
132 url = { version = "2", features = ["debugger_visualizer"] }
137 #![doc(html_root_url = "https://docs.rs/url/2.5.2")]
140 debugger_visualizer(natvis_file = "../../debug_metadata/url.natvis")
185 /// A parsed URL record.
187 pub struct Url { struct
190 /// url = scheme ":" [ hierarchical | non-hierarchical ] [ "?" query ]? [ "#" fragment ]?
211 /// Full configuration for the URL parser.
215 base_url: Option<&'a Url>, argument
221 /// Change the base URL
223 /// See the notes of [`Url::join`] for more details about how this base is considered
225 pub fn base_url(mut self, new: Option<&'a Url>) -> Self { in base_url()
245 /// use url::{Url, SyntaxViolation};
246 /// # use url::ParseError;
247 /// # fn run() -> Result<(), url::ParseError> {
249 /// let url = Url::options()
252 /// assert_eq!(url.as_str(), "https://example.com/");
264 /// Parse an URL string with the configuration so far.
265 pub fn parse(self, input: &str) -> Result<Url, crate::ParseError> { in parse() argument
277 impl Url { implementation
278 /// Parse an absolute URL from a string.
283 /// use url::Url;
284 /// # use url::ParseError;
287 /// let url = Url::parse("https://example.net")?;
295 /// If the function can not parse an absolute URL from the given string,
300 pub fn parse(input: &str) -> Result<Url, crate::ParseError> { in parse() argument
301 Url::options().parse(input) in parse()
304 /// Parse an absolute URL from a string and add params to its query string.
311 /// use url::Url;
312 /// # use url::ParseError;
315 /// let url = Url::parse_with_params("https://example.net?dont=clobberme",
317 /// assert_eq!("https://example.net/?dont=clobberme&lang=rust&browser=servo", url.as_str());
325 /// If the function can not parse an absolute URL from the given string,
330 pub fn parse_with_params<I, K, V>(input: &str, iter: I) -> Result<Url, crate::ParseError> in parse_with_params() argument
337 let mut url = Url::options().parse(input); in parse_with_params() localVariable
339 if let Ok(ref mut url) = url { in parse_with_params()
340 url.query_pairs_mut().extend_pairs(iter); in parse_with_params()
343 url in parse_with_params()
346 /// https://url.spec.whatwg.org/#potentially-strip-trailing-spaces-from-an-opaque-path
372 /// Parse a string as an URL, with this URL as the base URL.
381 …/// - A [scheme relative special URL](https://url.spec.whatwg.org/#scheme-relative-special-url-str…
382 /// as input replaces everything in the base URL after the scheme.
383 /// - An absolute URL (with a scheme) as input replaces the whole base URL (even the scheme).
388 /// use url::Url;
389 /// # use url::ParseError;
393 /// let base = Url::parse("https://example.net/a/b.html")?;
394 /// let url = base.join("c.png")?;
395 /// assert_eq!(url.as_str(), "https://example.net/a/c.png"); // Not /a/b.html/c.png
398 /// let base = Url::parse("https://example.net/a/b/")?;
399 /// let url = base.join("c.png")?;
400 /// assert_eq!(url.as_str(), "https://example.net/a/b/c.png");
402 /// // Input as scheme relative special URL
403 /// let base = Url::parse("https://alice.com/a")?;
404 /// let url = base.join("//eve.com/b")?;
405 /// assert_eq!(url.as_str(), "https://eve.com/b");
407 /// // Input as absolute URL
408 /// let base = Url::parse("https://alice.com/a")?;
409 /// let url = base.join("http://eve.com/b")?;
410 /// assert_eq!(url.as_str(), "http://eve.com/b"); // http instead of https
419 /// If the function can not parse an URL from the given string
420 /// with this URL as the base URL, a [`ParseError`] variant will be returned.
425 pub fn join(&self, input: &str) -> Result<Url, crate::ParseError> { in join() argument
426 Url::options().base_url(Some(self)).parse(input) in join()
429 /// Creates a relative URL if possible, with this URL as the base URL.
436 /// use url::Url;
437 /// # use url::ParseError;
440 /// let base = Url::parse("https://example.net/a/b.html")?;
441 /// let url = Url::parse("https://example.net/a/c.png")?;
442 /// let relative = base.make_relative(&url);
445 /// let base = Url::parse("https://example.net/a/b/")?;
446 /// let url = Url::parse("https://example.net/a/b/c.png")?;
447 /// let relative = base.make_relative(&url);
450 /// let base = Url::parse("https://example.net/a/b/")?;
451 /// let url = Url::parse("https://example.net/a/d/c.png")?;
452 /// let relative = base.make_relative(&url);
455 /// let base = Url::parse("https://example.net/a/b.html?c=d")?;
456 /// let url = Url::parse("https://example.net/a/b.html?e=f")?;
457 /// let relative = base.make_relative(&url);
466 /// If this URL can't be a base for the given URL, `None` is returned.
470 pub fn make_relative(&self, url: &Url) -> Option<String> { in make_relative()
476 if self.scheme() != url.scheme() || self.host() != url.host() || self.port() != url.port() { in make_relative()
497 let (url_path, url_filename) = extract_path_filename(url.path()); in make_relative()
548 if let Some(query) = url.query() { in make_relative()
553 if let Some(fragment) = url.fragment() { in make_relative()
561 /// Return a default `ParseOptions` that can fully configure the URL parser.
565 /// Get default `ParseOptions`, then change base url
568 /// use url::Url;
569 /// # use url::ParseError;
571 /// let options = Url::options();
572 /// let api = Url::parse("https://api.example.com")?;
588 /// Return the serialization of this URL.
590 /// This is fast since that serialization is already stored in the `Url` struct.
595 /// use url::Url;
596 /// # use url::ParseError;
600 /// let url = Url::parse(url_str)?;
601 /// assert_eq!(url.as_str(), url_str);
611 /// Return the serialization of this URL.
613 /// This consumes the `Url` and takes ownership of the `String` stored in it.
618 /// use url::Url;
619 /// # use url::ParseError;
623 /// let url = Url::parse(url_str)?;
624 /// assert_eq!(String::from(url), url_str);
637 /// Methods of the `Url` struct assume a number of invariants.
639 /// This is for testing rust-url itself.
646 "!( {} ) for URL {:?}", in check_invariants()
660 return Err(format!("{:?} != {:?} ({} != {}) for URL {:?}", in check_invariants()
677 // URL with authority in check_invariants()
719 // Anarchist URL (no authority) in check_invariants()
746 let other = Url::parse(self.as_str()).expect("Failed to parse myself?"); in check_invariants()
755 // See https://github.com/whatwg/url/issues/79 in check_invariants()
765 /// Return the origin of this URL (<https://url.spec.whatwg.org/#origin>)
768 /// `url.origin() != url.origin()`.
772 /// URL with `ftp` scheme:
775 /// use url::{Host, Origin, Url};
776 /// # use url::ParseError;
779 /// let url = Url::parse("ftp://example.com/foo")?;
780 /// assert_eq!(url.origin(),
789 /// URL with `blob` scheme:
792 /// use url::{Host, Origin, Url};
793 /// # use url::ParseError;
796 /// let url = Url::parse("blob:https://example.com/foo")?;
797 /// assert_eq!(url.origin(),
806 /// URL with `file` scheme:
809 /// use url::{Host, Origin, Url};
810 /// # use url::ParseError;
813 /// let url = Url::parse("file:///tmp/foo")?;
814 /// assert!(!url.origin().is_tuple());
816 /// let other_url = Url::parse("file:///tmp/foo")?;
817 /// assert!(url.origin() != other_url.origin());
823 /// URL with other scheme:
826 /// use url::{Host, Origin, Url};
827 /// # use url::ParseError;
830 /// let url = Url::parse("foo:bar")?;
831 /// assert!(!url.origin().is_tuple());
841 /// Return the scheme of this URL, lower-cased, as an ASCII string without the ':' delimiter.
846 /// use url::Url;
847 /// # use url::ParseError;
850 /// let url = Url::parse("file:///tmp/foo")?;
851 /// assert_eq!(url.scheme(), "file");
861 /// Return whether the URL is special (has a special scheme)
866 /// use url::Url;
867 /// # use url::ParseError;
870 /// assert!(Url::parse("http:///tmp/foo")?.is_special());
871 /// assert!(Url::parse("file:///tmp/foo")?.is_special());
872 /// assert!(!Url::parse("moz:///tmp/foo")?.is_special());
882 /// Return whether the URL has an 'authority',
893 /// use url::Url;
894 /// # use url::ParseError;
897 /// let url = Url::parse("ftp://rms@example.com")?;
898 /// assert!(url.has_authority());
900 /// let url = Url::parse("unix:/run/foo.socket")?;
901 /// assert!(!url.has_authority());
903 /// let url = Url::parse("data:text/plain,Stuff")?;
904 /// assert!(!url.has_authority());
915 /// Return the authority of this URL as an ASCII string.
918 /// of a special URL, or percent encoded for non-special URLs.
920 /// Ports are omitted if they match the well known port of a special URL.
929 /// use url::Url;
930 /// # use url::ParseError;
933 /// let url = Url::parse("unix:/run/foo.socket")?;
934 /// assert_eq!(url.authority(), "");
935 /// let url = Url::parse("file:///tmp/foo")?;
936 /// assert_eq!(url.authority(), "");
937 /// let url = Url::parse("https://user:password@example.com/tmp/foo")?;
938 /// assert_eq!(url.authority(), "user:password@example.com");
939 /// let url = Url::parse("irc://àlex.рф.example.com:6667/foo")?;
940 /// assert_eq!(url.authority(), "%C3%A0lex.%D1%80%D1%84.example.com:6667");
941 /// let url = Url::parse("http://àlex.рф.example.com:80/foo")?;
942 /// assert_eq!(url.authority(), "xn--lex-8ka.xn--p1ai.example.com");
956 /// Return whether this URL is a cannot-be-a-base URL,
957 /// meaning that parsing a relative URL string with this URL as the base will return an error.
965 /// use url::Url;
966 /// # use url::ParseError;
969 /// let url = Url::parse("ftp://rms@example.com")?;
970 /// assert!(!url.cannot_be_a_base());
972 /// let url = Url::parse("unix:/run/foo.socket")?;
973 /// assert!(!url.cannot_be_a_base());
975 /// let url = Url::parse("data:text/plain,Stuff")?;
976 /// assert!(url.cannot_be_a_base());
986 /// Return the username for this URL (typically the empty string)
992 /// use url::Url;
993 /// # use url::ParseError;
996 /// let url = Url::parse("ftp://rms@example.com")?;
997 /// assert_eq!(url.username(), "rms");
999 /// let url = Url::parse("ftp://:secret123@example.com")?;
1000 /// assert_eq!(url.username(), "");
1002 /// let url = Url::parse("https://example.com")?;
1003 /// assert_eq!(url.username(), "");
1017 /// Return the password for this URL, if any, as a percent-encoded ASCII string.
1022 /// use url::Url;
1023 /// # use url::ParseError;
1026 /// let url = Url::parse("ftp://rms:secret123@example.com")?;
1027 /// assert_eq!(url.password(), Some("secret123"));
1029 /// let url = Url::parse("ftp://:secret123@example.com")?;
1030 /// assert_eq!(url.password(), Some("secret123"));
1032 /// let url = Url::parse("ftp://rms@example.com")?;
1033 /// assert_eq!(url.password(), None);
1035 /// let url = Url::parse("https://example.com")?;
1036 /// assert_eq!(url.password(), None);
1055 /// Equivalent to `url.host().is_some()`.
1060 /// use url::Url;
1061 /// # use url::ParseError;
1064 /// let url = Url::parse("ftp://rms@example.com")?;
1065 /// assert!(url.has_host());
1067 /// let url = Url::parse("unix:/run/foo.socket")?;
1068 /// assert!(!url.has_host());
1070 /// let url = Url::parse("data:text/plain,Stuff")?;
1071 /// assert!(!url.has_host());
1080 /// Return the string representation of the host (domain or IP address) for this URL, if any.
1083 /// of a special URL, or percent encoded for non-special URLs.
1094 /// use url::Url;
1095 /// # use url::ParseError;
1098 /// let url = Url::parse("https://127.0.0.1/index.html")?;
1099 /// assert_eq!(url.host_str(), Some("127.0.0.1"));
1101 /// let url = Url::parse("ftp://rms@example.com")?;
1102 /// assert_eq!(url.host_str(), Some("example.com"));
1104 /// let url = Url::parse("unix:/run/foo.socket")?;
1105 /// assert_eq!(url.host_str(), None);
1107 /// let url = Url::parse("data:text/plain,Stuff")?;
1108 /// assert_eq!(url.host_str(), None);
1121 /// Return the parsed representation of the host for this URL.
1123 /// of a special URL, or percent encoded for non-special URLs.
1133 /// use url::Url;
1134 /// # use url::ParseError;
1137 /// let url = Url::parse("https://127.0.0.1/index.html")?;
1138 /// assert!(url.host().is_some());
1140 /// let url = Url::parse("ftp://rms@example.com")?;
1141 /// assert!(url.host().is_some());
1143 /// let url = Url::parse("unix:/run/foo.socket")?;
1144 /// assert!(url.host().is_none());
1146 /// let url = Url::parse("data:text/plain,Stuff")?;
1147 /// assert!(url.host().is_none());
1161 /// If this URL has a host and it is a domain name (not an IP address), return it.
1163 /// of a special URL, or percent encoded for non-special URLs.
1168 /// use url::Url;
1169 /// # use url::ParseError;
1172 /// let url = Url::parse("https://127.0.0.1/")?;
1173 /// assert_eq!(url.domain(), None);
1175 /// let url = Url::parse("mailto:rms@example.net")?;
1176 /// assert_eq!(url.domain(), None);
1178 /// let url = Url::parse("https://example.com/")?;
1179 /// assert_eq!(url.domain(), Some("example.com"));
1191 /// Return the port number for this URL, if any.
1199 /// use url::Url;
1200 /// # use url::ParseError;
1203 /// let url = Url::parse("https://example.com")?;
1204 /// assert_eq!(url.port(), None);
1206 /// let url = Url::parse("https://example.com:443/")?;
1207 /// assert_eq!(url.port(), None);
1209 /// let url = Url::parse("ssh://example.com:22")?;
1210 /// assert_eq!(url.port(), Some(22));
1220 /// Return the port number for this URL, or the default port number if it is known.
1226 /// For other schemes, it is the same as `Url::port()`.
1231 /// use url::Url;
1232 /// # use url::ParseError;
1235 /// let url = Url::parse("foo://example.com")?;
1236 /// assert_eq!(url.port_or_known_default(), None);
1238 /// let url = Url::parse("foo://example.com:1456")?;
1239 /// assert_eq!(url.port_or_known_default(), Some(1456));
1241 /// let url = Url::parse("https://example.com")?;
1242 /// assert_eq!(url.port_or_known_default(), Some(443));
1252 /// Resolve a URL’s host and port number to `SocketAddr`.
1254 /// If the URL has the default port number of a scheme that is unknown to this library,
1257 /// or by matching on the URL’s `.scheme()`.
1264 /// let url = url::Url::parse("https://example.net/").unwrap();
1265 /// let addrs = url.socket_addrs(|| None).unwrap();
1272 /// fn socket_addrs(url: url::Url) -> std::io::Result<Vec<std::net::SocketAddr>> {
1273 /// url.socket_addrs(|| match url.scheme() {
1296 let host = io_result(self.host(), "No host name in the URL")?; in socket_addrs()
1299 "No port number in the URL", in socket_addrs()
1308 /// Return the path for this URL, as a percent-encoded ASCII string.
1316 /// use url::{Url, ParseError};
1319 /// let url = Url::parse("https://example.com/api/versions?page=2")?;
1320 /// assert_eq!(url.path(), "/api/versions");
1322 /// let url = Url::parse("https://example.com")?;
1323 /// assert_eq!(url.path(), "/");
1325 /// let url = Url::parse("https://example.com/countries/việt nam")?;
1326 /// assert_eq!(url.path(), "/countries/vi%E1%BB%87t%20nam");
1340 /// Unless this URL is cannot-be-a-base,
1352 /// use url::Url;
1356 /// let url = Url::parse("https://example.com/foo/bar")?;
1357 /// let mut path_segments = url.path_segments().ok_or_else(|| "cannot be base")?;
1362 /// let url = Url::parse("https://example.com")?;
1363 /// let mut path_segments = url.path_segments().ok_or_else(|| "cannot be base")?;
1367 /// let url = Url::parse("data:text/plain,HelloWorld")?;
1368 /// assert!(url.path_segments().is_none());
1370 /// let url = Url::parse("https://example.com/countries/việt nam")?;
1371 /// let mut path_segments = url.path_segments().ok_or_else(|| "cannot be base")?;
1383 /// Return this URL’s query string, if any, as a percent-encoded ASCII string.
1388 /// use url::Url;
1389 /// # use url::ParseError;
1392 /// let url = Url::parse("https://example.com/products?page=2")?;
1393 /// let query = url.query();
1396 /// let url = Url::parse("https://example.com/products")?;
1397 /// let query = url.query();
1400 /// let url = Url::parse("https://example.com/?country=español")?;
1401 /// let query = url.query();
1421 /// Parse the URL’s query string, if any, as `application/x-www-form-urlencoded`
1429 /// use url::Url;
1430 /// # use url::ParseError;
1433 /// let url = Url::parse("https://example.com/products?page=2&sort=desc")?;
1434 /// let mut pairs = url.query_pairs();
1450 /// Return this URL’s fragment identifier, if any.
1452 /// A fragment is the part of the URL after the `#` symbol.
1459 /// of a URL to the server.
1467 /// use url::Url;
1468 /// # use url::ParseError;
1471 /// let url = Url::parse("https://example.com/data.csv#row=4")?;
1473 /// assert_eq!(url.fragment(), Some("row=4"));
1475 /// let url = Url::parse("https://example.com/data.csv#cell=4,1-6,2")?;
1477 /// assert_eq!(url.fragment(), Some("cell=4,1-6,2"));
1496 /// Change this URL’s fragment identifier.
1501 /// use url::Url;
1502 /// # use url::ParseError;
1505 /// let mut url = Url::parse("https://example.com/data.csv")?;
1506 /// assert_eq!(url.as_str(), "https://example.com/data.csv");
1508 /// url.set_fragment(Some("cell=4,1-6,2"));
1509 /// assert_eq!(url.as_str(), "https://example.com/data.csv#cell=4,1-6,2");
1510 /// assert_eq!(url.fragment(), Some("cell=4,1-6,2"));
1512 /// url.set_fragment(None);
1513 /// assert_eq!(url.as_str(), "https://example.com/data.csv");
1514 /// assert!(url.fragment().is_none());
1554 /// Change this URL’s query string. If `query` is `None`, this URL's
1560 /// use url::Url;
1561 /// # use url::ParseError;
1564 /// let mut url = Url::parse("https://example.com/products")?;
1565 /// assert_eq!(url.as_str(), "https://example.com/products");
1567 /// url.set_query(Some("page=2"));
1568 /// assert_eq!(url.as_str(), "https://example.com/products?page=2");
1569 /// assert_eq!(url.query(), Some("page=2"));
1606 /// Manipulate this URL’s query string, viewed as a sequence of name/value pairs
1612 /// # use url::{Url, ParseError};
1615 /// let mut url = Url::parse("https://example.net?lang=fr#nav")?;
1616 /// assert_eq!(url.query(), Some("lang=fr"));
1618 /// url.query_pairs_mut().append_pair("foo", "bar");
1619 /// assert_eq!(url.query(), Some("lang=fr&foo=bar"));
1620 /// assert_eq!(url.as_str(), "https://example.net/?lang=fr&foo=bar#nav");
1622 /// url.query_pairs_mut()
1626 /// assert_eq!(url.query(), Some("foo=bar+%26+baz&saisons=%C3%89t%C3%A9%2Bhiver"));
1627 /// assert_eq!(url.as_str(),
1634 /// Note: `url.query_pairs_mut().clear();` is equivalent to `url.set_query(Some(""))`,
1635 /// not `url.set_query(None)`.
1637 /// The state of `Url` is unspecified if this return value is leaked without being dropped.
1652 url: Some(self), in query_pairs_mut()
1669 /// Change this URL’s path.
1674 /// use url::Url;
1675 /// # use url::ParseError;
1678 /// let mut url = Url::parse("https://example.com")?;
1679 /// url.set_path("api/comments");
1680 /// assert_eq!(url.as_str(), "https://example.com/api/comments");
1681 /// assert_eq!(url.path(), "/api/comments");
1683 /// let mut url = Url::parse("https://example.com/api")?;
1684 /// url.set_path("data/report.csv");
1685 /// assert_eq!(url.as_str(), "https://example.com/data/report.csv");
1686 /// assert_eq!(url.path(), "/data/report.csv");
1689 /// let mut url = Url::parse("https://example.com")?;
1690 /// url.set_path("api/some comments");
1691 /// assert_eq!(url.as_str(), "https://example.com/api/some%20comments");
1692 /// assert_eq!(url.path(), "/api/some%20comments");
1695 /// let mut url = Url::parse("https://example.com")?;
1696 /// url.set_path("api/some%20comments");
1697 /// assert_eq!(url.as_str(), "https://example.com/api/some%20comments");
1698 /// assert_eq!(url.path(), "/api/some%20comments");
1729 /// Return an object with methods to manipulate this URL’s path segments.
1731 /// Return `Err(())` if this URL is cannot-be-a-base.
1756 /// Change this URL’s port number.
1760 /// If this URL is cannot-be-a-base, does not have a host, or has the `file` scheme;
1766 /// use url::Url;
1770 /// let mut url = Url::parse("ssh://example.net:2048/")?;
1772 /// url.set_port(Some(4096)).map_err(|_| "cannot be base")?;
1773 /// assert_eq!(url.as_str(), "ssh://example.net:4096/");
1775 /// url.set_port(None).map_err(|_| "cannot be base")?;
1776 /// assert_eq!(url.as_str(), "ssh://example.net/");
1785 /// use url::Url;
1789 /// let mut url = Url::parse("https://example.org/")?;
1791 /// url.set_port(Some(443)).map_err(|_| "cannot be base")?;
1792 /// assert!(url.port().is_none());
1801 /// use url::Url;
1802 /// # use url::ParseError;
1805 /// let mut url = Url::parse("mailto:rms@example.net")?;
1807 /// let result = url.set_port(Some(80));
1810 /// let result = url.set_port(None);
1868 /// Change this URL’s host.
1878 /// use url::Url;
1879 /// # use url::ParseError;
1882 /// let mut url = Url::parse("https://example.net")?;
1883 /// let result = url.set_host(Some("rust-lang.org"));
1885 /// assert_eq!(url.as_str(), "https://rust-lang.org/");
1894 /// use url::Url;
1895 /// # use url::ParseError;
1898 /// let mut url = Url::parse("foo://example.net")?;
1899 /// let result = url.set_host(None);
1901 /// assert_eq!(url.as_str(), "foo:/");
1910 /// use url::Url;
1911 /// # use url::ParseError;
1914 /// let mut url = Url::parse("https://example.net")?;
1915 /// let result = url.set_host(None);
1917 /// assert_eq!(url.as_str(), "https://example.net/");
1926 /// use url::Url;
1927 /// # use url::ParseError;
1930 /// let mut url = Url::parse("mailto:rms@example.net")?;
1932 /// let result = url.set_host(Some("rust-lang.org"));
1934 /// assert_eq!(url.as_str(), "mailto:rms@example.net");
1936 /// let result = url.set_host(None);
1938 /// assert_eq!(url.as_str(), "mailto:rms@example.net");
1946 /// If this URL is cannot-be-a-base or there is an error parsing the given `host`,
2057 /// Change this URL’s host to the given IP address.
2059 /// If this URL is cannot-be-a-base, do nothing and return `Err`.
2061 /// Compared to `Url::set_host`, this skips the host parser.
2066 /// use url::{Url, ParseError};
2069 /// let mut url = Url::parse("http://example.com")?;
2070 /// url.set_ip_host("127.0.0.1".parse().unwrap());
2071 /// assert_eq!(url.host_str(), Some("127.0.0.1"));
2072 /// assert_eq!(url.as_str(), "http://127.0.0.1/");
2078 /// Cannot change URL's from mailto(cannot-be-base) to ip:
2081 /// use url::{Url, ParseError};
2084 /// let mut url = Url::parse("mailto:rms@example.com")?;
2085 /// let result = url.set_ip_host("127.0.0.1".parse().unwrap());
2087 /// assert_eq!(url.as_str(), "mailto:rms@example.com");
2108 /// Change this URL’s password.
2110 /// If this URL is cannot-be-a-base or does not have a host, do nothing and return `Err`.
2115 /// use url::{Url, ParseError};
2118 /// let mut url = Url::parse("mailto:rmz@example.com")?;
2119 /// let result = url.set_password(Some("secret_password"));
2122 /// let mut url = Url::parse("ftp://user1:secret1@example.com")?;
2123 /// let result = url.set_password(Some("secret_password"));
2124 /// assert_eq!(url.password(), Some("secret_password"));
2126 /// let mut url = Url::parse("ftp://user2:@example.com")?;
2127 /// let result = url.set_password(Some("secret2"));
2129 /// assert_eq!(url.password(), Some("secret2"));
2193 /// Change this URL’s username.
2195 /// If this URL is cannot-be-a-base or does not have a host, do nothing and return `Err`.
2201 /// use url::{Url, ParseError};
2204 /// let mut url = Url::parse("mailto:rmz@example.com")?;
2205 /// let result = url.set_username("user1");
2206 /// assert_eq!(url.as_str(), "mailto:rmz@example.com");
2216 /// use url::{Url, ParseError};
2219 /// let mut url = Url::parse("ftp://:secre1@example.com/")?;
2220 /// let result = url.set_username("user1");
2222 /// assert_eq!(url.username(), "user1");
2223 /// assert_eq!(url.as_str(), "ftp://user1:secre1@example.com/");
2280 /// Change this URL’s scheme.
2285 /// * If this URL is cannot-be-a-base and the new scheme is one of
2289 /// * If the new scheme is `file` and this URL includes credentials
2291 /// * If this URL's scheme is `file` and its host is empty or null
2293 /// See also [the URL specification's section on legal scheme state
2294 /// overrides](https://url.spec.whatwg.org/#scheme-state).
2298 /// Change the URL’s scheme from `https` to `http`:
2301 /// use url::Url;
2302 /// # use url::ParseError;
2305 /// let mut url = Url::parse("https://example.net")?;
2306 /// let result = url.set_scheme("http");
2307 /// assert_eq!(url.as_str(), "http://example.net/");
2313 /// Change the URL’s scheme from `foo` to `bar`:
2316 /// use url::Url;
2317 /// # use url::ParseError;
2320 /// let mut url = Url::parse("foo://example.net")?;
2321 /// let result = url.set_scheme("bar");
2322 /// assert_eq!(url.as_str(), "bar://example.net");
2329 /// Cannot change URL’s scheme from `https` to `foõ`:
2332 /// use url::Url;
2333 /// # use url::ParseError;
2336 /// let mut url = Url::parse("https://example.net")?;
2337 /// let result = url.set_scheme("foõ");
2338 /// assert_eq!(url.as_str(), "https://example.net/");
2345 /// Cannot change URL’s scheme from `mailto` (cannot-be-a-base) to `https`:
2348 /// use url::Url;
2349 /// # use url::ParseError;
2352 /// let mut url = Url::parse("mailto:rms@example.net")?;
2353 /// let result = url.set_scheme("https");
2354 /// assert_eq!(url.as_str(), "mailto:rms@example.net");
2360 /// Cannot change the URL’s scheme from `foo` to `https`:
2363 /// use url::Url;
2364 /// # use url::ParseError;
2367 /// let mut url = Url::parse("foo://example.net")?;
2368 /// let result = url.set_scheme("https");
2369 /// assert_eq!(url.as_str(), "foo://example.net");
2375 /// Cannot change the URL’s scheme from `http` to `foo`:
2378 /// use url::Url;
2379 /// # use url::ParseError;
2382 /// let mut url = Url::parse("http://example.net")?;
2383 /// let result = url.set_scheme("foo");
2384 /// assert_eq!(url.as_str(), "http://example.net/");
2396 // If url’s scheme is a special scheme and buffer is not a special scheme, then return. in set_scheme()
2398 // If url’s scheme is not a special scheme and buffer is a special scheme, then return. in set_scheme()
2400 … // If url includes credentials or has a non-null port, and buffer is "file", then return. in set_scheme()
2401 // If url’s scheme is "file" and its host is an empty host or null, then return. in set_scheme()
2442 /// Convert a file name as `std::path::Path` into an URL in the `file` scheme.
2453 /// use url::Url;
2456 /// let url = Url::from_file_path("/tmp/foo.txt")?;
2457 /// assert_eq!(url.as_str(), "file:///tmp/foo.txt");
2459 /// let url = Url::from_file_path("../foo.txt");
2460 /// assert!(url.is_err());
2462 /// let url = Url::from_file_path("https://google.com/");
2463 /// assert!(url.is_err());
2471 pub fn from_file_path<P: AsRef<Path>>(path: P) -> Result<Url, ()> { in from_file_path() argument
2475 Ok(Url { in from_file_path()
2489 /// Convert a directory name as `std::path::Path` into an URL in the `file` scheme.
2494 /// Compared to `from_file_path`, this ensure that URL’s the path has a trailing slash
2495 /// so that the entire path is considered when using this URL as a base URL.
2499 /// * `"index.html"` parsed with `Url::from_directory_path(Path::new("/var/www"))`
2500 /// as the base URL is `file:///var/www/index.html`
2501 /// * `"index.html"` parsed with `Url::from_file_path(Path::new("/var/www"))`
2502 /// as the base URL is `file:///var/index.html`, which might not be what was intended.
2508 pub fn from_directory_path<P: AsRef<Path>>(path: P) -> Result<Url, ()> { in from_directory_path() argument
2509 let mut url = Url::from_file_path(path)?; in from_directory_path() localVariable
2510 if !url.serialization.ends_with('/') { in from_directory_path()
2511 url.serialization.push('/') in from_directory_path()
2513 Ok(url) in from_directory_path()
2516 /// Serialize with Serde using the internal representation of the `Url` struct.
2531 let Url { in serialize_internal() localVariable
2558 /// Serialize with Serde using the internal representation of the `Url` struct.
2583 let url = Url { in deserialize_internal() localVariable
2596 url.check_invariants().map_err(|reason| { in deserialize_internal()
2601 Ok(url) in deserialize_internal()
2604 /// Assuming the URL is in the `file` scheme or similar,
2607 /// **Note:** This does not actually check the URL’s `scheme`,
2609 /// It is the user’s responsibility to check the URL’s scheme before calling this.
2612 /// # use url::Url;
2613 /// # let url = Url::parse("file:///etc/passwd").unwrap();
2614 /// let path = url.to_file_path();
2656 /// Parse a string as an URL, without a base URL or encoding override.
2657 impl str::FromStr for Url { implementation
2661 fn from_str(input: &str) -> Result<Url, crate::ParseError> { in from_str() argument
2662 Url::parse(input) in from_str()
2666 impl<'a> TryFrom<&'a str> for Url { implementation
2670 Url::parse(s) in try_from()
2674 /// Display the serialization of this URL.
2675 impl fmt::Display for Url { implementation
2683 impl From<Url> for String {
2684 fn from(value: Url) -> String { in from()
2689 /// Debug the serialization of this URL.
2690 impl fmt::Debug for Url { implementation
2694 .debug_struct("Url") in fmt()
2709 impl Eq for Url {} implementation
2712 impl PartialEq for Url { implementation
2720 impl Ord for Url { implementation
2728 impl PartialOrd for Url { implementation
2736 impl hash::Hash for Url { implementation
2746 /// Return the serialization of this URL.
2747 impl AsRef<str> for Url { implementation
2779 /// Serializes this URL into a `serde` stream.
2783 impl serde::Serialize for Url { implementation
2792 /// Deserializes this URL from a `serde` stream.
2796 impl<'de> serde::Deserialize<'de> for Url { implementation
2797 fn deserialize<D>(deserializer: D) -> Result<Url, D::Error> in deserialize() argument
2806 type Value = Url; in deserialize()
2809 formatter.write_str("a string representing an URL") in deserialize()
2816 Url::parse(s).map_err(|err| { in deserialize()
2851 // An URL’s path must not be empty. in path_to_file_url_segments()
2865 // Build this unconditionally to alleviate https://github.com/servo/rust-url/issues/102
2982 // Build this unconditionally to alleviate https://github.com/servo/rust-url/issues/102
3035 /// Implementation detail of `Url::query_pairs_mut`. Typically not used directly.
3038 url: Option<&'a mut Url>, field
3042 // `as_mut_string` string here exposes the internal serialization of an `Url`,
3049 // `Url::query_pairs_mut` which is `Serializer<UrlQuery>`
3054 &mut self.url.as_mut().unwrap().serialization in as_mut_string()
3057 fn finish(mut self) -> &'a mut Url { in finish() argument
3058 let url = self.url.take().unwrap(); in finish() localVariable
3059 url.restore_already_parsed_fragment(self.fragment.take()); in finish()
3060 url in finish()
3063 type Finished = &'a mut Url;
3068 if let Some(url) = self.url.take() { in drop()
3069 url.restore_already_parsed_fragment(self.fragment.take()) in drop()