hifijson

https://docs.rs/hifijson/0.5.0/hifijson/
Admin
hifijson is a high-fidelity JSON lexer and parser for Rust that provides modular building blocks to...
Tokens:6,371
Snippets:91
Trust Score:9.1
Update:1 month ago
Show doc for...
Tokens:
Raw
### Initialize IterLexer from Read

Source: https://docs.rs/hifijson/0.5.0/hifijson/struct.IterLexer.html

Example of creating an IterLexer instance from a standard input reader's byte iterator.

```rust
use std::io::Read;
let read = std::io::stdin();
let lexer = hifijson::IterLexer::new(read.bytes());
```

--------------------------------

### Using Write Trait with Lexers

Source: https://docs.rs/hifijson/0.5.0/hifijson/trait.Write.html

Example demonstrating how to use the write_until method with SliceLexer and IterLexer to capture input bytes.

```rust
fn test<L: hifijson::Write>(lexer: &mut L) {
    let mut bytes = L::Bytes::default();
    lexer.write_until(&mut bytes, |c| c == b' ');
    assert_eq!(bytes.as_ref(), b"Hello");
    lexer.write_until(&mut bytes, |_| false);
    assert_eq!(bytes.as_ref(), b" World");
}
let s = b"Hello World";
test(&mut hifijson::SliceLexer::new(s));
test(&mut hifijson::IterLexer::new(s.iter().copied().map(Ok::<_, ()>)));
```

--------------------------------

### Display::new

Source: https://docs.rs/hifijson/0.5.0/hifijson/str/struct.Display.html

Creates a new Display wrapper for a string to be printed as a JSON string.

```APIDOC
## pub fn new(s: Str) -> Self

### Description
Creates a new string wrapper to be printed as a JSON string.

### Parameters
- **s** (Str) - The string-like object to be wrapped for JSON display.
```

--------------------------------

### Parse JSON from files and streams

Source: https://docs.rs/hifijson/0.5.0/hifijson/index.html

Shows how to process JSON input from either a file or standard input using the LexAlloc trait.

```rust
/// Parse a single JSON value and print it.
///
/// Note that the `LexAlloc` trait indicates that this lexer allocates memory.
fn process<L: hifijson::LexAlloc>(mut lexer: L) {
    let value = lexer.exactly_one(L::ws_peek, hifijson::value::parse_unbounded);
    let value = value.expect("parse");
    println!("{}", value);
}

let filename = std::env::args().nth(1);
if let Some(filename) = filename {
    let file = std::fs::read(filename).expect("read file");
    process(hifijson::SliceLexer::new(&file))
} else {
    use std::io::Read;
    process(hifijson::IterLexer::new(std::io::stdin().bytes()))
}
```

--------------------------------

### SliceLexer::new

Source: https://docs.rs/hifijson/0.5.0/hifijson/struct.SliceLexer.html

Creates a new SliceLexer instance from a byte slice.

```APIDOC
## pub fn new(slice: &'a [u8]) -> Self

### Description
Creates a new slice lexer from the provided byte slice. A fast way to obtain the contents of a file as `&[u8]` is memory mapping.
```

--------------------------------

### str_foreach

Source: https://docs.rs/hifijson/0.5.0/hifijson/str/trait.Lex.html

Executes a provided closure for every character (byte) of the string.

```APIDOC
## fn str_foreach(&mut self, f: impl FnMut(u8)) -> Result<(), Error>

### Description
Run a function for every character of the string.
```

--------------------------------

### IterLexer::new

Source: https://docs.rs/hifijson/0.5.0/hifijson/struct.IterLexer.html

Creates a new instance of IterLexer from an iterator of bytes.

```APIDOC
## pub fn new(iter: I) -> Self

### Description
Creates a new iterator lexer from an iterator of bytes.

### Parameters
- **iter** (I) - Required - An iterator over Result<u8, E>.

### Example
```rust
use std::io::Read;
let read = std::io::stdin();
let lexer = hifijson::IterLexer::new(read.bytes());
```
```

--------------------------------

