From 968b7860d7263a283f87f104d14109cff33c371a Mon Sep 17 00:00:00 2001 From: Jonathan Johnson Date: Mon, 23 Jan 2023 11:49:14 -0800 Subject: [PATCH] Adding no-std to readme, added HeaplessDocument --- .rustme/config.ron | 14 ++++++++++++-- .rustme/docs.md | 24 ++++++++++++++++++++++++ README.md | 26 +++++++++++++++++++++++++- examples/heapless.rs | 15 +++++++++------ src/.crate-docs.md | 24 ++++++++++++++++++++++++ src/doc.rs | 4 ++++ 6 files changed, 98 insertions(+), 9 deletions(-) diff --git a/.rustme/config.ron b/.rustme/config.ron index 858d4b0..4da0645 100644 --- a/.rustme/config.ron +++ b/.rustme/config.ron @@ -51,10 +51,20 @@ Configuration( for_docs: "crate::JsonNumber", ), "document": ( - default: "https://khonsulabs.github.io/justjson/main/justjson/doc/struct.Document.html", - release: "https://docs.rs/justjson/*/justjson/doc/struct.Document.html", + default: "https://khonsulabs.github.io/justjson/main/justjson/doc/type.Document.html", + release: "https://docs.rs/justjson/*/justjson/doc/type.Document.html", for_docs: "crate::doc::Document", ), + "heapless-document": ( + default: "https://khonsulabs.github.io/justjson/main/justjson/doc/type.HeaplessDocument.html", + release: "https://docs.rs/justjson/*/justjson/doc/type.HeaplessDocument.html", + for_docs: "crate::doc::HeaplessDocument", + ), + "generic-document": ( + default: "https://khonsulabs.github.io/justjson/main/justjson/doc/struct.GenericDocument.html", + release: "https://docs.rs/justjson/*/justjson/doc/struct.GenericDocument.html", + for_docs: "crate::doc::GenericDocument", + ) } ], ) \ No newline at end of file diff --git a/.rustme/docs.md b/.rustme/docs.md index 15c71a7..6c102b2 100644 --- a/.rustme/docs.md +++ b/.rustme/docs.md @@ -95,12 +95,36 @@ This crate uses unsafe code only when converting from raw incoming data to UTF-8 data. The parser fully verifies that the data is valid UTF-8 before these functions are used. +## `no_std` support + +By default, this crate enables the `std` feature, which adds support for Rust's +standard library types. By disabling default features, this crate can be used in +`no_std` projects. For example, in your Cargo.toml: + +```toml +[dependencies] +justjson = { version = "*", default-features = false } +``` + +The [`Value`][value] type requires the `alloc` feature to be enabled. + +The [`Document`][document] type alias requires the `alloc` feature, but the +[`GenericDocument`][generic-doc] type allows providing your own collection type. + +With the `heapless` feature enabled, the [`HeaplessDocument`][heapless-doc] type +can be used to parse documents using the [heapless][heapless] crate's `Vec` type +for storage. This enables parsing JSON in environments where the `alloc` crate +isn't supported. + [value]: $value$ [string]: $string$ [number]: $number$ [document]: $document$ +[generic-doc]: $generic-document$ +[heapless-doc]: $heapless-document$ [json-ld]: https://www.w3.org/TR/json-ld11/#compacted-document-form [fediverse]: https://en.wikipedia.org/wiki/Fediverse [activitypub]: https://www.w3.org/TR/activitypub/ [simd-json]: https://github.com/simd-lite/simd-json [serde-json]: https://github.com/serde-rs/json +[heapless]: https://github.com/japaric/heapless diff --git a/README.md b/README.md index b145fec..bd76c5b 100644 --- a/README.md +++ b/README.md @@ -97,15 +97,39 @@ This crate uses unsafe code only when converting from raw incoming data to UTF-8 data. The parser fully verifies that the data is valid UTF-8 before these functions are used. +## `no_std` support + +By default, this crate enables the `std` feature, which adds support for Rust's +standard library types. By disabling default features, this crate can be used in +`no_std` projects. For example, in your Cargo.toml: + +```toml +[dependencies] +justjson = { version = "*", default-features = false } +``` + +The [`Value`][value] type requires the `alloc` feature to be enabled. + +The [`Document`][document] type alias requires the `alloc` feature, but the +[`GenericDocument`][generic-doc] type allows providing your own collection type. + +With the `heapless` feature enabled, the [`HeaplessDocument`][heapless-doc] type +can be used to parse documents using the [heapless][heapless] crate's `Vec` type +for storage. This enables parsing JSON in environments where the `alloc` crate +isn't supported. + [value]: https://khonsulabs.github.io/justjson/main/justjson/enum.Value.html [string]: https://khonsulabs.github.io/justjson/main/justjson/struct.JsonString.html [number]: https://khonsulabs.github.io/justjson/main/justjson/struct.JsonNumber.html -[document]: https://khonsulabs.github.io/justjson/main/justjson/doc/struct.Document.html +[document]: https://khonsulabs.github.io/justjson/main/justjson/doc/type.Document.html +[generic-doc]: https://khonsulabs.github.io/justjson/main/justjson/doc/struct.GenericDocument.html +[heapless-doc]: https://khonsulabs.github.io/justjson/main/justjson/doc/type.HeaplessDocument.html [json-ld]: https://www.w3.org/TR/json-ld11/#compacted-document-form [fediverse]: https://en.wikipedia.org/wiki/Fediverse [activitypub]: https://www.w3.org/TR/activitypub/ [simd-json]: https://github.com/simd-lite/simd-json [serde-json]: https://github.com/serde-rs/json +[heapless]: https://github.com/japaric/heapless ## Open-source Licenses diff --git a/examples/heapless.rs b/examples/heapless.rs index 8962979..7673bf3 100644 --- a/examples/heapless.rs +++ b/examples/heapless.rs @@ -1,11 +1,10 @@ -use heapless::Vec; -use justjson::doc::{GenericDocument, Node}; +use justjson::doc::{HeaplessDocument, Node}; use justjson::{ErrorKind, JsonString}; fn main() { // Using a heapless vec, we can parse directly to the stack. - let doc: GenericDocument, 3>> = - GenericDocument::from_json(r#"{"hello": "world"}"#).expect("invalid json"); + let doc: HeaplessDocument<'_, 3> = + HeaplessDocument::from_json(r#"{"hello": "world"}"#).expect("invalid json"); let mut nodes = doc.into_iter(); assert_eq!(nodes.next(), Some(Node::Object { length: 1 })); assert_eq!(nodes.next(), Some(Node::String(JsonString::from("hello")))); @@ -13,7 +12,11 @@ fn main() { // When parsing a document too large for the heapless Vec, an error will be // returned instead of panicing. - let error = GenericDocument::, 3>>::from_json("[1, 2, 3, 4]") - .expect_err("shouldn't have space"); + let error = HeaplessDocument::<3>::from_json("[1, 2, 3, 4]").expect_err("shouldn't have space"); assert_eq!(error.kind(), &ErrorKind::PaylodTooLarge); } + +#[test] +fn runs() { + main(); +} diff --git a/src/.crate-docs.md b/src/.crate-docs.md index be477e4..cbfadc4 100644 --- a/src/.crate-docs.md +++ b/src/.crate-docs.md @@ -95,12 +95,36 @@ This crate uses unsafe code only when converting from raw incoming data to UTF-8 data. The parser fully verifies that the data is valid UTF-8 before these functions are used. +## `no_std` support + +By default, this crate enables the `std` feature, which adds support for Rust's +standard library types. By disabling default features, this crate can be used in +`no_std` projects. For example, in your Cargo.toml: + +```toml +[dependencies] +justjson = { version = "*", default-features = false } +``` + +The [`Value`][value] type requires the `alloc` feature to be enabled. + +The [`Document`][document] type alias requires the `alloc` feature, but the +[`GenericDocument`][generic-doc] type allows providing your own collection type. + +With the `heapless` feature enabled, the [`HeaplessDocument`][heapless-doc] type +can be used to parse documents using the [heapless][heapless] crate's `Vec` type +for storage. This enables parsing JSON in environments where the `alloc` crate +isn't supported. + [value]: crate::Value [string]: crate::JsonString [number]: crate::JsonNumber [document]: crate::doc::Document +[generic-doc]: crate::doc::GenericDocument +[heapless-doc]: crate::doc::HeaplessDocument [json-ld]: https://www.w3.org/TR/json-ld11/#compacted-document-form [fediverse]: https://en.wikipedia.org/wiki/Fediverse [activitypub]: https://www.w3.org/TR/activitypub/ [simd-json]: https://github.com/simd-lite/simd-json [serde-json]: https://github.com/serde-rs/json +[heapless]: https://github.com/japaric/heapless diff --git a/src/doc.rs b/src/doc.rs index a658e76..acfd9ea 100644 --- a/src/doc.rs +++ b/src/doc.rs @@ -477,3 +477,7 @@ impl<'a, const N: usize> NodeCollection<'a> for heapless::Vec, N> { /// `std`/`alloc`. #[cfg(feature = "alloc")] pub type Document<'a> = GenericDocument<'a, Vec>>; + +/// A convenience alias for a [`GenericDocument`] that uses a `heapless::Vec`. +#[cfg(feature = "heapless")] +pub type HeaplessDocument<'a, const N: usize> = GenericDocument<'a, heapless::Vec, N>>;