improve docs, bump version

Author: PSeitz

CHANGELOG.md

@@ -1,3 +1,7 @@
+0.8.0 (2025-06-15)
+==================
+perf: add CowStr type to be able to use Cow::Borrowed on keys https://github.com/PSeitz/serde_json_borrow/pull/32 (Thanks @jszwec)
+
 0.7.1 (2024-11-02)
 ==================
 strip extra iteration when initialising ObjectAsVec https://github.com/PSeitz/serde_json_borrow/pull/29 (Thanks @meskill) 

Cargo.toml

@@ -3,7 +3,7 @@ name = "serde_json_borrow"
 categories = ["parsing", "parser-implementations", "encoding"]
 authors = ["Pascal Seitz <pascal.seitz@gmail.com>"]
 description = "Provides JSON deserialization into a borrowed DOM"
-version = "0.7.1"
+version = "0.8.0"
 edition = "2021"
 license = "MIT"
 keywords = ["JSON", "serde", "deserialization", "ref", "borrowed"]

src/lib.rs

@@ -25,6 +25,23 @@
 //! due to less allocations. By borrowing a DOM, the library ensures that no additional memory is
 //! allocated for `Strings`, that contain no JSON escape codes.
 //!
+//! # Usage
+//! ```rust
+//! use std::io;
+//! fn main() -> io::Result<()> {
+//!     let data: &str = r#"{"bool": true, "key": "123"}"#;
+//!     // Note that serde_json_borrow::Value<'ctx> is tied to the lifetime of data.
+//!     let value: serde_json_borrow::Value = serde_json::from_str(&data)?;
+//!     assert_eq!(value.get("bool"), &serde_json_borrow::Value::Bool(true));
+//!     assert_eq!(value.get("key"), &serde_json_borrow::Value::Str("123".into()));
+//!     // Using OwnedValue will take ownership of the String.
+//!     let value: serde_json_borrow::OwnedValue = serde_json_borrow::OwnedValue::from_str(&data)?;
+//!     assert_eq!(value.get("bool"), &serde_json_borrow::Value::Bool(true));
+//!     assert_eq!(value.get("key"), &serde_json_borrow::Value::Str("123".into()));
+//!     Ok(())
+//! }
+//! ```
+//!
 //! ## OwnedValue
 //! You can take advantage of [`OwnedValue`] to parse a `String` containing
 //! unparsed `JSON` into a `Value` without having to worry about lifetimes,
@@ -36,7 +53,7 @@
 //! support for escaped data in keys. Without the `cowkeys` feature flag `&str` is used, which does
 //! not allow any JSON escaping characters in keys.
 //!
-//! List of _unsupported_ characters (https://www.json.org/json-en.html) in object keys without `cowkeys` feature flag.
+//! List of _unsupported_ characters (<https://www.json.org/json-en.html>) in object keys without `cowkeys` feature flag.
 //!
 //! ```text
 //! \" represents the quotation mark character (U+0022).
@@ -48,18 +65,6 @@
 //! \r represents the carriage return character (U+000D).
 //! \t represents the character tabulation character (U+0009).
 //! ```
-//! # Usage
-//! ```rust
-//! use std::io;
-//! use serde_json_borrow::Value;
-//! fn main() -> io::Result<()> {
-//!     let data = r#"{"bool": true, "key": "123"}"#;
-//!     let value: Value = serde_json::from_str(&data)?;
-//!     assert_eq!(value.get("bool"), &Value::Bool(true));
-//!     assert_eq!(value.get("key"), &Value::Str("123".into()));
-//!     Ok(())
-//! }
-//! ```
 //! # Performance
 //! Performance gain depends on how many allocations can be avoided, and how many objects there are,
 //! as deserializing into a vec is significantly faster.
@@ -76,13 +81,13 @@ mod deserializer;
 mod index;
 mod num;
 mod object_vec;
-mod owned;
+mod ownedvalue;
 mod ser;
 mod value;
 
 #[cfg(feature = "cowkeys")]
 mod cowstr;
 
 pub use object_vec::{KeyStrType, ObjectAsVec, ObjectAsVec as Map};
-pub use owned::OwnedValue;
+pub use ownedvalue::OwnedValue;
 pub use value::Value;