### Parse JSON strings to values

Source: https://docs.rs/hifijson/0.5.0/hifijson/index.html

Demonstrates creating a SliceLexer to parse a JSON string into a Value structure.

```rust
// our input JSON that we want to parse
let json = br#"[null, true, false, "hello", 0, 3.1415, [1, 2], {"x": 1, "y": 2}]"#;

// the lexer on our input -- just creating it does not actually run it yet
let mut lexer = hifijson::SliceLexer::new(json);

use hifijson::token::Lex;
// now we are going -- we try to
// obtain exactly one JSON value from the lexer and
// parse it to a value, allowing for arbitrarily deep (unbounded) nesting
let value = lexer.exactly_one(Lex::ws_peek, hifijson::value::parse_unbounded);
let value = value.expect("parse");

// yay, we got an array!
assert!(matches!(value, hifijson::value::Value::Array(_)));
assert_eq!(
    value.to_string(),
    // printing a value yields a compact representation with minimal spaces
    r#"[null,true,false,"hello",0,3.1415,[1,2],{"x":1,"y":2}]"#
);
```

--------------------------------

### Display struct definition

Source: https://docs.rs/hifijson/0.5.0/hifijson/str/struct.Display.html

The definition of the Display wrapper type.

```rust
pub struct Display<Str>(/* private fields */);
```

--------------------------------

### Define the Parts struct

Source: https://docs.rs/hifijson/0.5.0/hifijson/num/struct.Parts.html

The structure definition for tracking number components.

```rust
pub struct Parts {
    pub zero: bool,
    pub dot: bool,
    pub exp: bool,
}
```

--------------------------------

### Lit::try_from

Source: https://docs.rs/hifijson/0.5.0/hifijson/escape/enum.Lit.html

Attempts to interpret a given ASCII byte as the first character of an escape sequence, returning the corresponding Lit variant if valid.

```APIDOC
## pub fn try_from(c: u8) -> Option<Self>

### Description
Try to interpret an ASCII character as the first character of an escape sequence.

### Parameters
- **c** (u8) - Required - The ASCII byte to interpret.

### Returns
- **Option<Self>** - Returns Some(Lit) if the character corresponds to a valid escape sequence, otherwise None.
```

--------------------------------

### pub fn parse<L: Lex>(next: u8, lexer: &mut L) -> Result<(), Error>

Source: https://docs.rs/hifijson/0.5.0/hifijson/ignore/fn.parse.html

Parses and discards a value using the provided lexer.

```APIDOC
## pub fn parse<L: Lex>(next: u8, lexer: &mut L) -> Result<(), Error>

### Description
Parse and discard a value.

### Signature
`pub fn parse<L: Lex>(next: u8, lexer: &mut L) -> Result<(), Error>`

### Parameters
- **next** (u8) - The next byte to process.
- **lexer** (&mut L) - A mutable reference to the lexer implementing the Lex trait.

### Returns
- **Result<(), Error>** - Returns Ok(()) if the value was successfully parsed and discarded, or an Error if parsing failed.
```

--------------------------------

### Track Lexer Offset

Source: https://docs.rs/hifijson/0.5.0/hifijson/struct.SliceLexer.html

Use as_slice to calculate the number of bytes consumed by the lexer, useful for error reporting.

```rust
use hifijson::{token::Lex, value, Read};
let input = b"true false";
let mut lexer = hifijson::SliceLexer::new(input);
let parse = || Some(value::parse_unbounded(lexer.ws_peek()?, &mut lexer));
let mut vals = core::iter::from_fn(parse);

assert_eq!(vals.next(), Some(Ok(value::Value::Bool(true))));
let offset = lexer.as_slice().as_ptr() as usize - input.as_ptr() as usize;
assert_eq!(offset, 4);
```

--------------------------------

### LexAlloc Implementation for T

Source: https://docs.rs/hifijson/0.5.0/hifijson/trait.LexAlloc.html

Generic implementation of LexAlloc for types that satisfy LexWrite and LexAlloc bounds.

