Auto merge of #271 - kybishop:parse-with-params, r=SimonSapin

add Url::parse_with_params()

Allows us to build a `Url` from user-supplied params without the boilerplate of constructing then modifying the `Url`.

This is in hopes of improving the ergenomics of the reqwest library: https://github.com/seanmonstar/reqwest/pull/45#issuecomment-272589321

<!-- Reviewable:start -->
---
This change is [<img src="https://reviewable.io/review_button.svg" height="34" align="absmiddle" alt="Reviewable"/>](https://reviewable.io/reviews/servo/rust-url/271)
<!-- Reviewable:end -->

Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 
 name = "url"
-version = "1.2.5"
+version = "1.3.0"
 authors = ["The rust-url developers"]
 
 description = "URL library for Rust, based on the WHATWG URL Standard"

src/lib.rs

@@ -125,6 +125,7 @@ use host::HostInternal;
 use parser::{Parser, Context, SchemeType, to_u32};
 use percent_encoding::{PATH_SEGMENT_ENCODE_SET, USERINFO_ENCODE_SET,
                        percent_encode, percent_decode, utf8_percent_encode};
+use std::borrow::Borrow;
 use std::cmp;
 #[cfg(feature = "serde")] use std::error::Error;
 use std::fmt::{self, Write};
@@ -242,6 +243,34 @@ impl Url {
         Url::options().parse(input)
     }
 
+    /// Parse an absolute URL from a string and add params to its query string.
+    ///
+    /// Existing params are not removed.
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// use url::Url;
+    ///
+    /// let url = Url::parse_with_params("https://example.net?dont=clobberme",
+    ///                                  &[("lang", "rust"), ("browser", "servo")]);
+    /// ```
+    #[inline]
+    pub fn parse_with_params<I, K, V>(input: &str, iter: I) -> Result<Url, ::ParseError>
+        where I: IntoIterator,
+              I::Item: Borrow<(K, V)>,
+              K: AsRef<str>,
+              V: AsRef<str>
+    {
+        let mut url = Url::options().parse(input);
+
+        if let Ok(ref mut url) = url {
+            url.query_pairs_mut().extend_pairs(iter);
+        }
+
+        url
+    }
+
     /// Parse a string as an URL, with this URL as the base URL.
     ///
     /// # Examples
@@ -1369,7 +1398,7 @@ impl Url {
     /// assert_eq!(url.as_str(), "foo://example.net/");
     /// assert!(result.is_ok());
     /// ```
-    /// 
+    ///
     ///
     /// Cannot change URL’s scheme from `https` to `foõ`:
     ///

tests/unit.rs

@@ -111,6 +111,14 @@ fn from_str() {
     assert!("http://testing.com/this".parse::<Url>().is_ok());
 }
 
+#[test]
+fn parse_with_params() {
+    let url = Url::parse_with_params("http://testing.com/this?dont=clobberme",
+                                     &[("lang", "rust")]).unwrap();
+
+    assert_eq!(url.as_str(), "http://testing.com/this?dont=clobberme&lang=rust");
+}
+
 #[test]
 fn issue_124() {
     let url: Url = "file:a".parse().unwrap();