From b69c42eb9b9f055e74353c9c149074616eff181f Mon Sep 17 00:00:00 2001
From: Sam Scott <sam.scott89@gmail.com>
Date: Wed, 23 Jan 2019 11:13:18 -0500
Subject: Add documentation and workaroud for `#[serde(flatten)]` usage.
---
src/lib.rs | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 48 insertions(+)
(limited to 'src')
diff --git a/src/lib.rs b/src/lib.rs
index 15e4036..1c3d33e 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -97,7 +97,55 @@
//! using keys with square brackets in them, or unexpected things can
//! happen.
//!
+//! ## Flatten workaround
+//!
+//! A current [known limitation](https://github.com/serde-rs/serde/issues/1183)
+//! in `serde` is deserializing `#[serde(flatten)]` structs for formats which
+//! are not self-describing. This includes query strings: `12` can be an integer
+//! or a string, for example.
+//!
+//! We suggest the following workaround:
+//!
+//! ```
+//! extern crate serde;
+//! #[macro_use]
+//! extern crate serde_derive;
+//! extern crate serde_qs as qs;
+//!
+//! use serde::de::Error;
//!
+//! fn from_str<'de, D, S>(deserializer: D) -> Result<S, D::Error>
+//! where D: serde::Deserializer<'de>,
+//! S: std::str::FromStr
+//! {
+//! let s = <&str as serde::Deserialize>::deserialize(deserializer)?;
+//! S::from_str(&s).map_err(|_| D::Error::custom("could not parse string"))
+//! }
+//!
+//! #[derive(Deserialize, Serialize, Debug, PartialEq)]
+//! struct Query {
+//! a: u8,
+//! #[serde(flatten)]
+//! common: CommonParams,
+//! }
+//!
+//! #[derive(Deserialize, Serialize, Debug, PartialEq)]
+//! struct CommonParams {
+//! #[serde(deserialize_with="from_str")]
+//! limit: u64,
+//! #[serde(deserialize_with="from_str")]
+//! offset: u64,
+//! #[serde(deserialize_with="from_str")]
+//! remaining: bool,
+//! }
+//!
+//! fn main() {
+//! let params = "a=1&limit=100&offset=50&remaining=true";
+//! let query = Query { a: 1, common: CommonParams { limit: 100, offset: 50, remaining: true } };
+//! let rec_query: Result<Query, _> = qs::from_str(params);
+//! assert_eq!(rec_query.unwrap(), query);
+//! }
+//! ```
#![allow(
)]
--
cgit v1.2.3