Add convenience functions (fixes #2)

src/de.rs

@@ -4,9 +4,48 @@ use serde::de;
 use serde::de::value::MapDeserializer;
 use std::borrow::Cow;
 use url::form_urlencoded::Parse as UrlEncodedParse;
+use url::form_urlencoded::parse;
 
 pub use serde::de::value::Error;
 
+/// Deserializes a `application/x-wwww-url-encoded` value from a `&[u8]`.
+///
+/// ```
+/// let meal = vec![
+///     ("bread".to_owned(), "baguette".to_owned()),
+///     ("cheese".to_owned(), "comté".to_owned()),
+///     ("meat".to_owned(), "ham".to_owned()),
+///     ("fat".to_owned(), "butter".to_owned()),
+/// ];
+///
+/// assert_eq!(
+///     serde_urlencoded::from_bytes::<Vec<(String, String)>>(
+///         b"bread=baguette&cheese=comt%C3%A9&meat=ham&fat=butter"),
+///     Ok(meal));
+/// ```
+pub fn from_bytes<T: de::Deserialize>(input: &[u8]) -> Result<T, Error> {
+    T::deserialize(&mut Deserializer::new(parse(input)))
+}
+
+/// Deserializes a `application/x-wwww-url-encoded` value from a `&str`.
+///
+/// ```
+/// let meal = vec![
+///     ("bread".to_owned(), "baguette".to_owned()),
+///     ("cheese".to_owned(), "comté".to_owned()),
+///     ("meat".to_owned(), "ham".to_owned()),
+///     ("fat".to_owned(), "butter".to_owned()),
+/// ];
+///
+/// assert_eq!(
+///     serde_urlencoded::from_str::<Vec<(String, String)>>(
+///         "bread=baguette&cheese=comt%C3%A9&meat=ham&fat=butter"),
+///     Ok(meal));
+/// ```
+pub fn from_str<T: de::Deserialize>(input: &str) -> Result<T, Error> {
+    from_bytes(input.as_bytes())
+}
+
 /// A deserializer for the `application/x-www-form-urlencoded` format.
 ///
 /// * Supported top-level outputs are structs, maps and sequences of pairs,

src/lib.rs

@@ -7,5 +7,5 @@ extern crate url;
 pub mod de;
 pub mod ser;
 
-pub use de::Deserializer;
-pub use ser::Serializer;
+pub use de::{Deserializer, from_bytes, from_str};
+pub use ser::{Serializer, to_string};

src/ser/mod.rs

@@ -12,6 +12,29 @@ use std::str;
 use url::form_urlencoded::Serializer as UrlEncodedSerializer;
 use url::form_urlencoded::Target as UrlEncodedTarget;
 
+/// Serializes a value into a `application/x-wwww-url-encoded` `String` buffer.
+///
+/// ```
+/// let meal = &[
+///     ("bread", "baguette"),
+///     ("cheese", "comté"),
+///     ("meat", "ham"),
+///     ("fat", "butter"),
+/// ];
+///
+/// assert_eq!(
+///     serde_urlencoded::to_string(meal),
+///     Ok("bread=baguette&cheese=comt%C3%A9&meat=ham&fat=butter".to_owned()));
+/// ```
+pub fn to_string<T: ser::Serialize>(input: &T) -> Result<String, Error> {
+    let mut output = String::new();
+    {
+        let mut urlencoder = UrlEncodedSerializer::new(&mut output);
+        try!(input.serialize(&mut Serializer::new(&mut urlencoder)));
+    }
+    Ok(output)
+}
+
 /// A serializer for the `application/x-www-form-urlencoded` format.
 ///
 /// * Supported top-level inputs are structs, maps and sequences of pairs,
@@ -32,7 +55,7 @@ impl<'output, T: 'output + UrlEncodedTarget> Serializer<'output, T> {
 }
 
 /// Errors returned during serializing to `application/x-www-form-urlencoded`.
-#[derive(Clone, Debug)]
+#[derive(Clone, Debug, PartialEq, Eq)]
 pub enum Error {
     Custom(Cow<'static, str>),
     InvalidValue(Cow<'static, str>),