Struct Literal 

pub struct Literal(/* private fields */);

Available on crate feature pipe only.

Zero allocation view of the literal text content of a JSON token.

To prevent allocation and minimize copying, a Literal may contain one or more Bytes buffers that share memory with the Bytes values that were piped into the PipeAnalyzer. Since these buffers have a uniform size, but JSON tokens can have arbitrary lengths, the text content of a token may be split across two or more buffers. In other words, the full text of the content may be non-contiguous in memory. To make this data structure usable in the widest range of use cases, Literal implements the Buf trait, which provides a uniform interface for reading data from potentially non-contiguous sources.

Performance considerations

Clones are cheap and do not allocate. However, for the memory considerations described below, it is preferable to use short-lifetime clones for discrete tasks and not to proliferate long-lived clones.

Memory considerations

Because a Literal may share memory with the Bytes buffers that were piped into a PipeAnalyzer, holding on to a Literal instance may prevent the PipeAnalyzer from reusing buffers. This can lead to increased memory usage. If all Literal instances produced by a PipeAnalyzer are retained, they will tend to prevent any of the allocations backing the input Bytes buffers from being dropped. This may undermine the value proposition of a streaming analyzer and, for large enough JSON texts, may lead to out-of-memory conditions. Therefore, it is advised that you retain Literal instances only as long as necessary to process them, extracting owned copies of their data if you need long-lived access to the token text.

Implementations

impl Literal

pub const fn from_static(s: &'static str) -> Self

Converts a static lifetime string slice to a literal value.

This function is the most efficient way to wrap a static string as a Literal. It does not allocate and produces the lightest-weight Literal value.

If you have a non-static string slice, use from_ref, one of the From trait implementations, or the FromStr implementation. If creating a literal value from an owned String, use from_string.

Examples

Populate and use a hash set of allowed JSON object keys.

use bufjson::lexical::{Token, pipe::{Literal, PipeAnalyzer}};
use bytes::Bytes;
use std::{collections::HashSet, sync::mpsc::channel, thread};

// Populate the set of allowed JSON object keys.
let mut allowed = HashSet::with_capacity(3);
allowed.insert(Literal::from_static(r#""foo""#)); // Note: store `"foo"`, not `foo`
allowed.insert(Literal::from_static(r#""baz""#)); // Note: store `"baz"`, not `baz`

// Parse some JSON.
let (tx, rx) = channel();
tx.send(r#"{"foo":"bar","baz":"qux"}"#.into()).unwrap();
drop(tx);
let mut parser = PipeAnalyzer::new(rx).into_parser();

// Verify that the literal value of every object key is allowed.
assert_eq!(Token::ObjBegin, parser.next());
loop {
    match parser.next_meaningful() {
        Token::Str => {
            let key = parser.content().literal();
            assert!(allowed.contains(&key));
            assert_eq!(Token::Str, parser.next_meaningful()); // Skip corresponding value.
        },
        Token::ObjEnd => (),
        Token::Eof => break,
        _ => unreachable!(),
    }
}

pub fn from_ref<T: AsRef<str> + ?Sized>(s: &T) -> Self

Creates a literal value from anything that cheaply converts to a string slice reference.

If you have a static string slice, prefer from_static, which has a lower construction cost and a more efficient implementation. If you have an owned String you can consume, prefer from_string, which will avoid allocation. If you have a Cow you can consume, prefer From<Cow<'_, str>>, which will avoid allocation if the Cow contains an owned value.

pub fn from_string(s: String) -> Self

Creates a literal value by consuming an owned string value.

Examples

Create a literal from an owned string.

let s = "foo".to_string();
let lit = Literal::from_string(s);
assert_eq!("foo", lit);

There is a From<String> implementation that is functionally equivalent.

let s = "bar".to_string();
let lit: Literal = s.into();
assert_eq!("bar", lit);

pub fn len(&self) -> usize

Returns the length of self.

This length is in bytes, not char values or graphemes. In other words, it might not be what a human considers the length of the string.

Examples

Get the length of a literal.

let boring = Literal::from_static("foo");
assert_eq!(3, boring.len());

let fancy = Literal::from_static("ƒoo"); // fancy f!
assert_eq!(fancy.len(), 4);

pub fn is_empty(&self) -> bool

Returns true if self has a length of zero bytes.

Examples

assert_eq!(true, Literal::from_static("").is_empty());

Trait Implementations

impl Clone for Literal

fn clone(&self) -> Literal

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Literal

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Literal

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T: ?Sized + AsRef<str>> From<&T> for Literal

fn from(value: &T) -> Self

Converts to this type from the input type.

impl<'a> From<Cow<'a, str>> for Literal

fn from(value: Cow<'a, str>) -> Self

Converts to this type from the input type.

impl From<Literal> for String

fn from(value: Literal) -> Self

Converts to this type from the input type.

impl From<String> for Literal

fn from(value: String) -> Self

Converts to this type from the input type.

impl FromStr for Literal

type Err = Infallible

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl Hash for Literal

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl IntoBuf for Literal

type Buf = LiteralBuf

fn into_buf(self) -> Self::Buf

Converts self into a Buf.

impl Ord for Literal

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl OrdStr for Literal

fn cmp(&self, other: &str) -> Ordering

Returns an Ordering between self and other.

impl PartialEq<&str> for Literal

fn eq(&self, other: &&str) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<Literal> for &str

fn eq(&self, other: &Literal) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<Literal> for String

fn eq(&self, other: &Literal) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<Literal> for str

fn eq(&self, other: &Literal) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<String> for Literal

fn eq(&self, other: &String) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<str> for Literal

fn eq(&self, other: &str) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq for Literal

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd<&str> for Literal

fn partial_cmp(&self, other: &&str) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl PartialOrd<Literal> for &str

fn partial_cmp(&self, other: &Literal) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl PartialOrd<Literal> for String

fn partial_cmp(&self, other: &Literal) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl PartialOrd<Literal> for str

fn partial_cmp(&self, other: &Literal) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl PartialOrd<String> for Literal

fn partial_cmp(&self, other: &String) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl PartialOrd<str> for Literal

fn partial_cmp(&self, other: &str) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl PartialOrd for Literal

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Eq for Literal

impl EqStr for Literal