diff --git a/ciborium/src/de/mod.rs b/ciborium/src/de/mod.rs index 18742e4..f511b7b 100644 --- a/ciborium/src/de/mod.rs +++ b/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(reader: R) -> Result> 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( 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( reader: R, diff --git a/ciborium/src/ser/mod.rs b/ciborium/src/ser/mod.rs index 39a46ad..0facbff 100644 --- a/ciborium/src/ser/mod.rs +++ b/ciborium/src/ser/mod.rs @@ -32,20 +32,35 @@ pub enum CanonicalizationScheme { #[cfg(feature = "std")] impl CanonicalizationScheme { - /// Does this canonicalisation scheme require sorting of keys. + /// Does this canonicalization scheme require sorting of keys. pub fn is_sorting(&self) -> bool { matches!(self, Self::Rfc7049 | Self::Rfc8049) } - - // pub fn key(&self, key: &K) -> Result, Error> { - // let mut buffer = Vec::new(); - // let mut serializer = Serializer::new(&mut buffer, true); - // key.serialize(&mut serializer)?; - // Ok(buffer) - // } } /// A serializer for CBOR. +/// +/// # Example +/// ```rust +/// use serde::Serialize; +/// use ciborium::Serializer; +/// use ciborium::ser::CanonicalizationScheme; +/// +/// #[derive(serde::Serialize)] +/// struct Example { +/// a: u64, +/// aa: u64, +/// b: u64, +/// } +/// +/// let example = Example { a: 42, aa: 420, b: 4200 }; +/// +/// let mut buffer = Vec::with_capacity(1024); +/// let mut serializer = Serializer::new(&mut buffer, CanonicalizationScheme::Rfc8049); +/// example.serialize(&mut serializer).unwrap(); +/// +/// assert_eq!(hex::encode(&buffer), "a36161182a61621910686261611901a4"); +/// ``` pub struct Serializer { encoder: Encoder, @@ -647,6 +662,23 @@ where } /// Serializes as CBOR into `Vec`. +/// +/// # Example +/// ```rust +/// use ciborium::to_vec; +/// +/// #[derive(serde::Serialize)] +/// struct Example { +/// a: u64, +/// aa: u64, +/// b: u64, +/// } +/// +/// let example = Example { a: 42, aa: 420, b: 4200 }; +/// let bytes = to_vec(&example).unwrap(); +/// +/// assert_eq!(hex::encode(&bytes), "a36161182a6261611901a46162191068"); +/// ``` #[cfg(feature = "std")] #[inline] pub fn to_vec(value: &T) -> Result, Error> { @@ -657,6 +689,24 @@ pub fn to_vec(value: &T) -> Result, Error` with a specified [CanonicalizationScheme]. +/// +/// # Example +/// ```rust +/// use ciborium::to_vec_canonical; +/// use ciborium::ser::CanonicalizationScheme; +/// +/// #[derive(serde::Serialize)] +/// struct Example { +/// a: u64, +/// aa: u64, +/// b: u64, +/// } +/// +/// let example = Example { a: 42, aa: 420, b: 4200 }; +/// let bytes = to_vec_canonical(&example, CanonicalizationScheme::Rfc8049).unwrap(); +/// +/// assert_eq!(hex::encode(&bytes), "a36161182a61621910686261611901a4"); +/// ``` #[cfg(feature = "std")] #[inline] pub fn to_vec_canonical(value: &T, scheme: CanonicalizationScheme) -> Result, Error> { @@ -667,6 +717,25 @@ pub fn to_vec_canonical(value: &T, scheme: Canonical } /// Serializes as CBOR into a type with [`impl ciborium_io::Write`](ciborium_io::Write) +/// +/// # Example +/// ```rust +/// use ciborium::into_writer; +/// +/// #[derive(serde::Serialize)] +/// struct Example { +/// a: u64, +/// aa: u64, +/// b: u64, +/// } +/// +/// let example = Example { a: 42, aa: 420, b: 4200 }; +/// +/// let mut bytes = Vec::new(); +/// into_writer(&example, &mut bytes).unwrap(); +/// +/// assert_eq!(hex::encode(&bytes), "a36161182a6261611901a46162191068"); +/// ``` #[inline] pub fn into_writer( value: &T, @@ -682,6 +751,26 @@ where /// Canonically serializes as CBOR into a type with [`impl ciborium_io::Write`](ciborium_io::Write) /// /// This will sort map keys in output according to a specified [CanonicalizationScheme]. +/// +/// # Example +/// ```rust +/// use ciborium::into_writer_canonical; +/// use ciborium::ser::CanonicalizationScheme; +/// +/// #[derive(serde::Serialize)] +/// struct Example { +/// a: u64, +/// aa: u64, +/// b: u64, +/// } +/// +/// let example = Example { a: 42, aa: 420, b: 4200 }; +/// +/// let mut bytes = Vec::new(); +/// into_writer_canonical(&example, &mut bytes, CanonicalizationScheme::Rfc8049).unwrap(); +/// +/// assert_eq!(hex::encode(&bytes), "a36161182a61621910686261611901a4"); +/// ``` #[cfg(feature = "std")] #[inline] pub fn into_writer_canonical(