diff options
| -rw-r--r-- | examples/introduction.rs | 10 | ||||
| -rw-r--r-- | src/lib.rs | 28 |
2 files changed, 37 insertions, 1 deletions
diff --git a/examples/introduction.rs b/examples/introduction.rs index d980719..a1f6fc9 100644 --- a/examples/introduction.rs +++ b/examples/introduction.rs @@ -7,6 +7,8 @@ extern crate serde_urlencoded as urlencoded; use rand::Rng; use std::collections::HashMap; +use qs::Config; + #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] struct Address { city: String, @@ -64,9 +66,15 @@ fn main() { // as a list of pairs using serde_urlencoded: let pairs: Vec<(String, String)> = urlencoded::from_str(&encoded).unwrap(); println!("`serde_urlencoded` from_str to pairs:\n\t{:?}", pairs); + // However, the best way is to use serde_qs to deserialize the entire thing // into a struct: - let params: QueryParams = qs::from_str(&encoded).unwrap(); + // + // (For this round trip to work, it's necessary to parse the query string + // in non-strict mode, to allow parsing of url_encoded square brackets + // in the key. See the lib.rs documentation for why). + let qs_non_strict = Config::new(5, false); + let params: QueryParams = qs_non_strict.deserialize_str(&encoded).unwrap(); assert_eq!(params, example_params); println!("`serde_qs` from_str to struct:\n\t{:?}", params); @@ -70,6 +70,34 @@ //! assert_eq!(rec_params, params); //! //! # } +//! ``` +//! +//! ## Strict vs Non-Strict modes +//! +//! `serde_qs` supports two operating modes, which can be specified using +//! [`Config`](struct.Config.html), and is all about how `serde_qs` handles square brackets. +//! +//! Techncially, square brackets should be encoded in URLs as `%5B` and `%5D`. +//! However, they are often used in their raw format to specify querystrings +//! such as `a[b]=123`. +//! +//! In strict mode, `serde_qs` will only tolerate unencoded square brackets +//! to denote nested keys. So `a[b]=123` will decode as `{"a": {"b": 123}}`. +//! This means that encoded square brackets can actually be part of the key. +//! `a[b%5Bc%5D]=123` becomes `{"a": {"b[c]": 123}}`. +//! +//! However, since some implementations will automatically encode everything +//! in the URL, we also have a non-strict mode. This means that `serde_qs` +//! will assume that any encoded square brackets in the string were meant to +//! be taken as nested keys. From the example before, `a[b%5Bc%5D]=123` will +//! now become `{"a": {"b": {"c": 123 }}}`. +//! +//! Non-strict mode can be useful when, as said before, some middleware +//! automatically encodes the brackets. But care must be taken to avoid +//! using keys with square brackets in them, or unexpected things can +//! happen. +//! +//! #![allow( )] |