diff options
| -rw-r--r-- | Cargo.toml | 2 | ||||
| -rw-r--r-- | README.md | 2 | ||||
| -rw-r--r-- | examples/introduction.rs | 2 | ||||
| -rw-r--r-- | src/lib.rs | 28 |
4 files changed, 31 insertions, 3 deletions
@@ -8,7 +8,7 @@ license = "MIT/Apache-2.0" name = "serde_qs" repository = "https://github.com/samscott89/serde_qs" readme = "README.md" -version = "0.4.1" +version = "0.4.2" [badges] @@ -26,7 +26,7 @@ This crate works with Cargo and can be found on ```toml [dependencies] -serde_qs = "0.4.1" +serde_qs = "0.4.2" ``` [crates.io]: https://crates.io/crates/serde_qs diff --git a/examples/introduction.rs b/examples/introduction.rs index 9878968..a1f6fc9 100644 --- a/examples/introduction.rs +++ b/examples/introduction.rs @@ -72,7 +72,7 @@ fn main() { // // (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). + // 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); @@ -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( )] |