From 162e041a00137503fb12a77ff2174a17ae36cd95 Mon Sep 17 00:00:00 2001 From: Jonathan Johnson Date: Wed, 30 Oct 2024 09:41:35 -0700 Subject: [PATCH] Doctests --- src/de.rs | 21 +++++++++++++++ src/lib.rs | 37 +++++++++++++++++++++++++++ src/ser.rs | 75 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 133 insertions(+) diff --git a/src/de.rs b/src/de.rs index fbf1b29..caa4f4b 100644 --- a/src/de.rs +++ b/src/de.rs @@ -1393,6 +1393,13 @@ impl Display for ErrorKind { impl Config { /// Deserializes `T` from `source` using this configuration. /// + /// ```rust + /// let deserialized: Vec = rsn::parser::Config::default() + /// .deserialize("[1, 2, 3]") + /// .unwrap(); + /// assert_eq!(deserialized, vec![1, 2, 3]); + /// ``` + /// /// # Errors /// /// Returns an error if `source` cannot be deserialized as `T`. @@ -1413,6 +1420,13 @@ impl Config { /// Deserializes `T` from `source` using this configuration. /// + /// ```rust + /// let deserialized: Vec = rsn::parser::Config::default() + /// .deserialize_from_slice(b"[1, 2, 3]") + /// .unwrap(); + /// assert_eq!(deserialized, vec![1, 2, 3]); + /// ``` + /// /// # Errors /// /// Returns an error if `source` cannot be deserialized as `T`. @@ -1437,6 +1451,13 @@ impl Config { /// Deserializes `T` from `reader` using this configuration. /// + /// ```rust + /// let deserialized: Vec = rsn::parser::Config::default() + /// .deserialize_from_reader(&b"[1, 2, 3]"[..]) + /// .unwrap(); + /// assert_eq!(deserialized, vec![1, 2, 3]); + /// ``` + /// /// # Errors /// /// Returns any errors encountered while reading from `reader` or if diff --git a/src/lib.rs b/src/lib.rs index 17ffbe1..1a91a01 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -27,6 +27,11 @@ pub mod writer; /// Deserializes `D` from `source` using the default Rsn /// [`Config`](parser::Config). /// +/// ```rust +/// let deserialized: Vec = rsn::from_str("[1, 2, 3]").unwrap(); +/// assert_eq!(deserialized, vec![1, 2, 3]); +/// ``` +/// /// # Errors /// /// Returns an error if `source` isn't valid Rsn or cannot be deserialized as @@ -39,6 +44,11 @@ pub fn from_str<'de, D: serde::Deserialize<'de>>(source: &'de str) -> Result = rsn::from_slice(b"[1, 2, 3]").unwrap(); +/// assert_eq!(deserialized, vec![1, 2, 3]); +/// ``` +/// /// # Errors /// /// Returns an error if `slice` isn't valid Rsn or cannot be deserialized as @@ -51,6 +61,11 @@ pub fn from_slice<'de, D: serde::Deserialize<'de>>(source: &'de [u8]) -> Result< /// Deserializes `D` from `reader` using the default Rsn /// [`Config`](parser::Config). /// +/// ```rust +/// let deserialized: Vec = rsn::from_reader(&b"[1, 2, 3]"[..]).unwrap(); +/// assert_eq!(deserialized, vec![1, 2, 3]); +/// ``` +/// /// # Errors /// /// Returns an error if `reader` returns an error while reading, doesn't contain @@ -65,6 +80,11 @@ pub fn from_reader( /// Serializes `value` into a `String` using the default Rsn /// [`Config`](ser::Config). /// +/// ```rust +/// let serialized = rsn::to_string(&vec![1, 2, 3]).unwrap(); +/// assert_eq!(serialized, "[1,2,3]"); +/// ``` +/// /// # Errors /// /// Rsn itself does not produce any errors while serializing values. This @@ -80,6 +100,11 @@ pub fn to_string( /// Serializes `value` into a `Vec` using the default Rsn /// [`Config`](ser::Config). /// +/// ```rust +/// let serialized = rsn::to_vec(&vec![1, 2, 3]).unwrap(); +/// assert_eq!(serialized, b"[1,2,3]"); +/// ``` +/// /// # Errors /// /// Rsn itself does not produce any errors while serializing values. This @@ -93,6 +118,12 @@ pub fn to_vec(value: &S) -> Result, cor /// Serializes `value` into a writer using the default Rsn /// [`Config`](ser::Config). /// +/// ```rust +/// let mut serialized = Vec::new(); +/// rsn::to_writer(&vec![1, 2, 3], &mut serialized).unwrap(); +/// assert_eq!(serialized, b"[1,2,3]"); +/// ``` +/// /// # Errors /// /// Returns any errors occurring while serializing `value` or while writing to @@ -108,6 +139,12 @@ pub fn to_writer( /// Serializes `value` into a `String` using /// [`Config::pretty()`](ser::Config::pretty()). /// +/// ```rust +/// let input = vec![1, 2, 3]; +/// let serialized = rsn::to_string_pretty(&input).unwrap(); +/// assert_eq!(serialized, "[\n 1,\n 2,\n 3\n]"); +/// ``` +/// /// # Errors /// /// Rsn itself does not produce any errors while serializing values. This diff --git a/src/ser.rs b/src/ser.rs index b15426d..0ddd651 100644 --- a/src/ser.rs +++ b/src/ser.rs @@ -483,6 +483,15 @@ impl Config { /// - `writer`: [`writer::Config::Compact`] /// - `implicit_map_at_root`: `false` /// - `anonymous_structs`: `false` + /// + /// ```rust + /// use std::collections::HashMap; + /// + /// let serialized = rsn::ser::Config::new() + /// .serialize(&HashMap::from([("hello", "world")])) + /// .unwrap(); + /// assert_eq!(serialized, r#"{"hello":"world"}"#) + /// ``` #[must_use] pub const fn new() -> Self { Self { @@ -493,6 +502,20 @@ impl Config { } /// Returns the default configuration with nested indentation and newlines. + /// + /// ```rust + /// use std::collections::HashMap; + /// + /// let serialized = rsn::ser::Config::pretty() + /// .serialize(&HashMap::from([("hello", "world")])) + /// .unwrap(); + /// assert_eq!( + /// serialized, + /// r#"{ + /// "hello": "world" + /// }"# + /// ); + /// ``` #[must_use] pub fn pretty() -> Self { Self { @@ -505,6 +528,16 @@ impl Config { } /// Sets [`Config::implicit_map_at_root`] and returns self. + /// + /// ```rust + /// use std::collections::HashMap; + /// + /// let serialized = rsn::ser::Config::pretty() + /// .implicit_map_at_root(true) + /// .serialize(&HashMap::from([("hello", "world")])) + /// .unwrap(); + /// assert_eq!(serialized, "\"hello\": \"world\"\n"); + /// ``` #[must_use] pub const fn implicit_map_at_root(mut self, implicit_map_at_root: bool) -> Self { self.implicit_map_at_root = implicit_map_at_root; @@ -512,6 +545,28 @@ impl Config { } /// Sets [`Config::anonymous_structs`] and returns self. + /// + /// ```rust + /// use serde::Serialize; + /// + /// #[derive(Serialize)] + /// struct Person { + /// name: &'static str, + /// } + /// + /// // With anonymous structures enabled + /// let anonymous_structs = rsn::ser::Config::new() + /// .anonymous_structs(true) + /// .serialize(&Person { name: "Bob" }) + /// .unwrap(); + /// assert_eq!(anonymous_structs, r#"{name:"Bob"}"#); + /// + /// // The default configuration + /// let default_config = rsn::ser::Config::new() + /// .serialize(&Person { name: "Bob" }) + /// .unwrap(); + /// assert_eq!(default_config, r#"Person{name:"Bob"}"#); + /// ``` #[must_use] pub const fn anonymous_structs(mut self, anonymous_structs: bool) -> Self { self.anonymous_structs = anonymous_structs; @@ -520,6 +575,11 @@ impl Config { /// Returns `value` serialized as Rsn with this configuration. /// + /// ```rust + /// let serialized = rsn::ser::Config::new().serialize(&vec![1, 2, 3]).unwrap(); + /// assert_eq!(serialized, "[1,2,3]"); + /// ``` + /// /// # Errors /// /// Rsn itself does not produce any errors while serializing values. This @@ -533,6 +593,13 @@ impl Config { /// Returns `value` serialized as Rsn with this configuration. /// + /// ```rust + /// let serialized = rsn::ser::Config::new() + /// .serialize_to_vec(&vec![1, 2, 3]) + /// .unwrap(); + /// assert_eq!(serialized, b"[1,2,3]"); + /// ``` + /// /// # Errors /// /// Rsn itself does not produce any errors while serializing values. This @@ -576,6 +643,14 @@ mod serialize_writer { impl Config { /// Serializes `value` into `writer` using this configuration. /// + /// ```rust + /// let mut serialized = Vec::new(); + /// rsn::ser::Config::new() + /// .serialize_to_writer(&vec![1, 2, 3], &mut serialized) + /// .unwrap(); + /// assert_eq!(serialized, b"[1,2,3]"); + /// ``` + /// /// # Errors /// /// Returns any errors occurring while serializing `value` or while