Struct RawJsonValue

pub struct RawJsonValue<'text, 'a> { /* private fields */ }

A JSON value in a RawJson.

This struct only provides the text and structural information (e.g., kind, parent, children) of this JSON value. Interpreting that text is the responsibility of the user.

To convert this JSON value to a Rust type that implements the FromRawJsonValue trait, RawJsonValue::try_to() is convinient. For other Rust types, you can use the standard FromStr trait or other parsing methods to parse the underlaying JSON text of this value as shown below:

let text = "1.23";
let json = RawJson::parse(text)?;
let raw: RawJsonValue = json.value();
let parsed: f32 =
    raw.as_number_str()?.parse().map_err(|e| JsonParseError::invalid_value(raw, e))?;
assert_eq!(parsed, 1.23);

Implementations

impl<'text, 'a> RawJsonValue<'text, 'a>

pub fn kind(self) -> JsonValueKind

Returns the kind of this JSON value.

pub fn position(self) -> usize

Returns the byte position where this value begins in the JSON text (self.json().text()).

pub fn json(self) -> &'a RawJson<'text>

Returns a reference to the RawJson instance that contains this value.

pub fn parent(self) -> Option<Self>

Returns the parent value (array or object) that contains this value.

pub fn try_to<T: FromRawJsonValue<'text>>(self) -> Result<T, JsonParseError>

Covnerts this value to T by using FromRawJsonValue::from_raw_json_value().

Examples

let json = RawJson::parse("[1, 2, -3]")?;

// Convert via `FromRawJsonValue::from_raw_json_value()`
let (v0, v1, v2) = FromRawJsonValue::from_raw_json_value(json.value())?;
assert_eq!((v0, v1, v2), (1, 2.0, -3));

// Convert via `RawJsonValue::try_to()`
// (Exactly the same result as the above call, but usually more concise and readable)
let (v0, v1, v2) = json.value().try_to()?;
assert_eq!((v0, v1, v2), (1, 2.0, -3));

pub fn as_raw_str(self) -> &'text str

Returns the raw JSON text of this value as-is.

pub fn as_boolean_str(self) -> Result<&'text str, JsonParseError>

Similar to RawJsonValue::as_raw_str(), but this method verifies whether the value is a JSON boolean.

Examples

let json = RawJson::parse("false")?;
assert_eq!(json.value().as_boolean_str()?.parse(), Ok(false));

let json = RawJson::parse("10")?;
assert!(json.value().as_boolean_str().is_err());

pub fn as_integer_str(self) -> Result<&'text str, JsonParseError>

Similar to RawJsonValue::as_raw_str(), but this method verifies whether the value is a JSON integer number.

Examples

let json = RawJson::parse("123")?;
assert_eq!(json.value().as_integer_str()?.parse(), Ok(123));

let json = RawJson::parse("12.3")?;
assert!(json.value().as_integer_str().is_err());

pub fn as_float_str(self) -> Result<&'text str, JsonParseError>

Similar to RawJsonValue::as_raw_str(), but this method verifies whether the value is a JSON floating-point number.

Examples

let json = RawJson::parse("12.3")?;
assert_eq!(json.value().as_float_str()?.parse(), Ok(12.3));

let json = RawJson::parse("123")?;
assert!(json.value().as_float_str().is_err());

pub fn as_number_str(self) -> Result<&'text str, JsonParseError>

Similar to RawJsonValue::as_raw_str(), but this method verifies whether the value is a JSON number.

Examples

let json = RawJson::parse("123")?;
assert_eq!(json.value().as_number_str()?.parse(), Ok(123));

let json = RawJson::parse("12.3")?;
assert_eq!(json.value().as_number_str()?.parse(), Ok(12.3));

let json = RawJson::parse("null")?;
assert!(json.value().as_number_str().is_err());

pub fn to_unquoted_string_str(self) -> Result<Cow<'text, str>, JsonParseError>

Similar to RawJsonValue::as_raw_str(), but this method verifies whether the value is a JSON number and returns the unquoted content of the string.

Examples

let json = RawJson::parse("\"123\"")?;
assert_eq!(json.value().to_unquoted_string_str()?, "123");
assert_eq!(json.value().to_unquoted_string_str()?.parse(), Ok(123));