```rust
impl<T> LexAlloc for T
where T: LexWrite + LexAlloc,
```

--------------------------------

### Function signature for parse_bounded

Source: https://docs.rs/hifijson/0.5.0/hifijson/value/fn.parse_bounded.html

The function signature defines the required LexAlloc trait bound and parameters for depth, the next byte, and the lexer.

```rust
pub fn parse_bounded<L: LexAlloc>(
    depth: usize,
    next: u8,
    lexer: &mut L,
) -> Result<Value<L::Num, L::Str>, Error>
```

--------------------------------

### fn write_until

Source: https://docs.rs/hifijson/0.5.0/hifijson/trait.Write.html

Writes input to the provided bytes buffer until the stop function returns true. This method is useful for capturing segments of input without allocating new memory.

```APIDOC
## fn write_until(&mut self, bytes: &mut Self::Bytes, stop: impl FnMut(u8) -> bool)

### Description
Writes input to `bytes` until the `stop` predicate yields true. The `stop` function evaluates the current byte to determine when to cease writing.

### Parameters
- **bytes** (Self::Bytes) - The buffer to write the input into. Must implement AsRef<[u8]> and Default.
- **stop** (impl FnMut(u8) -> bool) - A closure that returns true when the writing process should stop.
```

--------------------------------

### Define the Expect enum

Source: https://docs.rs/hifijson/0.5.0/hifijson/token/enum.Expect.html

The structure of the Expect enum, listing all possible variants that represent expected tokens.

```rust
pub enum Expect {
    Value,
    ValueOrEnd,
    CommaOrEnd,
    String,
    Colon,
    Eof,
}
```

--------------------------------

### LexWrite Trait Implementation

Source: https://docs.rs/hifijson/0.5.0/hifijson/trait.LexWrite.html

Generic implementation of LexWrite for types that satisfy the Lex and LexWrite trait bounds.

```rust
impl<T> LexWrite for T
where T: Lex + LexWrite + LexWrite,
```

--------------------------------

### Read Trait Definition

Source: https://docs.rs/hifijson/0.5.0/hifijson/trait.Read.html

The core trait definition for low-level input operations in hifijson.

```rust
pub trait Read {
    // Required methods
    fn peek_next(&mut self) -> Option<u8>;
    fn take_next(&mut self) -> Option<u8>;

    // Provided methods
    fn strip_prefix(&mut self, s: &[u8]) -> bool { ... }
    fn foreach_until(&mut self, f: impl FnMut(u8), stop: impl FnMut(u8) -> bool) { ... }
    fn skip_until(&mut self, stop: impl FnMut(u8) -> bool) { ... }
}
```

--------------------------------

### str_ignore

Source: https://docs.rs/hifijson/0.5.0/hifijson/str/trait.Lex.html

Reads a string without saving it, useful for skipping content during parsing.

```APIDOC
## fn str_ignore(&mut self) -> Result<(), Error>

### Description
Read a string without saving it.
```

--------------------------------

### Define a SliceLexer

Source: https://docs.rs/hifijson/0.5.0/hifijson/struct.SliceLexer.html

Basic structure definition for the SliceLexer.

```rust
pub struct SliceLexer<'a> { /* private fields */ }
```

--------------------------------

### Re-exporting Expect

Source: https://docs.rs/hifijson

Exposes the Expect token type for external use.

```rust
pub use token::Expect;
```

--------------------------------

### LexWrite Trait Definition

Source: https://docs.rs/hifijson/0.5.0/hifijson/str/trait.LexWrite.html

The trait definition for LexWrite, requiring implementations of Lex, Read, and Write.

```rust
pub trait LexWrite:
    Lex
    + Read
    + Write {
    // Provided methods
    fn str_bytes(&mut self, bytes: &mut Self::Bytes) -> Result<(), Error> { ... }
    fn str_fold<E: From<Error>, T>(
        &mut self,
        out: T,
        on_string: impl Fn(&mut Self::Bytes, &mut T) -> Result<(), E>,
        on_escape: impl Fn(&mut Self, &mut T) -> Result<(), E>,
    ) -> Result<T, E> { ... }
}
```