src/object_vec.rs

@@ -6,11 +6,11 @@ use std::borrow::Cow;
 use crate::Value;
 
 #[cfg(feature = "cowkeys")]
-/// The string type used. Can be toggled between &str and Cow<str> via `cowstr` feature flag
+/// The string type used. Can be toggled between `&str` and `Cow<str>` via `cowstr` feature flag
 pub type KeyStrType<'a> = crate::cowstr::CowStr<'a>;
 
 #[cfg(not(feature = "cowkeys"))]
-/// The string type used. Can be toggled between &str and Cow<str> via `cowstr` feature flag
+/// The string type used. Can be toggled between `&str` and `Cow<str>` via `cowstr` feature flag
 /// Cow strings
 pub type KeyStrType<'a> = &'a str;
 
@@ -51,7 +51,7 @@ impl<'ctx> ObjectAsVec<'ctx> {
     /// # Note
     /// Since KeyStrType can be changed via a feature flag avoid using `as_vec` and use other
     /// methods instead. This could be a problem with feature unification, when one crate uses it
-    /// as &str and another uses it as Cow<str>, both will get Cow<str?
+    /// as `&str` and another uses it as `Cow<str>`, both will get `Cow<str>`
     #[inline]
     pub fn as_vec(&self) -> &Vec<(KeyStrType, Value<'ctx>)> {
         &self.0

src/owned.rs src/ownedvalue.rssrc/owned.rs renamed to src/ownedvalue.rs

@@ -3,10 +3,26 @@ use std::ops::Deref;
 
 use crate::Value;
 
-/// Parses a `String` into `Value`, by taking ownership of `String` and reference slices from it in
-/// contrast to copying the contents.
+/// Parses a `String` into `Value`, by taking ownership of `String` and reference slices from it.
+///
+/// With [`crate::Value`], your lifetime is tied to the lifetime of the
+/// passed `str`. This means that the `Value` can only be used as long as the original `str` is
+/// valid. With [`OwnedValue`], you get a owned Value instead.
+///
+/// Note: `OwnedValue` does not implement `Deserialize`, as it is not intended to be used for
+/// deserialization. It is designed to be used when you already have a `String` containing JSON
+/// data, and you want to parse it into a `Value` without worrying about lifetimes.
+///
+/// ## Example
+/// ```
+/// use serde_json::json;
+/// use crate::OwnedValue;
+/// let raw_json = r#"{"name": "John", "age": 30}"#;
+/// let owned_value = OwnedValue::from_string(raw_json.to_string()).unwrap();
+/// assert_eq!(owned_value.get("name"), &Value::Str("John".into()));
+/// assert_eq!(owned_value.get("age"), &Value::Number(30_u64.into()));
+/// ```
 ///
-/// This is done to mitigate lifetime issues.
 #[derive(Clone, Debug, Eq, PartialEq, Hash)]
 pub struct OwnedValue {
     /// Keep owned data, to be able to safely reference it from Value<'static>

src/ser.rs

@@ -1,13 +1,15 @@
 use serde::ser::{Serialize, Serializer};
 
 use crate::num::{Number, N};
-use crate::owned::OwnedValue;
+use crate::ownedvalue::OwnedValue;
 use crate::value::Value;
 use crate::Map;
 
 impl Serialize for Value<'_> {
     fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
-    where S: Serializer {
+    where
+        S: Serializer,
+    {
         match self {
             Value::Null => serializer.serialize_unit(),
             Value::Bool(b) => serializer.serialize_bool(*b),
@@ -20,21 +22,27 @@ impl Serialize for Value<'_> {
 }
 impl Serialize for Map<'_> {
     fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
-    where S: Serializer {
+    where
+        S: Serializer,
+    {
         serializer.collect_map(self.iter())
     }
 }
 
 impl Serialize for OwnedValue {
     fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
-    where S: Serializer {
+    where
+        S: Serializer,
+    {
         Value::serialize(self.get_value(), serializer)
     }
 }
 
 impl Serialize for Number {
     fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
-    where S: Serializer {
+    where
+        S: Serializer,
+    {
         match self.n {
             N::PosInt(n) => serializer.serialize_u64(n),
             N::NegInt(n) => serializer.serialize_i64(n),