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 #![doc(html_root_url = "https://docs.rs/url/2.3.1")]
128 debugger_visualizer(natvis_file = "../../debug_metadata/url.natvis")
168 /// A parsed URL record.
170 pub struct Url { struct
173 /// url = scheme ":" [ hierarchical | non-hierarchical ] [ "?" query ]? [ "#" fragment ]?
194 /// Full configuration for the URL parser.
197 base_url: Option<&'a Url>, argument
203 /// Change the base URL
204 pub fn base_url(mut self, new: Option<&'a Url>) -> Self { in base_url()
224 /// use url::{Url, SyntaxViolation};
225 /// # use url::ParseError;
226 /// # fn run() -> Result<(), url::ParseError> {
228 /// let url = Url::options()
231 /// assert_eq!(url.as_str(), "https://example.com/");
243 /// Parse an URL string with the configuration so far.
244 pub fn parse(self, input: &str) -> Result<Url, crate::ParseError> { in parse() argument
256 impl Url { implementation
257 /// Parse an absolute URL from a string.
262 /// use url::Url;
263 /// # use url::ParseError;
266 /// let url = Url::parse("https://example.net")?;
274 /// If the function can not parse an absolute URL from the given string,
279 pub fn parse(input: &str) -> Result<Url, crate::ParseError> { in parse() argument
280 Url::options().parse(input) in parse()
283 /// Parse an absolute URL from a string and add params to its query string.
290 /// use url::Url;
291 /// # use url::ParseError;
294 /// let url = Url::parse_with_params("https://example.net?dont=clobberme",
296 /// assert_eq!("https://example.net/?dont=clobberme&lang=rust&browser=servo", url.as_str());
304 /// If the function can not parse an absolute URL from the given string,
309 pub fn parse_with_params<I, K, V>(input: &str, iter: I) -> Result<Url, crate::ParseError> in parse_with_params() argument
316 let mut url = Url::options().parse(input); in parse_with_params() localVariable
318 if let Ok(ref mut url) = url { in parse_with_params()
319 url.query_pairs_mut().extend_pairs(iter); in parse_with_params()
322 url in parse_with_params()
325 /// Parse a string as an URL, with this URL as the base URL.
336 /// use url::Url;
337 /// # use url::ParseError;
340 /// let base = Url::parse("https://example.net/a/b.html")?;
341 /// let url = base.join("c.png")?;
342 /// assert_eq!(url.as_str(), "https://example.net/a/c.png"); // Not /a/b.html/c.png
344 /// let base = Url::parse("https://example.net/a/b/")?;
345 /// let url = base.join("c.png")?;
346 /// assert_eq!(url.as_str(), "https://example.net/a/b/c.png");
354 /// If the function can not parse an URL from the given string
355 /// with this URL as the base URL, a [`ParseError`] variant will be returned.
360 pub fn join(&self, input: &str) -> Result<Url, crate::ParseError> { in join() argument
361 Url::options().base_url(Some(self)).parse(input) in join()
364 /// Creates a relative URL if possible, with this URL as the base URL.
371 /// use url::Url;
372 /// # use url::ParseError;
375 /// let base = Url::parse("https://example.net/a/b.html")?;
376 /// let url = Url::parse("https://example.net/a/c.png")?;
377 /// let relative = base.make_relative(&url);
380 /// let base = Url::parse("https://example.net/a/b/")?;
381 /// let url = Url::parse("https://example.net/a/b/c.png")?;
382 /// let relative = base.make_relative(&url);
385 /// let base = Url::parse("https://example.net/a/b/")?;
386 /// let url = Url::parse("https://example.net/a/d/c.png")?;
387 /// let relative = base.make_relative(&url);
390 /// let base = Url::parse("https://example.net/a/b.html?c=d")?;
391 /// let url = Url::parse("https://example.net/a/b.html?e=f")?;
392 /// let relative = base.make_relative(&url);
401 /// If this URL can't be a base for the given URL, `None` is returned.
405 pub fn make_relative(&self, url: &Url) -> Option<String> { in make_relative()
411 if self.scheme() != url.scheme() || self.host() != url.host() || self.port() != url.port() { in make_relative()
432 let (url_path, url_filename) = extract_path_filename(url.path()); in make_relative()
483 if let Some(query) = url.query() { in make_relative()
488 if let Some(fragment) = url.fragment() { in make_relative()
496 /// Return a default `ParseOptions` that can fully configure the URL parser.
500 /// Get default `ParseOptions`, then change base url
503 /// use url::Url;
504 /// # use url::ParseError;
506 /// let options = Url::options();
507 /// let api = Url::parse("https://api.example.com")?;
523 /// Return the serialization of this URL.
525 /// This is fast since that serialization is already stored in the `Url` struct.
530 /// use url::Url;
531 /// # use url::ParseError;
535 /// let url = Url::parse(url_str)?;
536 /// assert_eq!(url.as_str(), url_str);
546 /// Return the serialization of this URL.
548 /// This consumes the `Url` and takes ownership of the `String` stored in it.
553 /// use url::Url;
554 /// # use url::ParseError;
558 /// let url = Url::parse(url_str)?;
559 /// assert_eq!(String::from(url), url_str);
572 /// Methods of the `Url` struct assume a number of invariants.
574 /// This is for testing rust-url itself.
581 "!( {} ) for URL {:?}", in check_invariants()
595 return Err(format!("{:?} != {:?} ({} != {}) for URL {:?}", in check_invariants()
612 // URL with authority in check_invariants()
654 // Anarchist URL (no authority) in check_invariants()
674 let other = Url::parse(self.as_str()).expect("Failed to parse myself?"); in check_invariants()
683 // See https://github.com/whatwg/url/issues/79 in check_invariants()
693 /// Return the origin of this URL (<https://url.spec.whatwg.org/#origin>)
696 /// `url.origin() != url.origin()`.
700 /// URL with `ftp` scheme:
703 /// use url::{Host, Origin, Url};
704 /// # use url::ParseError;
707 /// let url = Url::parse("ftp://example.com/foo")?;
708 /// assert_eq!(url.origin(),
717 /// URL with `blob` scheme:
720 /// use url::{Host, Origin, Url};
721 /// # use url::ParseError;
724 /// let url = Url::parse("blob:https://example.com/foo")?;
725 /// assert_eq!(url.origin(),
734 /// URL with `file` scheme:
737 /// use url::{Host, Origin, Url};
738 /// # use url::ParseError;
741 /// let url = Url::parse("file:///tmp/foo")?;
742 /// assert!(!url.origin().is_tuple());
744 /// let other_url = Url::parse("file:///tmp/foo")?;
745 /// assert!(url.origin() != other_url.origin());
751 /// URL with other scheme:
754 /// use url::{Host, Origin, Url};
755 /// # use url::ParseError;
758 /// let url = Url::parse("foo:bar")?;
759 /// assert!(!url.origin().is_tuple());
769 /// Return the scheme of this URL, lower-cased, as an ASCII string without the ':' delimiter.
774 /// use url::Url;
775 /// # use url::ParseError;
778 /// let url = Url::parse("file:///tmp/foo")?;
779 /// assert_eq!(url.scheme(), "file");
789 /// Return whether the URL has an 'authority',
798 /// use url::Url;
799 /// # use url::ParseError;
802 /// let url = Url::parse("ftp://rms@example.com")?;
803 /// assert!(url.has_authority());
805 /// let url = Url::parse("unix:/run/foo.socket")?;
806 /// assert!(!url.has_authority());
808 /// let url = Url::parse("data:text/plain,Stuff")?;
809 /// assert!(!url.has_authority());
820 /// Return whether this URL is a cannot-be-a-base URL,
821 /// meaning that parsing a relative URL string with this URL as the base will return an error.
829 /// use url::Url;
830 /// # use url::ParseError;
833 /// let url = Url::parse("ftp://rms@example.com")?;
834 /// assert!(!url.cannot_be_a_base());
836 /// let url = Url::parse("unix:/run/foo.socket")?;
837 /// assert!(!url.cannot_be_a_base());
839 /// let url = Url::parse("data:text/plain,Stuff")?;
840 /// assert!(url.cannot_be_a_base());
850 /// Return the username for this URL (typically the empty string)
856 /// use url::Url;
857 /// # use url::ParseError;
860 /// let url = Url::parse("ftp://rms@example.com")?;
861 /// assert_eq!(url.username(), "rms");
863 /// let url = Url::parse("ftp://:secret123@example.com")?;
864 /// assert_eq!(url.username(), "");
866 /// let url = Url::parse("https://example.com")?;
867 /// assert_eq!(url.username(), "");
881 /// Return the password for this URL, if any, as a percent-encoded ASCII string.
886 /// use url::Url;
887 /// # use url::ParseError;
890 /// let url = Url::parse("ftp://rms:secret123@example.com")?;
891 /// assert_eq!(url.password(), Some("secret123"));
893 /// let url = Url::parse("ftp://:secret123@example.com")?;
894 /// assert_eq!(url.password(), Some("secret123"));
896 /// let url = Url::parse("ftp://rms@example.com")?;
897 /// assert_eq!(url.password(), None);
899 /// let url = Url::parse("https://example.com")?;
900 /// assert_eq!(url.password(), None);
919 /// Equivalent to `url.host().is_some()`.
924 /// use url::Url;
925 /// # use url::ParseError;
928 /// let url = Url::parse("ftp://rms@example.com")?;
929 /// assert!(url.has_host());
931 /// let url = Url::parse("unix:/run/foo.socket")?;
932 /// assert!(!url.has_host());
934 /// let url = Url::parse("data:text/plain,Stuff")?;
935 /// assert!(!url.has_host());
944 /// Return the string representation of the host (domain or IP address) for this URL, if any.
947 /// of a special URL, or percent encoded for non-special URLs.
958 /// use url::Url;
959 /// # use url::ParseError;
962 /// let url = Url::parse("https://127.0.0.1/index.html")?;
963 /// assert_eq!(url.host_str(), Some("127.0.0.1"));
965 /// let url = Url::parse("ftp://rms@example.com")?;
966 /// assert_eq!(url.host_str(), Some("example.com"));
968 /// let url = Url::parse("unix:/run/foo.socket")?;
969 /// assert_eq!(url.host_str(), None);
971 /// let url = Url::parse("data:text/plain,Stuff")?;
972 /// assert_eq!(url.host_str(), None);
985 /// Return the parsed representation of the host for this URL.
987 /// of a special URL, or percent encoded for non-special URLs.
997 /// use url::Url;
998 /// # use url::ParseError;
1001 /// let url = Url::parse("https://127.0.0.1/index.html")?;
1002 /// assert!(url.host().is_some());
1004 /// let url = Url::parse("ftp://rms@example.com")?;
1005 /// assert!(url.host().is_some());
1007 /// let url = Url::parse("unix:/run/foo.socket")?;
1008 /// assert!(url.host().is_none());
1010 /// let url = Url::parse("data:text/plain,Stuff")?;
1011 /// assert!(url.host().is_none());
1025 /// If this URL has a host and it is a domain name (not an IP address), return it.
1027 /// of a special URL, or percent encoded for non-special URLs.
1032 /// use url::Url;
1033 /// # use url::ParseError;
1036 /// let url = Url::parse("https://127.0.0.1/")?;
1037 /// assert_eq!(url.domain(), None);
1039 /// let url = Url::parse("mailto:rms@example.net")?;
1040 /// assert_eq!(url.domain(), None);
1042 /// let url = Url::parse("https://example.com/")?;
1043 /// assert_eq!(url.domain(), Some("example.com"));
1055 /// Return the port number for this URL, if any.
1063 /// use url::Url;
1064 /// # use url::ParseError;
1067 /// let url = Url::parse("https://example.com")?;
1068 /// assert_eq!(url.port(), None);
1070 /// let url = Url::parse("https://example.com:443/")?;
1071 /// assert_eq!(url.port(), None);
1073 /// let url = Url::parse("ssh://example.com:22")?;
1074 /// assert_eq!(url.port(), Some(22));
1084 /// Return the port number for this URL, or the default port number if it is known.
1090 /// For other schemes, it is the same as `Url::port()`.
1095 /// use url::Url;
1096 /// # use url::ParseError;
1099 /// let url = Url::parse("foo://example.com")?;
1100 /// assert_eq!(url.port_or_known_default(), None);
1102 /// let url = Url::parse("foo://example.com:1456")?;
1103 /// assert_eq!(url.port_or_known_default(), Some(1456));
1105 /// let url = Url::parse("https://example.com")?;
1106 /// assert_eq!(url.port_or_known_default(), Some(443));
1116 /// Resolve a URL’s host and port number to `SocketAddr`.
1118 /// If the URL has the default port number of a scheme that is unknown to this library,
1121 /// or by matching on the URL’s `.scheme()`.
1128 /// let url = url::Url::parse("https://example.net/").unwrap();
1129 /// let addrs = url.socket_addrs(|| None).unwrap();
1136 /// fn socket_addrs(url: url::Url) -> std::io::Result<Vec<std::net::SocketAddr>> {
1137 /// url.socket_addrs(|| match url.scheme() {
1159 let host = io_result(self.host(), "No host name in the URL")?; in socket_addrs()
1162 "No port number in the URL", in socket_addrs()
1171 /// Return the path for this URL, as a percent-encoded ASCII string.
1179 /// use url::{Url, ParseError};
1182 /// let url = Url::parse("https://example.com/api/versions?page=2")?;
1183 /// assert_eq!(url.path(), "/api/versions");
1185 /// let url = Url::parse("https://example.com")?;
1186 /// assert_eq!(url.path(), "/");
1188 /// let url = Url::parse("https://example.com/countries/việt nam")?;
1189 /// assert_eq!(url.path(), "/countries/vi%E1%BB%87t%20nam");
1203 /// Unless this URL is cannot-be-a-base,
1215 /// use url::Url;
1219 /// let url = Url::parse("https://example.com/foo/bar")?;
1220 /// let mut path_segments = url.path_segments().ok_or_else(|| "cannot be base")?;
1225 /// let url = Url::parse("https://example.com")?;
1226 /// let mut path_segments = url.path_segments().ok_or_else(|| "cannot be base")?;
1230 /// let url = Url::parse("data:text/plain,HelloWorld")?;
1231 /// assert!(url.path_segments().is_none());
1233 /// let url = Url::parse("https://example.com/countries/việt nam")?;
1234 /// let mut path_segments = url.path_segments().ok_or_else(|| "cannot be base")?;
1246 /// Return this URL’s query string, if any, as a percent-encoded ASCII string.
1251 /// use url::Url;
1252 /// # use url::ParseError;
1255 /// let url = Url::parse("https://example.com/products?page=2")?;
1256 /// let query = url.query();
1259 /// let url = Url::parse("https://example.com/products")?;
1260 /// let query = url.query();
1263 /// let url = Url::parse("https://example.com/?country=español")?;
1264 /// let query = url.query();
1284 /// Parse the URL’s query string, if any, as `application/x-www-form-urlencoded`
1292 /// use url::Url;
1293 /// # use url::ParseError;
1296 /// let url = Url::parse("https://example.com/products?page=2&sort=desc")?;
1297 /// let mut pairs = url.query_pairs();
1313 /// Return this URL’s fragment identifier, if any.
1315 /// A fragment is the part of the URL after the `#` symbol.
1322 /// of a URL to the server.
1330 /// use url::Url;
1331 /// # use url::ParseError;
1334 /// let url = Url::parse("https://example.com/data.csv#row=4")?;
1336 /// assert_eq!(url.fragment(), Some("row=4"));
1338 /// let url = Url::parse("https://example.com/data.csv#cell=4,1-6,2")?;
1340 /// assert_eq!(url.fragment(), Some("cell=4,1-6,2"));
1359 /// Change this URL’s fragment identifier.
1364 /// use url::Url;
1365 /// # use url::ParseError;
1368 /// let mut url = Url::parse("https://example.com/data.csv")?;
1369 /// assert_eq!(url.as_str(), "https://example.com/data.csv");
1371 /// url.set_fragment(Some("cell=4,1-6,2"));
1372 /// assert_eq!(url.as_str(), "https://example.com/data.csv#cell=4,1-6,2");
1373 /// assert_eq!(url.fragment(), Some("cell=4,1-6,2"));
1375 /// url.set_fragment(None);
1376 /// assert_eq!(url.as_str(), "https://example.com/data.csv");
1377 /// assert!(url.fragment().is_none());
1416 /// Change this URL’s query string.
1421 /// use url::Url;
1422 /// # use url::ParseError;
1425 /// let mut url = Url::parse("https://example.com/products")?;
1426 /// assert_eq!(url.as_str(), "https://example.com/products");
1428 /// url.set_query(Some("page=2"));
1429 /// assert_eq!(url.as_str(), "https://example.com/products?page=2");
1430 /// assert_eq!(url.query(), Some("page=2"));
1462 /// Manipulate this URL’s query string, viewed as a sequence of name/value pairs
1468 /// # use url::{Url, ParseError};
1471 /// let mut url = Url::parse("https://example.net?lang=fr#nav")?;
1472 /// assert_eq!(url.query(), Some("lang=fr"));
1474 /// url.query_pairs_mut().append_pair("foo", "bar");
1475 /// assert_eq!(url.query(), Some("lang=fr&foo=bar"));
1476 /// assert_eq!(url.as_str(), "https://example.net/?lang=fr&foo=bar#nav");
1478 /// url.query_pairs_mut()
1482 /// assert_eq!(url.query(), Some("foo=bar+%26+baz&saisons=%C3%89t%C3%A9%2Bhiver"));
1483 /// assert_eq!(url.as_str(),
1490 /// Note: `url.query_pairs_mut().clear();` is equivalent to `url.set_query(Some(""))`,
1491 /// not `url.set_query(None)`.
1493 /// The state of `Url` is unspecified if this return value is leaked without being dropped.
1508 url: Some(self), in query_pairs_mut()
1525 /// Change this URL’s path.
1530 /// use url::Url;
1531 /// # use url::ParseError;
1534 /// let mut url = Url::parse("https://example.com")?;
1535 /// url.set_path("api/comments");
1536 /// assert_eq!(url.as_str(), "https://example.com/api/comments");
1537 /// assert_eq!(url.path(), "/api/comments");
1539 /// let mut url = Url::parse("https://example.com/api")?;
1540 /// url.set_path("data/report.csv");
1541 /// assert_eq!(url.as_str(), "https://example.com/data/report.csv");
1542 /// assert_eq!(url.path(), "/data/report.csv");
1545 /// let mut url = Url::parse("https://example.com")?;
1546 /// url.set_path("api/some comments");
1547 /// assert_eq!(url.as_str(), "https://example.com/api/some%20comments");
1548 /// assert_eq!(url.path(), "/api/some%20comments");
1551 /// let mut url = Url::parse("https://example.com")?;
1552 /// url.set_path("api/some%20comments");
1553 /// assert_eq!(url.as_str(), "https://example.com/api/some%20comments");
1554 /// assert_eq!(url.path(), "/api/some%20comments");
1581 /// Return an object with methods to manipulate this URL’s path segments.
1583 /// Return `Err(())` if this URL is cannot-be-a-base.
1608 /// Change this URL’s port number.
1612 /// If this URL is cannot-be-a-base, does not have a host, or has the `file` scheme;
1618 /// use url::Url;
1622 /// let mut url = Url::parse("ssh://example.net:2048/")?;
1624 /// url.set_port(Some(4096)).map_err(|_| "cannot be base")?;
1625 /// assert_eq!(url.as_str(), "ssh://example.net:4096/");
1627 /// url.set_port(None).map_err(|_| "cannot be base")?;
1628 /// assert_eq!(url.as_str(), "ssh://example.net/");
1637 /// use url::Url;
1641 /// let mut url = Url::parse("https://example.org/")?;
1643 /// url.set_port(Some(443)).map_err(|_| "cannot be base")?;
1644 /// assert!(url.port().is_none());
1653 /// use url::Url;
1654 /// # use url::ParseError;
1657 /// let mut url = Url::parse("mailto:rms@example.net")?;
1659 /// let result = url.set_port(Some(80));
1662 /// let result = url.set_port(None);
1720 /// Change this URL’s host.
1730 /// use url::Url;
1731 /// # use url::ParseError;
1734 /// let mut url = Url::parse("https://example.net")?;
1735 /// let result = url.set_host(Some("rust-lang.org"));
1737 /// assert_eq!(url.as_str(), "https://rust-lang.org/");
1746 /// use url::Url;
1747 /// # use url::ParseError;
1750 /// let mut url = Url::parse("foo://example.net")?;
1751 /// let result = url.set_host(None);
1753 /// assert_eq!(url.as_str(), "foo:/");
1762 /// use url::Url;
1763 /// # use url::ParseError;
1766 /// let mut url = Url::parse("https://example.net")?;
1767 /// let result = url.set_host(None);
1769 /// assert_eq!(url.as_str(), "https://example.net/");
1778 /// use url::Url;
1779 /// # use url::ParseError;
1782 /// let mut url = Url::parse("mailto:rms@example.net")?;
1784 /// let result = url.set_host(Some("rust-lang.org"));
1786 /// assert_eq!(url.as_str(), "mailto:rms@example.net");
1788 /// let result = url.set_host(None);
1790 /// assert_eq!(url.as_str(), "mailto:rms@example.net");
1798 /// If this URL is cannot-be-a-base or there is an error parsing the given `host`,
1909 /// Change this URL’s host to the given IP address.
1911 /// If this URL is cannot-be-a-base, do nothing and return `Err`.
1913 /// Compared to `Url::set_host`, this skips the host parser.
1918 /// use url::{Url, ParseError};
1921 /// let mut url = Url::parse("http://example.com")?;
1922 /// url.set_ip_host("127.0.0.1".parse().unwrap());
1923 /// assert_eq!(url.host_str(), Some("127.0.0.1"));
1924 /// assert_eq!(url.as_str(), "http://127.0.0.1/");
1930 /// Cannot change URL's from mailto(cannot-be-base) to ip:
1933 /// use url::{Url, ParseError};
1936 /// let mut url = Url::parse("mailto:rms@example.com")?;
1937 /// let result = url.set_ip_host("127.0.0.1".parse().unwrap());
1939 /// assert_eq!(url.as_str(), "mailto:rms@example.com");
1960 /// Change this URL’s password.
1962 /// If this URL is cannot-be-a-base or does not have a host, do nothing and return `Err`.
1967 /// use url::{Url, ParseError};
1970 /// let mut url = Url::parse("mailto:rmz@example.com")?;
1971 /// let result = url.set_password(Some("secret_password"));
1974 /// let mut url = Url::parse("ftp://user1:secret1@example.com")?;
1975 /// let result = url.set_password(Some("secret_password"));
1976 /// assert_eq!(url.password(), Some("secret_password"));
1978 /// let mut url = Url::parse("ftp://user2:@example.com")?;
1979 /// let result = url.set_password(Some("secret2"));
1981 /// assert_eq!(url.password(), Some("secret2"));
2044 /// Change this URL’s username.
2046 /// If this URL is cannot-be-a-base or does not have a host, do nothing and return `Err`.
2052 /// use url::{Url, ParseError};
2055 /// let mut url = Url::parse("mailto:rmz@example.com")?;
2056 /// let result = url.set_username("user1");
2057 /// assert_eq!(url.as_str(), "mailto:rmz@example.com");
2067 /// use url::{Url, ParseError};
2070 /// let mut url = Url::parse("ftp://:secre1@example.com/")?;
2071 /// let result = url.set_username("user1");
2073 /// assert_eq!(url.username(), "user1");
2074 /// assert_eq!(url.as_str(), "ftp://user1:secre1@example.com/");
2131 /// Change this URL’s scheme.
2136 /// * If this URL is cannot-be-a-base and the new scheme is one of
2140 /// * If the new scheme is `file` and this URL includes credentials
2142 /// * If this URL's scheme is `file` and its host is empty or null
2144 /// See also [the URL specification's section on legal scheme state
2145 /// overrides](https://url.spec.whatwg.org/#scheme-state).
2149 /// Change the URL’s scheme from `https` to `http`:
2152 /// use url::Url;
2153 /// # use url::ParseError;
2156 /// let mut url = Url::parse("https://example.net")?;
2157 /// let result = url.set_scheme("http");
2158 /// assert_eq!(url.as_str(), "http://example.net/");
2164 /// Change the URL’s scheme from `foo` to `bar`:
2167 /// use url::Url;
2168 /// # use url::ParseError;
2171 /// let mut url = Url::parse("foo://example.net")?;
2172 /// let result = url.set_scheme("bar");
2173 /// assert_eq!(url.as_str(), "bar://example.net");
2180 /// Cannot change URL’s scheme from `https` to `foõ`:
2183 /// use url::Url;
2184 /// # use url::ParseError;
2187 /// let mut url = Url::parse("https://example.net")?;
2188 /// let result = url.set_scheme("foõ");
2189 /// assert_eq!(url.as_str(), "https://example.net/");
2196 /// Cannot change URL’s scheme from `mailto` (cannot-be-a-base) to `https`:
2199 /// use url::Url;
2200 /// # use url::ParseError;
2203 /// let mut url = Url::parse("mailto:rms@example.net")?;
2204 /// let result = url.set_scheme("https");
2205 /// assert_eq!(url.as_str(), "mailto:rms@example.net");
2211 /// Cannot change the URL’s scheme from `foo` to `https`:
2214 /// use url::Url;
2215 /// # use url::ParseError;
2218 /// let mut url = Url::parse("foo://example.net")?;
2219 /// let result = url.set_scheme("https");
2220 /// assert_eq!(url.as_str(), "foo://example.net");
2226 /// Cannot change the URL’s scheme from `http` to `foo`:
2229 /// use url::Url;
2230 /// # use url::ParseError;
2233 /// let mut url = Url::parse("http://example.net")?;
2234 /// let result = url.set_scheme("foo");
2235 /// assert_eq!(url.as_str(), "http://example.net/");
2247 // If url’s scheme is a special scheme and buffer is not a special scheme, then return. in set_scheme()
2249 // If url’s scheme is not a special scheme and buffer is a special scheme, then return. in set_scheme()
2251 … // If url includes credentials or has a non-null port, and buffer is "file", then return. in set_scheme()
2252 // If url’s scheme is "file" and its host is an empty host or null, then return. in set_scheme()
2293 /// Convert a file name as `std::path::Path` into an URL in the `file` scheme.
2304 /// use url::Url;
2307 /// let url = Url::from_file_path("/tmp/foo.txt")?;
2308 /// assert_eq!(url.as_str(), "file:///tmp/foo.txt");
2310 /// let url = Url::from_file_path("../foo.txt");
2311 /// assert!(url.is_err());
2313 /// let url = Url::from_file_path("https://google.com/");
2314 /// assert!(url.is_err());
2322 pub fn from_file_path<P: AsRef<Path>>(path: P) -> Result<Url, ()> { in from_file_path() argument
2326 Ok(Url { in from_file_path()
2340 /// Convert a directory name as `std::path::Path` into an URL in the `file` scheme.
2345 /// Compared to `from_file_path`, this ensure that URL’s the path has a trailing slash
2346 /// so that the entire path is considered when using this URL as a base URL.
2350 /// * `"index.html"` parsed with `Url::from_directory_path(Path::new("/var/www"))`
2351 /// as the base URL is `file:///var/www/index.html`
2352 /// * `"index.html"` parsed with `Url::from_file_path(Path::new("/var/www"))`
2353 /// as the base URL is `file:///var/index.html`, which might not be what was intended.
2359 pub fn from_directory_path<P: AsRef<Path>>(path: P) -> Result<Url, ()> { in from_directory_path() argument
2360 let mut url = Url::from_file_path(path)?; in from_directory_path() localVariable
2361 if !url.serialization.ends_with('/') { in from_directory_path()
2362 url.serialization.push('/') in from_directory_path()
2364 Ok(url) in from_directory_path()
2367 /// Serialize with Serde using the internal representation of the `Url` struct.
2382 let Url { in serialize_internal() localVariable
2409 /// Serialize with Serde using the internal representation of the `Url` struct.
2434 let url = Url { in deserialize_internal() localVariable
2447 url.check_invariants().map_err(|reason| { in deserialize_internal()
2452 Ok(url) in deserialize_internal()
2455 /// Assuming the URL is in the `file` scheme or similar,
2458 /// **Note:** This does not actually check the URL’s `scheme`,
2460 /// It is the user’s responsibility to check the URL’s scheme before calling this.
2463 /// # use url::Url;
2464 /// # let url = Url::parse("file:///etc/passwd").unwrap();
2465 /// let path = url.to_file_path();
2507 /// Parse a string as an URL, without a base URL or encoding override.
2508 impl str::FromStr for Url { implementation
2512 fn from_str(input: &str) -> Result<Url, crate::ParseError> { in from_str() argument
2513 Url::parse(input) in from_str()
2517 impl<'a> TryFrom<&'a str> for Url { implementation
2521 Url::parse(s) in try_from()
2525 /// Display the serialization of this URL.
2526 impl fmt::Display for Url { implementation
2534 impl From<Url> for String {
2535 fn from(value: Url) -> String { in from()
2540 /// Debug the serialization of this URL.
2541 impl fmt::Debug for Url { implementation
2545 .debug_struct("Url") in fmt()
2560 impl Eq for Url {} implementation
2563 impl PartialEq for Url { implementation
2571 impl Ord for Url { implementation
2579 impl PartialOrd for Url { implementation
2587 impl hash::Hash for Url { implementation
2597 /// Return the serialization of this URL.
2598 impl AsRef<str> for Url { implementation
2630 /// Serializes this URL into a `serde` stream.
2634 impl serde::Serialize for Url { implementation
2643 /// Deserializes this URL from a `serde` stream.
2647 impl<'de> serde::Deserialize<'de> for Url { implementation
2648 fn deserialize<D>(deserializer: D) -> Result<Url, D::Error> in deserialize() argument
2657 type Value = Url; in deserialize()
2660 formatter.write_str("a string representing an URL") in deserialize()
2667 Url::parse(s).map_err(|err| { in deserialize()
2702 // An URL’s path must not be empty. in path_to_file_url_segments()
2716 // Build this unconditionally to alleviate https://github.com/servo/rust-url/issues/102
2833 // Build this unconditionally to alleviate https://github.com/servo/rust-url/issues/102
2886 /// Implementation detail of `Url::query_pairs_mut`. Typically not used directly.
2889 url: Option<&'a mut Url>, field
2893 // `as_mut_string` string here exposes the internal serialization of an `Url`,
2900 // `Url::query_pairs_mut` which is `Serializer<UrlQuery>`
2905 &mut self.url.as_mut().unwrap().serialization in as_mut_string()
2908 fn finish(mut self) -> &'a mut Url { in finish() argument
2909 let url = self.url.take().unwrap(); in finish() localVariable
2910 url.restore_already_parsed_fragment(self.fragment.take()); in finish()
2911 url in finish()
2914 type Finished = &'a mut Url;
2919 if let Some(url) = self.url.take() { in drop()
2920 url.restore_already_parsed_fragment(self.fragment.take()) in drop()