--------------------------------

### LexWrite Trait Definition

Source: https://docs.rs/hifijson/0.5.0/hifijson/trait.LexWrite.html

The trait definition for LexWrite, requiring implementations of Lex and itself.

```rust
pub trait LexWrite:
    Lex
    + LexWrite
    + LexWrite { }
```

--------------------------------

### SliceLexer::as_slice

Source: https://docs.rs/hifijson/0.5.0/hifijson/struct.SliceLexer.html

Returns the remaining input as a subslice of the original data.

```APIDOC
## pub fn as_slice(&self) -> &'a [u8]

### Description
Return remaining input as a subslice of the original data. This can be used to obtain the number of bytes consumed, for example to find the location where an error occurred.
```

--------------------------------

### Write Trait Definition

Source: https://docs.rs/hifijson/0.5.0/hifijson/trait.Write.html

The core definition of the Write trait, requiring an associated Bytes type and the write_until method.

```rust
pub trait Write {
    type Bytes: AsRef<[u8]> + Default;

    // Required method
    fn write_until(
        &mut self,
        bytes: &mut Self::Bytes,
        stop: impl FnMut(u8) -> bool,
    );
}
```

--------------------------------

### Count JSON values with constant memory

Source: https://docs.rs/hifijson/0.5.0/hifijson/index.html

Operates directly on the lexer to count JSON values without allocating memory for the full structure.

```rust
use hifijson::{Error, Expect, Lex};

/// Recursively count the number of values in the value starting with the `next` character.
///
/// The `Lex` trait indicates that this lexer does *not* allocate memory.
fn count<L: Lex>(next: u8, lexer: &mut L) -> Result<usize, Error> {
    match next {
        // the JSON values "null", "true", and "false"
        b'a'..=b'z' => Ok(lexer.null_or_bool().map(|_| 1).ok_or(Expect::Value)?),
        b'0'..=b'9' | b'-' => Ok(lexer.num_ignore().validate().map(|_| 1)?),
        b'"' => Ok(lexer.discarded().str_ignore().map(|_| 1)?),

        // start of array
        b'[' => {
            // an array is a value itself, so start with 1
            let mut sum = 1;
            // perform the following for every item of the array
            lexer.discarded().seq(b']', L::ws_peek, |next, lexer| {
                sum += count(next, lexer)?;
                Ok::<_, Error>(())
            })?;
            Ok(sum)
        }

        // start of object
        b'{' => {
            let mut sum = 1;
            // perform the following for every key-value pair of the object
            lexer.discarded().seq(b'}', L::ws_peek, |next, lexer| {
                /// read the key, ignoring it, and then the ':' after it
                lexer.expect(|_| Some(next), b'"').ok_or(Expect::String)?;
                lexer.str_ignore().map_err(Error::Str)?;
                lexer.expect(L::ws_peek, b':').ok_or(Expect::Colon)?;

                /// peek the next non-whitespace character
                let next = lexer.ws_peek().ok_or(Expect::Value)?;
                sum += count(next, lexer)?;
                Ok::<_, Error>(())
            })?;
            Ok(sum)
        }
        _ => Err(Expect::Value)?,
    }
}

fn process<L: Lex>(mut lexer: L) -> Result<usize, Error> {
    lexer.exactly_one(L::ws_peek, count)
}

let json = br#"[null, true, false, "hello", 0, 3.1415, [1, 2], {"x": 1, "y": 2}]"#;
let mut lexer = hifijson::SliceLexer::new(json);
let n = process(lexer).unwrap();
assert_eq!(n, 13)
```

--------------------------------

### Lex Trait Definition

Source: https://docs.rs/hifijson/0.5.0/hifijson/token/trait.Lex.html

The core definition of the Lex trait, including its provided methods for token parsing.

