update api

README.md

@@ -20,22 +20,70 @@ Add this to your `Cargo.toml`
 
 ```toml
 # In the `[dependencies]` section
-simdjson-rust = {git = "https://github.com/SunDoge/simdjson-rust"}
+simdjson-rust = "0.3.0"
 ```
 
 Then, get started.
 
 ```rust
-use simdjson_rust::{ondemand::Parser, prelude::*};
+use simdjson_rust::prelude::*;
+use simdjson_rust::{dom, ondemand};
 
 fn main() -> simdjson_rust::Result<()> {
-    let mut parser = Parser::default();
     let ps = make_padded_string("[0,1,2,3]");
-    let mut doc = parser.iterate(&ps)?;
-    let mut array = doc.get_array()?;
-    for (index, value) in array.iter()?.enumerate() {
-        assert_eq!(index as u64, value?.get_uint64()?);
+
+    // ondemand api.
+    {
+        let mut parser = ondemand::Parser::default();
+        let mut doc = parser.iterate(&ps)?;
+        let mut array = doc.get_array()?;
+        for (index, value) in array.iter()?.enumerate() {
+            assert_eq!(index as u64, value?.get_uint64()?);
+        }
+    }
+
+    // dom api.
+    {
+        let mut parser = dom::Parser::default();
+        let elem = parser.parse(&ps)?;
+        let arr = elem.get_array()?;
+        for (index, value) in arr.iter().enumerate() {
+            assert_eq!(index as u64, value.get_uint64()?);
+        }
     }
+
+    Ok(())
+}
+```
+
+### `dom` and `ondemand` 
+
+`simdjson` now offer two kinds of API, `dom` and `ondemand`.
+`dom` will parsed the whole string while `ondemand` only parse what you request.
+Due to `ffi`, the overhead of `ondemand` API is relatively high. I have tested `lto` but it only improves a little :(
+
+Thus it is suggestted that
+
+- use `ondemand` if you only want to access a specific part of a large json,
+- use `dom` if you want to parse the whole json.
+
+
+### `padded_string`
+
+`simdjson` requires the input string to be padded. We must provide a string with `capacity = len + SIMDJSON_PADDING`.
+We provide utils to do so.
+
+```rust
+use simdjson_rust::prelude::*;
+
+fn main() -> simdjson_rust::Result<()> {
+    let ps = make_padded_string("[0,1,2,3]");
+    let ps = "[0,1,2,3]".to_padded_string();
+    // or reuse a buffer.
+    let unpadded = String::from("[1,2,3,4]");
+    let ps = unpadded.into_padded_string();
+    // or load from file.
+    let ps = load_padded_string("test.json")?;
     Ok(())
 }
 ```

examples/simple.rs

@@ -1,19 +1,27 @@
 use simdjson_rust::prelude::*;
+use simdjson_rust::{dom, ondemand};
 
 fn main() -> simdjson_rust::Result<()> {
-    let mut parser = ondemand::Parser::default();
     let ps = make_padded_string("[0,1,2,3]");
-    let mut doc = parser.iterate(&ps)?;
-    let mut array = doc.get_array()?;
-    for (index, value) in array.iter()?.enumerate() {
-        assert_eq!(index as u64, value?.get_uint64()?);
+
+    // ondemand api.
+    {
+        let mut parser = ondemand::Parser::default();
+        let mut doc = parser.iterate(&ps)?;
+        let mut array = doc.get_array()?;
+        for (index, value) in array.iter()?.enumerate() {
+            assert_eq!(index as u64, value?.get_uint64()?);
+        }
     }
 
-    let mut dom_parser = simdjson_rust::dom::Parser::default();
-    let elem = dom_parser.parse(&ps)?;
-    let arr = elem.get_array()?;
-    for (index, value) in arr.iter().enumerate() {
-        assert_eq!(index as u64, value.get_uint64()?);
+    // dom api.
+    {
+        let mut parser = dom::Parser::default();
+        let elem = parser.parse(&ps)?;
+        let arr = elem.get_array()?;
+        for (index, value) in arr.iter().enumerate() {
+            assert_eq!(index as u64, value.get_uint64()?);
+        }
     }
 
     Ok(())

src/dom/mod.rs

@@ -5,7 +5,9 @@ mod element;
 mod object;
 mod parser;
 
-pub use array::Array;
+pub use array::{Array, ArrayIter};
+pub use document::Document;
+pub use document_stream::{DocumentStream, DocumentStreamIter};
 pub use element::{Element, ElementType};
-pub use object::Object;
+pub use object::{Object, ObjectIter};
 pub use parser::Parser;

src/dom/parser.rs

@@ -34,11 +34,11 @@ impl Parser {
         .map(Element::new)
     }
 
-    pub fn parse_into_document(
-        &mut self,
-        doc: &mut Document,
+    pub fn parse_into_document<'d>(
+        &self,
+        doc: &'d mut Document,
         padded_string: &String,
-    ) -> Result<Element> {
+    ) -> Result<Element<'d>> {
         map_ptr_result!(ffi::SJ_DOM_parser_parse_into_document(
             self.ptr.as_ptr(),
             doc.as_ptr(),
@@ -68,3 +68,34 @@ impl Parser {
 }
 
 impl_drop!(Parser, ffi::SJ_DOM_parser_free);
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::prelude::*;
+
+    #[test]
+    fn parse() {
+        let ps = "1".to_padded_string();
+        let mut parser = Parser::default();
+        let elem = parser.parse(&ps).unwrap();
+        assert_eq!(elem.get_uint64().unwrap(), 1);
+    }
+
+    #[test]
+    fn parse_into_document() {
+        let ps = "[1,2,3]".to_padded_string();
+        let parser = Parser::default();
+        let mut doc = Document::new();
+        let elem = parser.parse_into_document(&mut doc, &ps).unwrap();
+        assert_eq!(
+            elem.get_array()
+                .unwrap()
+                .at(0)
+                .unwrap()
+                .get_uint64()
+                .unwrap(),
+            1
+        );
+    }
+}

src/ondemand/document.rs

@@ -150,6 +150,7 @@ impl_drop!(Document<'p, 's>, ffi::SJ_OD_document_free);
 
 #[cfg(test)]
 mod tests {
+    use crate::ondemand;
     use crate::prelude::*;
 
     #[test]

src/prelude.rs

@@ -1,4 +1,3 @@
-pub use crate::{
-    ondemand,
-    padded_string::{load_padded_string, make_padded_string, IntoPaddedString, ToPaddedString},
+pub use crate::padded_string::{
+    load_padded_string, make_padded_string, IntoPaddedString, ToPaddedString,
 };