let json = RawJson::parse("123")?;
assert!(json.value().to_unquoted_string_str().is_err());

pub fn to_array(self) -> Result<impl Iterator<Item = Self>, JsonParseError>

If the value is a JSON array, this method returns an iterator that iterates over the array’s elements.

Examples

let json = RawJson::parse("[0, 1, 2]")?;
for (i, v) in json.value().to_array()?.enumerate() {
    assert_eq!(v.as_integer_str()?.parse(), Ok(i));
}

let json = RawJson::parse("null")?;
assert!(json.value().to_array().is_err());

pub fn to_fixed_array<const N: usize>(self) -> Result<[Self; N], JsonParseError>

If the value is a JSON array with exactly N elements, this method returns a fixed-size array containing those elements.

Examples

let json = RawJson::parse("[0, 1, 2]")?;
let [v0, v1, v2] = json.value().to_fixed_array()?;
for (i, v) in [v0, v1, v2].into_iter().enumerate() {
    assert_eq!(v.as_integer_str()?.parse(), Ok(i));
}

let json = RawJson::parse("[0, 1]")?;
assert!(json.value().to_fixed_array::<3>().is_err());

pub fn to_object( self, ) -> Result<impl Iterator<Item = (Self, Self)>, JsonParseError>

If the value is a JSON object, this method returns an iterator that iterates over the name and value pairs of the object’s members.

Examples

let json = RawJson::parse(r#"{"a": 1, "b": 2, "c": 3}"#)?;
let mut members = json.value().to_object()?;
let (k, v) = members.next().expect("some");
assert_eq!(k.to_unquoted_string_str()?, "a");
assert_eq!(v.as_integer_str()?.parse(), Ok(1));

let json = RawJson::parse("null")?;
assert!(json.value().to_object().is_err());

pub fn to_fixed_object<const N: usize, const M: usize>( self, required_member_names: [&str; N], optional_member_names: [&str; M], ) -> Result<([Self; N], [Option<Self>; M]), JsonParseError>

If the value is a JSON object, this method extracts member values for a fixed set of member names.

The method returns a tuple containing:

• An array of values for required member names
• An array of optional values for optional member names

Examples

let json = RawJson::parse(r#"{"name": "Alice", "age": 30, "city": "New York"}"#)?;
let (required, optional) = json.value().to_fixed_object(
    ["name", "age"],      // required fields
    ["city", "country"]   // optional fields
)?;

assert_eq!(required[0].to_unquoted_string_str()?, "Alice");
assert_eq!(required[1].as_integer_str()?.parse(), Ok(30));

assert_eq!(optional[0].expect("some").to_unquoted_string_str()?, "New York");
assert!(optional[1].is_none()); // "country" wasn't present

// Fails when required fields are missing
let json = RawJson::parse(r#"{"name": "Bob", "city": "London"}"#)?;
assert!(json.value().to_fixed_object(["name", "age"], ["city"]).is_err());

Trait Implementations

impl<'text, 'a> Clone for RawJsonValue<'text, 'a>

fn clone(&self) -> RawJsonValue<'text, 'a>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'text, 'a> Debug for RawJsonValue<'text, 'a>

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

Formats the value using the given formatter.

impl Display for RawJsonValue<'_, '_>

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

Formats the value using the given formatter.

impl DisplayJson for RawJsonValue<'_, '_>

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

Formats the value as JSON into the provided formatter.

impl<'text, 'a> Hash for RawJsonValue<'text, 'a>

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<'text, 'a> Ord for RawJsonValue<'text, 'a>

fn cmp(&self, other: &RawJsonValue<'text, 'a>) -> 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<'text, 'a> PartialEq for RawJsonValue<'text, 'a>

fn eq(&self, other: &RawJsonValue<'text, 'a>) -> 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<'text, 'a> PartialOrd for RawJsonValue<'text, 'a>

fn partial_cmp(&self, other: &RawJsonValue<'text, 'a>) -> 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<'text, 'a> Copy for RawJsonValue<'text, 'a>

impl<'text, 'a> Eq for RawJsonValue<'text, 'a>

impl<'text, 'a> StructuralPartialEq for RawJsonValue<'text, 'a>