```rust
pub trait Lex: Read {
    // Provided methods
    fn eat_whitespace(&mut self) { ... }
    fn ws_peek(&mut self) -> Option<u8> { ... }
    fn null_or_bool(&mut self) -> Option<Option<bool>> { ... }
    fn discarded(&mut self) -> &mut Self { ... }
    fn expect(
        &mut self,
        pf: impl FnOnce(&mut Self) -> Option<u8>,
        expect: u8,
    ) -> Option<()> { ... }
    fn seq<E: From<Expect>, PF, F>(
        &mut self,
        end: u8,
        pf: PF,
        f: F,
    ) -> Result<(), E>
       where PF: FnMut(&mut Self) -> Option<u8>,
             F: FnMut(u8, &mut Self) -> Result<(), E> { ... }
    fn exactly_one<T, E: From<Expect>, PF, F>(
        &mut self,
        pf: PF,
        f: F,
    ) -> Result<T, E>
       where PF: FnMut(&mut Self) -> Option<u8>,
             F: FnOnce(u8, &mut Self) -> Result<T, E> { ... }
}
```

--------------------------------

### LexAlloc Trait Definition

Source: https://docs.rs/hifijson/0.5.0/hifijson/trait.LexAlloc.html

The core definition of the LexAlloc trait requiring LexWrite and LexAlloc implementations.

```rust
pub trait LexAlloc: LexWrite + LexAlloc { }
```

--------------------------------

### Function signature for parse_unbounded

Source: https://docs.rs/hifijson/0.5.0/hifijson/value/fn.parse_unbounded.html

The function signature for parsing a value without recursion depth limits.

```rust
pub fn parse_unbounded<L: LexAlloc>(
    next: u8,
    lexer: &mut L,
) -> Result<Value<L::Num, L::Str>, Error>
```

--------------------------------

### parse

Source: https://docs.rs/hifijson/0.5.0/hifijson/ignore/index.html

Parses and discards a JSON value.

```APIDOC
## Function: parse

### Description
Parses and discards a value from the input stream.

### Signature
`pub fn parse<R>(reader: &mut R) -> Result<(), Error> where R: Read`
```

--------------------------------

### LexAlloc Trait Definition

Source: https://docs.rs/hifijson/0.5.0/hifijson/str/trait.LexAlloc.html

The trait definition for LexAlloc, which extends LexWrite and requires an associated Str type and the str_string method.

```rust
pub trait LexAlloc: LexWrite {
    type Str: AsRef<str>;

    // Required method
    fn str_string(&mut self) -> Result<Self::Str, Error>;
}
```

--------------------------------

### Lex Trait Implementation

Source: https://docs.rs/hifijson/0.5.0/hifijson/trait.Lex.html

Generic implementation of the Lex trait for types that satisfy the required trait bounds.

```rust
impl<T> Lex for T
where T: Lex + Lex + Lex,
```

--------------------------------

### Signature of the parse function

Source: https://docs.rs/hifijson/0.5.0/hifijson/ignore/fn.parse.html

The function signature for parsing and discarding a value using a lexer.

```rust
pub fn parse<L: Lex>(next: u8, lexer: &mut L) -> Result<(), Error>
```

--------------------------------

### LexWrite Trait Definition

Source: https://docs.rs/hifijson/0.5.0/hifijson/num/trait.LexWrite.html

The core trait definition for LexWrite, requiring an associated Num type and the implementation of num_string_with.

```rust
pub trait LexWrite: Lex + Write {
    type Num: AsRef<str> + AsRef<[u8]>;

    // Required method
    fn num_string_with(&mut self, num: Num) -> Num<Self::Num>;

    // Provided methods
    fn num_bytes(&mut self) -> Num<Self::Bytes> { ... }
    fn num_bytes_with(&mut self, num: Num) -> Num<Self::Bytes> { ... }
    fn num_string(&mut self) -> Num<Self::Num> { ... }
}
```

--------------------------------

### Lex Trait Definition

Source: https://docs.rs/hifijson/0.5.0/hifijson/trait.Lex.html

The definition of the Lex trait, which requires implementation of multiple Lex-related traits.

```rust
pub trait Lex:
    Lex
    + Lex
    + Lex { }
```

