From 51b9edc66b0320e4ad8680416f040070c2b3810c Mon Sep 17 00:00:00 2001 From: Sam Scott Date: Sat, 4 Aug 2018 12:13:46 -0400 Subject: Update documentation to clarify strict encoding modes. --- src/lib.rs | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) (limited to 'src') 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