feat: rfc8949 and rfc7049 canonicalized output

Signed-off-by: Liam Gray <hoxxep@gmail.com>

Author: hoxxep

ciborium/Cargo.toml

@@ -24,12 +24,12 @@ is-it-maintained-open-issues = { repository = "enarx/ciborium" }
 ciborium-ll = { path = "../ciborium-ll", version = "0.2.2" }
 ciborium-io = { path = "../ciborium-io", version = "0.2.2", features = ["alloc"] }
 serde = { version = "1.0.170", default-features = false, features = ["alloc", "derive"] }
+hex = "0.4"
 
 [dev-dependencies]
 serde_bytes = "0.11"
 rstest = "0.23.0"
 rand = "0.8"
-hex = "0.4"
 
 [features]
 default = ["std"]

ciborium/src/de/mod.rs

@@ -786,6 +786,24 @@ where
 /// If you want to deserialize faster at the cost of more memory, consider using
 /// [`from_reader_with_buffer`](from_reader_with_buffer) with a larger buffer,
 /// for example 64KB.
+///
+/// # Example
+/// ```rust
+/// use ciborium::from_reader;
+///
+/// #[derive(Debug, serde::Deserialize, Eq, PartialEq)]
+/// struct Example {
+///     a: u64,
+///     aa: u64,
+///     b: u64,
+/// }
+///
+/// let cbor = hex::decode("a36161182a61621910686261611901a4").unwrap();
+/// let expected = Example { a: 42, aa: 420, b: 4200 };
+///
+/// let deserialized: Example = from_reader(cbor.as_slice()).unwrap();
+/// assert_eq!(deserialized, expected);
+/// ```
 #[inline]
 pub fn from_reader<T: de::DeserializeOwned, R: Read>(reader: R) -> Result<T, Error<R::Error>>
 where
@@ -798,6 +816,25 @@ where
 /// Deserializes as CBOR from a type with [`impl
 /// ciborium_io::Read`](ciborium_io::Read), using a caller-specific buffer as a
 /// temporary scratch space.
+///
+/// # Example
+/// ```rust
+/// use ciborium::from_reader_with_buffer;
+///
+/// #[derive(Debug, serde::Deserialize, Eq, PartialEq)]
+/// struct Example {
+///     a: u64,
+///     aa: u64,
+///     b: u64,
+/// }
+///
+/// let cbor = hex::decode("a36161182a61621910686261611901a4").unwrap();
+/// let expected = Example { a: 42, aa: 420, b: 4200 };
+///
+/// let mut scratch = [0; 8192];
+/// let deserialized: Example = from_reader_with_buffer(cbor.as_slice(), &mut scratch).unwrap();
+/// assert_eq!(deserialized, expected);
+/// ```
 #[inline]
 pub fn from_reader_with_buffer<T: de::DeserializeOwned, R: Read>(
     reader: R,
@@ -820,6 +857,24 @@ where
 /// will result in [`Error::RecursionLimitExceeded`] .
 ///
 /// Set a high recursion limit at your own risk (of stack exhaustion)!
+///
+/// # Example
+/// ```rust
+/// use ciborium::de::from_reader_with_recursion_limit;
+///
+/// #[derive(Debug, serde::Deserialize, Eq, PartialEq)]
+/// struct Example {
+///     a: u64,
+///     aa: u64,
+///     b: u64,
+/// }
+///
+/// let cbor = hex::decode("a36161182a61621910686261611901a4").unwrap();
+/// let expected = Example { a: 42, aa: 420, b: 4200 };
+///
+/// let deserialized: Example = from_reader_with_recursion_limit(cbor.as_slice(), 1024).unwrap();
+/// assert_eq!(deserialized, expected);
+/// ```
 #[inline]
 pub fn from_reader_with_recursion_limit<T: de::DeserializeOwned, R: Read>(
     reader: R,

ciborium/src/lib.rs

@@ -99,12 +99,14 @@ pub mod value;
 
 // Re-export the [items recommended by serde](https://serde.rs/conventions.html).
 #[doc(inline)]
-pub use crate::de::from_reader;
+pub use crate::de::{from_reader, from_reader_with_buffer, Deserializer};
+
 #[doc(inline)]
-pub use crate::de::from_reader_with_buffer;
+pub use crate::ser::{into_writer, Serializer};
 
 #[doc(inline)]
-pub use crate::ser::into_writer;
+#[cfg(feature = "std")]
+pub use crate::ser::{into_writer_canonical, to_vec, to_vec_canonical};
 
 #[doc(inline)]
 pub use crate::value::Value;