--------------------------------

### parse_bounded

Source: https://docs.rs/hifijson/0.5.0/hifijson/value/index.html

Parses a JSON value while limiting the recursion depth to prevent stack overflow.

```APIDOC
## parse_bounded

### Description
Parses a JSON value, limiting the recursion to a specified depth.

### Parameters
- **depth** (usize) - Required - The maximum recursion depth allowed during parsing.
```

--------------------------------

### Define the Error enum

Source: https://docs.rs/hifijson/0.5.0/hifijson/escape/enum.Error.html

The structure of the Error enum representing different lexing failure states.

```rust
pub enum Error {
    InvalidKind(u8),
    InvalidHex(u8),
    InvalidChar(u32),
    ExpectedLowSurrogate,
    Eof,
}
```

--------------------------------

### Lex Trait Definition

Source: https://docs.rs/hifijson/0.5.0/hifijson/str/trait.Lex.html

The definition of the Lex trait, which includes methods for string processing without allocation.

```rust
pub trait Lex: Lex {
    // Provided methods
    fn str_ignore(&mut self) -> Result<(), Error> { ... }
    fn str_foreach(&mut self, f: impl FnMut(u8)) -> Result<(), Error> { ... }
}
```

--------------------------------

### Lex Trait Definition

Source: https://docs.rs/hifijson/0.5.0/hifijson/num/trait.Lex.html

The trait definition for Lex, which requires the Read trait and provides methods for ignoring numbers.

```rust
pub trait Lex: Read {
    // Provided methods
    fn num_ignore(&mut self) -> Num { ... }
    fn num_ignore_with(&mut self, num: Num) -> Num { ... }
}
```

--------------------------------

### Define IterLexer struct

Source: https://docs.rs/hifijson/0.5.0/hifijson/struct.IterLexer.html

The structure definition for IterLexer, which holds an optional error state.

```rust
pub struct IterLexer<E, I> {
    pub error: Option<E>,
    /* private fields */
}
```

--------------------------------

### Value Enum Definition

Source: https://docs.rs/hifijson/0.5.0/hifijson/value/enum.Value.html

The core enum structure representing various JSON data types.

```rust
pub enum Value<Num, Str> {
    Null,
    Bool(bool),
    Number((Num, Parts)),
    String(Str),
    Array(Vec<Self>),
    Object(Vec<(Str, Self)>),
}
```

--------------------------------

### Lex Trait Definition

Source: https://docs.rs/hifijson/0.5.0/hifijson/escape/trait.Lex.html

The definition of the Lex trait, which requires the Read trait and provides methods for handling surrogates, escape sequences, and hex parsing.

```rust
pub trait Lex: Read {
    // Provided methods
    fn low_surrogate(&mut self, high: u16) -> Result<u32, Error> { ... }
    fn escape(&mut self, c: u8) -> Result<char, Error> { ... }
    fn hex<T: From<u8> + Shl<Output = T> + Add<Output = T>>(
        &mut self,
    ) -> Result<T, Error> { ... }
}
```

--------------------------------

### Lit Enum Definition

Source: https://docs.rs/hifijson/0.5.0/hifijson/escape/enum.Lit.html

The definition of the Lit enum containing variants for various escape characters.

```rust
pub enum Lit {
    QuotationMark,
    ReverseSolidus,
    Solidus,
    Backspace,
    FormFeed,
    LineFeed,
    Tab,
    CarriageReturn,
}
```

--------------------------------

### parse_unbounded

Source: https://docs.rs/hifijson/0.5.0/hifijson/value/index.html

Parses a JSON value without imposing a recursion depth limit.

```APIDOC
## parse_unbounded

### Description
Parses a value, not limiting the recursion depth.
```

--------------------------------

### Define the Error enum

Source: https://docs.rs/hifijson/0.5.0/hifijson/enum.Error.html

The Error enum structure used to represent parsing errors in hifijson.

```rust
pub enum Error {
    Depth,
    Num(Error),
    Str(Error),
    Token(Expect),
}
```
Tokens:
Raw