From 902fb6c3d625e12023a72498475574413a6e620a Mon Sep 17 00:00:00 2001
From: Walther Chen <walther.chen@gmail.com>
Date: Sat, 4 Aug 2018 11:08:11 -0400
Subject: use non-strict parsing to allow round-trip in example
---
examples/introduction.rs | 10 +++++++++-
1 file changed, 9 insertions(+), 1 deletion(-)
diff --git a/examples/introduction.rs b/examples/introduction.rs
index d980719..9878968 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).
+ 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);
--
cgit v1.2.3
From 51b9edc66b0320e4ad8680416f040070c2b3810c Mon Sep 17 00:00:00 2001
From: Sam Scott <sam.scott89@gmail.com>
Date: Sat, 4 Aug 2018 12:13:46 -0400
Subject: Update documentation to clarify strict encoding modes.
---
Cargo.toml | 2 +-
README.md | 2 +-
examples/introduction.rs | 2 +-
src/lib.rs | 28 ++++++++++++++++++++++++++++
4 files changed, 31 insertions(+), 3 deletions(-)
diff --git a/Cargo.toml b/Cargo.toml
index 8ea1c37..d832662 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -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]
diff --git a/README.md b/README.md
index a2ef973..034e9dd 100644
--- a/README.md
+++ b/README.md
@@ -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);
diff --git a/src/lib.rs b/src/lib.rs
index 2da9b2a..b2bd63c 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -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(
)]
--
cgit v1.2.3