From 1446b93f089fe62b415341055fe42ff837b0a864 Mon Sep 17 00:00:00 2001 From: Christiaan Biesterbosch Date: Sun, 8 Sep 2024 23:56:21 +0200 Subject: [PATCH 1/2] Improve and update the documentation Both README.md and the lib.rs documentation were missing features the other had. I've merged the two and updated where necessary, and made it so that lib.rs includes the README.md content. I've also made various small fixes in various places. --- Cargo.toml | 2 +- README.md | 177 ++++++++++++++++++++++++++++++++++++-------------- src/cow.rs | 8 ++- src/lib.rs | 106 +----------------------------- src/macros.rs | 7 +- 5 files changed, 144 insertions(+), 156 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index 419b0725..042d2e0b 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -79,7 +79,7 @@ known-key = ["once_cell", "ahash"] # use 8 number at once parsing strategy swar-number-parsing = [] -# Uses a approximate float parsing algorithm that is faster +# Uses an approximate float parsing algorithm that is faster # but does not guarantee round trips for the edges approx-number-parsing = [] diff --git a/README.md b/README.md index c27304aa..a3e4bdf9 100644 --- a/README.md +++ b/README.md @@ -10,89 +10,170 @@ [Code Coverage]: https://coveralls.io/repos/github/simd-lite/simd-json/badge.svg?branch=main [coveralls]: https://coveralls.io/github/simd-lite/simd-json?branch=main -**Rust port of extremely fast [simdjson](https://github.com/lemire/simdjson) JSON parser with [serde][1] compatibility.** +**Rust port of extremely fast [simdjson](https://github.com/lemire/simdjson) JSON parser with [Serde][serde] compatibility.** --- -## readme (for real!) +simd-json is a Rust port of the [simdjson c++ library](https://simdjson.org/). +It follows most of the design closely with a few exceptions to make it better +fit into the Rust ecosystem. -### simdjson version +## Goals -**Currently tracking version 0.2.x of simdjson upstream (work in progress, feedback is welcome!).** +The goal of the Rust port of simdjson is not to create a one-to-one +copy, but to integrate the principles of the C++ library into +a Rust library that plays well with the Rust ecosystem. As such +we provide both compatibility with Serde as well as parsing to a +DOM to manipulate data. -### CPU target +## Performance -To be able to take advantage of `simd-json` your system needs to be SIMD-capable. On `x86`, it will select the best SIMD feature set (`avx2` or `sse4.2`) during runtime. If `simd-json` is compiled with SIMD support, it will disable runtime detection. +As a rule of thumb this library tries to get as close as possible +to the performance of the C++ implementation (currently tracking 0.2.x, work in progress). +However, in some design decisions—such as parsing to a DOM or a tape—ergonomics is prioritized over +performance. In other places Rust makes it harder to achieve the same level of performance. -`simd-json` supports AVX2, SSE4.2, NEON, and simd128 (wasm) natively. It also includes an unoptimized fallback implementation using native rust for other platforms; however, this is a last resort measure and nothing we'd recommend relying on. +To take advantage of this library your system needs to support SIMD instructions. On `x86`, it will +select the best available supported instruction set (`avx2` or `sse4.2`) when the `runtime-detection` feature +is enabled (default). On `aarch64` this library uses the `NEON` instruction set. On `wasm` this library uses +the `simd128` instruction set when available. When no supported SIMD instructions are found, this library will use a +fallback implementation, but this is significantly slower. -### Performance characteristics +### Allocator +For best performance, we highly suggest using [mimalloc](https://crates.io/crates/mimalloc) or [jemalloc](https://crates.io/crates/jemalloc) instead of the system allocator used by +default. Another recent allocator that works well (but we have yet to test it in production) is [snmalloc](https://github.com/microsoft/snmalloc). -- CPU native cpu compilation results in the best performance. -- CPU detection for AVX and SSE4.2 is the second fastest (on x86_* only). -- Portable std::simd is the next fast implementation when compiled with a native CPU target. -- std::simd or the rust native implementation is the least performant. -### allocator +## Safety -For best performance, we highly suggest using [mimalloc](https://crates.io/crates/mimalloc) or [jemalloc](https://crates.io/crates/jemalloc) instead of the system allocator used by default. Another recent allocator that works well (but we have yet to test it in production) is [snmalloc](https://github.com/microsoft/snmalloc). +`simd-json` uses **a lot** of unsafe code. -### `runtime-detection` +There are a few reasons for this: -This feature allows selecting the optimal algorithm based on available features during runtime; it has no effect on non-x86 or x86_64 platforms. When neither `AVX2` nor `SSE4.2` is supported, it will fall back to a native rust implementation. +* SIMD intrinsics are inherently unsafe. These uses of unsafe are inescapable in a library such as `simd-json`. +* We work around some performance bottlenecks imposed by safe rust. These are avoidable, but at a performance cost. + This is a more considered path in `simd-json`. -Note that an application compiled with `runtime-detection` will not run as fast as an application compiled for a specific CPU. The reason is that rust can't optimise as far as the instruction set when it uses the generic instruction set, and non-simd parts of the code won't be optimised for the given instruction set either. -### `portable` +`simd-json` goes through extra scrutiny for unsafe code. These steps are: -**Currently disabled** +* Unit tests - to test 'the obvious' cases, edge cases, and regression cases +* Structural constructive property based testing - We generate random valid JSON objects to exercise the full `simd-json` + codebase stochastically. Floats are currently excluded since slightly different parsing algorithms lead to slightly + different results here. In short "is simd-json correct". +* Data-oriented property-based testing of string-like data - to assert that sequences of legal printable characters + don't panic or crash the parser (they might and often error so - they are not valid JSON!) +* Destructive Property based testing - make sure that no illegal byte sequences crash the parser in any way +* Fuzzing - fuzz based on upstream & jsonorg simd pass/fail cases +* Miri testing for UB + +This doesn't ensure complete safety nor is at a bulletproof guarantee, but it does go a long way +to assert that the library is of high production quality and fit for purpose for practical industrial applications. + +## Features +Various features can be enabled or disabled to tweak various parts of this library. Any features not mentioned here are +for internal configuration and testing. + +### `runtime-detection` (default) + +This feature allows selecting the optimal algorithm based on available features during runtime. It has no effect on +non-`x86` platforms. When neither `AVX2` nor `SSE4.2` is supported, it will fall back to a native Rust implementation. + +Disabling this feature (with `default-features = false`) **and** setting `RUSTFLAGS="-C target-cpu=native` will result +in better performance but the resulting binary will not be portable across `x86` processors. -An implementation of the algorithm using `std::simd` and up to 512 byte wide registers, currently disabled due to dependencies and is highly experimental. +### `serde_impl` (default) -### `serde_impl` +Enable [Serde](https://serde.rs) support. This consist of implementing `serde::Serializer` and `serde::Deserializer`, +allowing types that implement `serde::Serialize`/`serde::Deserialize` to be constructed/serialized to +`BorrowedValue`/`OwnedValue`. +In addition, this provides the same convenience functions that [`serde_json`](https://docs.rs/serde_json/latest/serde_json/) provides. -`simd-json` is compatible with serde and `serde-json`. The Value types provided implement serializers and deserializers. In addition to that `simd-json` implements the `Deserializer` trait for the parser so it can deserialize anything that implements the serde `Deserialize` trait. Note, that serde provides both a `Deserializer` and a `Deserialize` trait. +Disabling this feature (with `default-features = false`) will remove `serde` and `serde_json` from the dependencies. -That said the serde support is contained in the `serde_impl` feature which is part of the default feature set of `simd-json`, but it can be disabled. +### `swar-number-parsing` (default) +Enables a parsing method that will parse 8 digits at a time for floats. This is a common pattern but comes at a slight +performance hit if most of the float have less than 8 digits. ### `known-key` -The `known-key` feature changes the hash mechanism for the DOM representation of the underlying JSON object, from `ahash` to `fxhash`. The `ahash` hasher is faster at hashing and provides protection against DOS attacks by forcing multiple keys into a single hashing bucket. The `fxhash` hasher, on the other hand allows for repeatable hashing results, which in turn allows memoizing hashes for well known keys and saving time on lookups. In workloads that are heavy on accessing some well-known keys, this can be a performance advantage. +The `known-key` feature changes the hash mechanism for the DOM representation of the underlying JSON object from +`ahash` to `fxhash`. The `ahash` hasher is faster at hashing and provides protection against DOS attacks by forcing +multiple keys into a single hashing bucket. The `fxhash` hasher allows for repeatable hashing results, +which in turn allows memoizing hashes for well known keys and saving time on lookups. In workloads that are heavy on +accessing some well-known keys, this can be a performance advantage. The `known-key` feature is optional and disabled by default and should be explicitly configured. ### `value-no-dup-keys` - **This flag has no effect on simd-json itself but purely affects the `Value` structs.** -The `value-no-dup-keys` feature flag toggles stricter behavior for objects when deserializing into a `Value`. When enabled, the Value deserializer will remove duplicate keys in a JSON object and only keep the last one. If not set duplicate keys are considered undefined behavior and Value will not make guarantees on it's behavior. +The `value-no-dup-keys` feature flag enables stricter behavior for objects when deserializing into a `Value`. When +enabled, the Value deserializer will remove duplicate keys in a JSON object and only keep the last one. If not set +duplicate keys are considered undefined behavior and Value will not make guarantees on its behavior. ### `big-int-as-float` -The `big-int-as-float` feature flag treats very large integers that won't fit into u64 as f64 floats. This prevents parsing errors if the JSON you are parsing contains very large numbers. Keep in mind that f64 loses some precision when representing very large numbers. +The `big-int-as-float` feature flag treats very large integers that won't fit into u64 as f64 floats. This prevents +parsing errors if the JSON you are parsing contains very large integers. Keep in mind that f64 loses some precision when +representing very large numbers. -## safety +### `128bit` -`simd-json` uses **a lot** of unsafe code. +Add support for parsing and serializing 128-bit integers. This feature is disabled by default because such large numbers +are rare in the wild and adding the support incurs a performance penalty. -There are a few reasons for this: +### `beef` -* SIMD intrinsics are inherently unsafe. These uses of unsafe are inescapable in a library such as `simd-json`. -* We work around some performance bottlenecks imposed by safe rust. These are avoidable, but at a performance cost. This is a more considered path in `simd-json`. +**Enabling this feature can break dependencies in your dependency tree that are using `simd-json`.** +Replace [`std::borrow::Cow`](https://doc.rust-lang.org/std/borrow/enum.Cow.html) with +[`beef::lean::Cow`][beef] This feature is disabled by default, because +it is a breaking change in the API. -`simd-json` goes through extra scrutiny for unsafe code. These steps are: +### `portable` -* Unit tests - to test 'the obvious' cases, edge cases, and regression cases -* Structural constructive property based testing - We generate random valid JSON objects to exercise the full `simd-json` codebase stochastically. Floats are currently excluded since slightly different parsing algorithms lead to slightly different results here. In short "is simd-json correct". -* Data-oriented property-based testing of string-like data - to assert that sequences of legal printable characters don't panic or crash the parser (they might and often error so - they are not valid JSON!) -* Destructive Property based testing - make sure that no illegal byte sequences crash the parser in any way -* Fuzzing - fuzz based on upstream & jsonorg simd pass/fail cases -* Miri testing for UB +**Currently disabled** -This doesn't ensure complete safety nor is at a bulletproof guarantee, but it does go a long way -to assert that the library is of high production quality and fit for purpose for practical industrial applications. +An highly experimental implementation of the algorithm using `std::simd` and up to 512 byte wide registers. + + +## Usage + +simd-json offers two main entry points for usage: + +### Values API + +The values API is a set of optimized DOM objects that allow parsed +json to JSON data that has no known variable structure. simd-lite +has two versions of this: + +**Borrowed Values** + +```rust +use simd_json; +let mut d = br#"{"some": ["key", "value", 2]}"#.to_vec(); +let v: simd_json::BorrowedValue = simd_json::to_borrowed_value(&mut d).unwrap(); +``` + +**Owned Values** + +```rust +use simd_json; +let mut d = br#"{"some": ["key", "value", 2]}"#.to_vec(); +let v: simd_json::OwnedValue = simd_json::to_owned_value(&mut d).unwrap(); +``` + +### Serde Compatible API + +```rust ignore +use simd_json; +use serde_json::Value; + +let mut d = br#"{"some": ["key", "value", 2]}"#.to_vec(); +let v: Value = simd_json::serde::from_slice(&mut d).unwrap(); +``` ## Other interesting things @@ -102,17 +183,19 @@ There are also bindings for upstream `simdjson` available [here](https://github. simd-json itself is licensed under either of -* Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0) -* MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT) +* [Apache License, Version 2.0, (LICENSE-APACHE)](http://www.apache.org/licenses/LICENSE-2.0) +* [MIT license (LICENSE-MIT)](http://opensource.org/licenses/MIT) + at your option. -However it ports a lot of code from [simdjson](https://github.com/lemire/simdjson) so their work and copyright on that should be respected along side. +However it ports a lot of code from [simdjson](https://github.com/lemire/simdjson) so their work and copyright on that should also be respected. -The [serde][1] integration is based on their example and `serde-json` so again, their copyright should as well be respected. +The [Serde][serde] integration is based on `serde-json` so their copyright should as well be respected. -[1]: https://serde.rs +[serde]: https://serde.rs +[beef]: https://docs.rs/beef/latest/beef/lean/type.Cow.html ### All Thanks To Our Contributors: - + GitHub profile pictures of all contributors to simd-json diff --git a/src/cow.rs b/src/cow.rs index 0a47b1e7..712711e1 100644 --- a/src/cow.rs +++ b/src/cow.rs @@ -1,5 +1,9 @@ -//! Reexport of Cow - +//! Re-export of Cow +//! +//! If feature `beef` is enabled, this will re-export [`beef::lean::Cow`][beef]. +//! Otherwise, it will re-export [`std::borrow::Cow`]. +//! +//! [beef]: https://docs.rs/beef/latest/beef/lean/type.Cow.html #[cfg(not(feature = "beef"))] pub use std::borrow::Cow; diff --git a/src/lib.rs b/src/lib.rs index 75e7faf9..f00639f6 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -10,109 +10,7 @@ missing_docs )] #![allow(clippy::module_name_repetitions, renamed_and_removed_lints)] - -//! simd-json is a rust port of the simdjson c++ library. It follows -//! most of the design closely with a few exceptions to make it better -//! fit into the rust ecosystem. -//! -//! Note: On `x86` it will select the best SIMD featureset -//! (`avx2`, or `sse4.2`) during runtime. If `simd-json` is compiled -//! with SIMD support, it will disable runtime detection. -//! -//! ## Goals -//! -//! the goal of the rust port of simdjson is not to create a one to -//! one copy, but to integrate the principles of the c++ library into -//! a rust library that plays well with the rust ecosystem. As such -//! we provide both compatibility with serde as well as parsing to a -//! dom to manipulate data. -//! -//! ## Performance -//! -//! As a rule of thumb this library tries to get as close as possible -//! to the performance of the c++ implementation, but some of the -//! design decisions - such as parsing to a dom or a tape, weigh -//! ergonomics over performance. In other places Rust makes it harder -//! to achieve the same level of performance. -//! -//! ## Safety -//! -//! this library uses unsafe all over the place, and while it leverages -//! quite a few test cases along with property based testing, please use -//! this library with caution. -//! -//! -//! ## Features -//! -//! simd-json.rs comes with a number of features that can be toggled, -//! the following features are intended for 'user' selection. Additional -//! features in the `Cargo.toml` exist to work around cargo limitations. -//! -//! ### `swar-number-parsing` (default) -//! -//! Enables a parsing method that will parse 8 digits at a time for -//! floats - this is a common pattern but comes as a slight perf hit -//! if all the floats have less then 8 digits. -//! -//! ### `serde_impl` (default) -//! -//! Compatibility with [serde](https://serde.rs/). This allows to use -//! [simd-json.rs](https://simd-json.rs) to deserialize serde objects -//! as well as serde compatibility of the different Value types. -//! This can be disabled if serde is not used alongside simd-json. -//! -//! ### `128bit` -//! -//! Support for signed and unsigned 128 bit integer. This feature -//! is disabled by default as 128 bit integers are rare in the wild -//! and parsing them comes as a performance penalty due to extra logic -//! and a changed memory layout. -//! -//! ### `known-key` -//! -//! The known-key feature changes hasher for the objects, from ahash -//! to fxhash, ahash is faster at hashing and provides protection -//! against DOS attacks by forcing multiple keys into a single hashing -//! bucket. fxhash on the other hand allows for repeatable hashing -//! results, that allows memorizing hashes for well know keys and saving -//! time on lookups. In workloads that are heavy at accessing some well -//! known keys this can be a performance advantage. -//! -//! ## Usage -//! -//! simd-json offers two main entry points for usage: -//! -//! ### Values API -//! -//! The values API is a set of optimized DOM objects that allow parsed -//! json to JSON data that has no known variable structure. simd-lite -//! has two versions of this: -//! -//! **Borrowed Values** -//! -//! ``` -//! use simd_json; -//! let mut d = br#"{"some": ["key", "value", 2]}"#.to_vec(); -//! let v: simd_json::BorrowedValue = simd_json::to_borrowed_value(&mut d).unwrap(); -//! ``` -//! -//! **Owned Values** -//! -//! ``` -//! use simd_json; -//! let mut d = br#"{"some": ["key", "value", 2]}"#.to_vec(); -//! let v: simd_json::OwnedValue = simd_json::to_owned_value(&mut d).unwrap(); -//! ``` -//! -//! ### Serde Compatible API -//! -//! ```ignore -//! use simd_json; -//! use serde_json::Value; -//! -//! let mut d = br#"{"some": ["key", "value", 2]}"#.to_vec(); -//! let v: Value = simd_json::serde::from_slice(&mut d).unwrap(); -//! ``` +#![doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/README.md"))] #[cfg(feature = "serde_impl")] extern crate serde as serde_ext; @@ -144,7 +42,7 @@ use stage2::StackState; mod impls; -/// Reexport of Cow +/// Re-export of Cow pub mod cow; /// The maximum padding size required by any SIMD implementation diff --git a/src/macros.rs b/src/macros.rs index 17018489..55d71aae 100644 --- a/src/macros.rs +++ b/src/macros.rs @@ -1,6 +1,7 @@ -/// Taken from: /// Construct a `simd_json::Value` from a JSON literal. /// +/// Taken from: +/// /// ```edition2018 /// # use simd_json::json; /// # @@ -87,10 +88,10 @@ macro_rules! json { }; } -/// Adapted from: /// Constructs a `simd_json::Value` from a JSON literal and allows specifying whether it generates /// an owned or borrowed variant. /// +/// Adapted from: /// /// Create an owned value of the form: /// @@ -1298,6 +1299,8 @@ macro_rules! static_cast_u64 { }; } +/// Custom `try!` macro that does no `From` conversions +/// /// FROM serde-json /// We only use our own error type; no need for From conversions provided by the /// standard library's try! macro. This reduces lines of LLVM IR by 4%. From 0e8574aadaf3fc8b6ee71167cfbf851b47749757 Mon Sep 17 00:00:00 2001 From: Christiaan Biesterbosch Date: Mon, 9 Sep 2024 15:01:04 +0200 Subject: [PATCH 2/2] Add a example using the tape API and fix some more doc stuff --- README.md | 20 ++++++++++++++++++-- src/prelude.rs | 2 +- src/value.rs | 26 ++++++++++++++------------ src/value/borrowed.rs | 10 ++++++---- src/value/lazy.rs | 7 ++++--- src/value/owned.rs | 10 ++++++---- 6 files changed, 49 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index a3e4bdf9..1cf1668e 100644 --- a/README.md +++ b/README.md @@ -141,12 +141,12 @@ An highly experimental implementation of the algorithm using `std::simd` and up ## Usage -simd-json offers two main entry points for usage: +simd-json offers three main entry points for usage: ### Values API The values API is a set of optimized DOM objects that allow parsed -json to JSON data that has no known variable structure. simd-lite +JSON to JSON data that has no known variable structure. `simd-json` has two versions of this: **Borrowed Values** @@ -175,6 +175,22 @@ let mut d = br#"{"some": ["key", "value", 2]}"#.to_vec(); let v: Value = simd_json::serde::from_slice(&mut d).unwrap(); ``` +### Tape API + +```rust +use simd_json; + +let mut d = br#"{"the_answer": 42}"#.to_vec(); +let tape = simd_json::to_tape(&mut d).unwrap(); +let value = tape.as_value(); +// try_get treats value like an object, returns Ok(Some(_)) because the key is found +assert!(value.try_get("the_answer").unwrap().unwrap() == 42); +// returns Ok(None) because the key is not found but value is an object +assert!(value.try_get("does_not_exist").unwrap() == None); +// try_get_idx treats value like an array, returns Err(_) because value is not an array +assert!(value.try_get_idx(0).is_err()); +``` + ## Other interesting things There are also bindings for upstream `simdjson` available [here](https://github.com/SunDoge/simdjson-rust) diff --git a/src/prelude.rs b/src/prelude.rs index 77d8a9bb..d3e1fd47 100644 --- a/src/prelude.rs +++ b/src/prelude.rs @@ -1,2 +1,2 @@ -/// Prelude to include needed traits +// Prelude to include needed traits pub use value_trait::prelude::*; diff --git a/src/value.rs b/src/value.rs index 003ad621..823ba1fc 100644 --- a/src/value.rs +++ b/src/value.rs @@ -1,14 +1,15 @@ -/// This module holds the two dom implementations we use. We distinguish between -/// owned and borrowed. The difference being is that the borrowed value will -/// use `&str` as its string type, referencing the input, while owned will -/// allocate a new String for each value. +/// This module holds the two dom implementations we use. /// -/// Note that since json strings allow for for escape sequences the borrowed +/// We distinguish between owned and borrowed. The difference being is that +/// the borrowed value will use `&str` as its string type, referencing the input, +/// while owned will allocate a new String for each value. +/// +/// Note that since JSON strings allow for escape sequences the borrowed /// value does not implement zero copy parsing, it does however not allocate /// new memory for strings. /// -/// This differs notably from serde's zero copy implementation as, unlike serde, -/// we do not require prior knowledge about string content to to take advantage +/// This differs notably from Serde's zero copy implementation as, unlike Serde, +/// we do not require prior knowledge about string content to take advantage /// of it. /// /// ## Usage @@ -57,7 +58,6 @@ pub mod owned; /// Tape implementation pub mod tape; -/// A value that starts out as a tape and upgraes to a borrowed value when mutation is needed pub mod lazy; pub use self::borrowed::{ @@ -82,8 +82,9 @@ pub type ObjectHasher = crate::known_key::NotSoRandomState; #[cfg(not(feature = "known-key"))] pub type ObjectHasher = halfbrown::DefaultHashBuilder; -/// Parses a slice of bytes into a Value dom. This function will -/// rewrite the slice to de-escape strings. +/// Parses a slice of bytes into a Value dom. +/// +/// This function will rewrite the slice to de-escape strings. /// As we reference parts of the input slice the resulting dom /// has the same lifetime as the slice it was created from. /// @@ -101,8 +102,9 @@ where } } -/// Parses a slice of bytes into a Value dom. This function will -/// rewrite the slice to de-escape strings. +/// Parses a slice of bytes into a Value dom. +/// +/// This function will rewrite the slice to de-escape strings. /// As we reference parts of the input slice the resulting dom /// has the same lifetime as the slice it was created from. /// diff --git a/src/value/borrowed.rs b/src/value/borrowed.rs index 7f9e5ee4..b518637b 100644 --- a/src/value/borrowed.rs +++ b/src/value/borrowed.rs @@ -37,8 +37,9 @@ pub type Object<'value> = HashMap, Value<'value>, ObjectHasher> /// Representation of a JSON array pub type Array<'value> = Vec>; -/// Parses a slice of bytes into a Value dom. This function will -/// rewrite the slice to de-escape strings. +/// Parses a slice of bytes into a Value dom. +/// +/// This function will rewrite the slice to de-escape strings. /// As we reference parts of the input slice the resulting dom /// has the same lifetime as the slice it was created from. /// @@ -52,8 +53,9 @@ pub fn to_value(s: &mut [u8]) -> Result { } } -/// Parses a slice of bytes into a Value dom. This function will -/// rewrite the slice to de-escape strings. +/// Parses a slice of bytes into a Value dom. +/// +/// This function will rewrite the slice to de-escape strings. /// As we reference parts of the input slice the resulting dom /// has the same lifetime as the slice it was created from. /// diff --git a/src/value/lazy.rs b/src/value/lazy.rs index b2971df2..579bc1ca 100644 --- a/src/value/lazy.rs +++ b/src/value/lazy.rs @@ -1,6 +1,7 @@ -//! Lazy value, this gets initialized with a tape and as long as only non mutating operations are performed -//! it will stay a tape. If it is mutated it is upgtaded to a borrowed value. -//! This allows for a very cheap parsin and data access while still maintaining mutability. +//! Lazy value, uses a tape until mutated. +//! +//! If it is mutated it is upgraded to a borrowed value. +//! This allows for cheap parsing and data access while still maintaining mutability. //! //! # Example //! diff --git a/src/value/owned.rs b/src/value/owned.rs index c7d6e81f..f9c51cb1 100644 --- a/src/value/owned.rs +++ b/src/value/owned.rs @@ -33,8 +33,9 @@ use std::ops::{Index, IndexMut}; /// Representation of a JSON object pub type Object = HashMap; -/// Parses a slice of bytes into a Value dom. This function will -/// rewrite the slice to de-escape strings. +/// Parses a slice of bytes into a Value dom. +/// +/// This function will rewrite the slice to de-escape strings. /// We do not keep any references to the raw data but re-allocate /// owned memory wherever required thus returning a value without /// a lifetime. @@ -49,8 +50,9 @@ pub fn to_value(s: &mut [u8]) -> Result { } } -/// Parses a slice of bytes into a Value dom. This function will -/// rewrite the slice to de-escape strings. +/// Parses a slice of bytes into a Value dom. +/// +/// This function will rewrite the slice to de-escape strings. /// We do not keep any references to the raw data but re-allocate /// owned memory wherever required thus returning a value without /// a lifetime.