From 1d3e0dc281638bc60f88ca8a7fa5ff7d786a05b1 Mon Sep 17 00:00:00 2001 From: Corey Farwell Date: Tue, 3 Jan 2017 15:58:35 -0800 Subject: [PATCH 1/5] Add doc examples for `url::Url::from_file_path`. --- src/lib.rs | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/src/lib.rs b/src/lib.rs index e052b8f5..0b11c3ae 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1319,6 +1319,25 @@ impl Url { /// /// This returns `Err` if the given path is not absolute or, /// on Windows, if the prefix is not a disk prefix (e.g. `C:`). + /// + /// # Examples + /// + /// On Unix-like platforms: + /// + /// ``` + /// # if cfg!(unix) { + /// use url::Url; + /// + /// let url = Url::from_file_path("/tmp/foo.txt").unwrap(); + /// 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()); + /// # } + /// ``` pub fn from_file_path>(path: P) -> Result { let mut serialization = "file://".to_owned(); let path_start = serialization.len() as u32; From 5dd6bf5b64f73ffea657412308d22a0ddfebcc1e Mon Sep 17 00:00:00 2001 From: Corey Farwell Date: Tue, 3 Jan 2017 16:12:15 -0800 Subject: [PATCH 2/5] Add doc examples for `url::Url::set_scheme`. --- src/lib.rs | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/src/lib.rs b/src/lib.rs index 0b11c3ae..e6fa99a8 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1288,6 +1288,42 @@ impl Url { /// * The new scheme is not in `[a-zA-Z][a-zA-Z0-9+.-]+` /// * This URL is cannot-be-a-base and the new scheme is one of /// `http`, `https`, `ws`, `wss`, `ftp`, or `gopher` + /// + /// # Examples + /// + /// Change the URL’s scheme from `https` to `foo`: + /// + /// ``` + /// use url::Url; + /// + /// let mut url = Url::parse("https://example.net").unwrap(); + /// let result = url.set_scheme("foo"); + /// assert_eq!(url.as_str(), "foo://example.net/"); + /// assert!(result.is_ok()); + /// ``` + /// + /// + /// Cannot change URL’s scheme from `https` to `foõ`: + /// + /// ``` + /// use url::Url; + /// + /// let mut url = Url::parse("https://example.net").unwrap(); + /// let result = url.set_scheme("foõ"); + /// assert_eq!(url.as_str(), "https://example.net/"); + /// assert!(result.is_err()); + /// ``` + /// + /// Cannot change URL’s scheme from `mailto` (cannot-be-a-base) to `https`: + /// + /// ``` + /// use url::Url; + /// + /// let mut url = Url::parse("mailto:rms@example.net").unwrap(); + /// let result = url.set_scheme("https"); + /// assert_eq!(url.as_str(), "mailto:rms@example.net"); + /// assert!(result.is_err()); + /// ``` pub fn set_scheme(&mut self, scheme: &str) -> Result<(), ()> { let mut parser = Parser::for_setter(String::new()); let remaining = try!(parser.parse_scheme(parser::Input::new(scheme))); From 312495c1f43eab7124997dcec91383d0a9d2a7b6 Mon Sep 17 00:00:00 2001 From: Corey Farwell Date: Tue, 3 Jan 2017 16:20:09 -0800 Subject: [PATCH 3/5] Add interesting case for `url::Url::domain` doc examples. --- src/lib.rs | 3 +++ 1 file changed, 3 insertions(+) diff --git a/src/lib.rs b/src/lib.rs index e6fa99a8..7fb1ed1e 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -694,6 +694,9 @@ impl Url { /// let url = Url::parse("https://127.0.0.1/").unwrap(); /// assert_eq!(url.domain(), None); /// + /// let url = Url::parse("mailto:rms@example.net").unwrap(); + /// assert_eq!(url.domain(), None); + /// /// let url = Url::parse("https://example.com/").unwrap(); /// assert_eq!(url.domain(), Some("example.com")); /// ``` From 752d216824de14d9889c16eba965e625fe37d387 Mon Sep 17 00:00:00 2001 From: Corey Farwell Date: Tue, 3 Jan 2017 16:25:12 -0800 Subject: [PATCH 4/5] Add interesting case for `url::Url::set_port` doc examples. --- src/lib.rs | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/src/lib.rs b/src/lib.rs index 7fb1ed1e..7e8671a8 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1057,6 +1057,20 @@ impl Url { /// url.set_port(None).unwrap(); /// assert_eq!(url.as_str(), "ssh://example.net/"); /// ``` + /// + /// Cannot set port for cannot-be-a-base URLs: + /// + /// ``` + /// use url::Url; + /// + /// let mut url = Url::parse("mailto:rms@example.net").unwrap(); + /// + /// let result = url.set_port(Some(80)); + /// assert!(result.is_err()); + /// + /// let result = url.set_port(None); + /// assert!(result.is_err()); + /// ``` pub fn set_port(&mut self, mut port: Option) -> Result<(), ()> { if !self.has_host() || self.scheme() == "file" { return Err(()) From c4113d191a7e3ea23ed72cf631ead639421ee728 Mon Sep 17 00:00:00 2001 From: Corey Farwell Date: Tue, 3 Jan 2017 16:56:07 -0800 Subject: [PATCH 5/5] Add doc examples for `url::Url::set_host`. --- src/lib.rs | 51 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) diff --git a/src/lib.rs b/src/lib.rs index 7e8671a8..2c3b0a9b 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1119,6 +1119,57 @@ impl Url { /// /// Removing the host (calling this with `None`) /// will also remove any username, password, and port number. + /// + /// # Examples + /// + /// Change host: + /// + /// ``` + /// use url::Url; + /// + /// let mut url = Url::parse("https://example.net").unwrap(); + /// let result = url.set_host(Some("rust-lang.org")); + /// assert!(result.is_ok()); + /// assert_eq!(url.as_str(), "https://rust-lang.org/"); + /// ``` + /// + /// Remove host: + /// + /// ``` + /// use url::Url; + /// + /// let mut url = Url::parse("foo://example.net").unwrap(); + /// let result = url.set_host(None); + /// assert!(result.is_ok()); + /// assert_eq!(url.as_str(), "foo:/"); + /// ``` + /// + /// Cannot remove host for 'special' schemes (e.g. `http`): + /// + /// ``` + /// use url::Url; + /// + /// let mut url = Url::parse("https://example.net").unwrap(); + /// let result = url.set_host(None); + /// assert!(result.is_err()); + /// assert_eq!(url.as_str(), "https://example.net/"); + /// ``` + /// + /// Cannot change or remove host for cannot-be-a-base URLs: + /// + /// ``` + /// use url::Url; + /// + /// let mut url = Url::parse("mailto:rms@example.net").unwrap(); + /// + /// 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"); + /// ``` pub fn set_host(&mut self, host: Option<&str>) -> Result<(), ParseError> { if self.cannot_be_a_base() { return Err(ParseError::SetHostOnCannotBeABaseUrl)