Struct `RawValue`

struct RawValue { ... }

Reference to a range of bytes encompassing a single valid JSON value in the input data.

A RawValue can be used to defer parsing parts of a payload until later, or to avoid parsing it at all in the case that part of the payload just needs to be transferred verbatim into a different output object.

When serializing, a value of this type will retain its original formatting and will not be minified or pretty-printed.

Note

RawValue is only available if serde_json is built with the "raw_value" feature.

[dependencies]
serde_json = { version = "1.0", features = ["raw_value"] }

Example

use serde::{Deserialize, Serialize};
use serde_json::{Result, value::RawValue};

#[derive(Deserialize)]
struct Input<'a> {
    code: u32,
    #[serde(borrow)]
    payload: &'a RawValue,
}

#[derive(Serialize)]
struct Output<'a> {
    info: (u32, &'a RawValue),
}

// Efficiently rearrange JSON input containing separate "code" and "payload"
// keys into a single "info" key holding an array of code and payload.
//
// This could be done equivalently using serde_json::Value as the type for
// payload, but &RawValue will perform better because it does not require
// memory allocation. The correct range of bytes is borrowed from the input
// data and pasted verbatim into the output.
fn rearrange(input: &str) -> Result<String> {
    let input: Input = serde_json::from_str(input)?;

    let output = Output {
        info: (input.code, input.payload),
    };

    serde_json::to_string(&output)
}

fn main() -> Result<()> {
    let out = rearrange(r#" {"code": 200, "payload": {}} "#)?;

    assert_eq!(out, r#"{"info":[200,{}]}"#);

    Ok(())
}

Ownership

The typical usage of RawValue will be in the borrowed form:

# use serde::Deserialize;
# use serde_json::value::RawValue;
#
#[derive(Deserialize)]
struct SomeStruct<'a> {
    #[serde(borrow)]
    raw_value: &'a RawValue,
}

The borrowed form is suitable when deserializing through serde_json::from_str and serde_json::from_slice which support borrowing from the input data without memory allocation.

When deserializing through serde_json::from_reader you will need to use the boxed form of RawValue instead. This is almost as efficient but involves buffering the raw value from the I/O stream into memory.

# use serde::Deserialize;
# use serde_json::value::RawValue;
#
#[derive(Deserialize)]
struct SomeStruct {
    raw_value: Box<RawValue>,
}

Implementations

`impl RawValue`

fn from_string(json: String) -> Result<Box<Self>, Error>

Convert an owned String of JSON data to an owned RawValue.

This function is equivalent to serde_json::from_str::<Box<RawValue>> except that we avoid an allocation and memcpy if both of the following are true:

the input has no leading or trailing whitespace, and
the input has capacity equal to its length.

fn get(self: &Self) -> &str

Access the JSON text underlying a raw value.

Example

use serde::Deserialize;
use serde_json::{Result, value::RawValue};

#[derive(Deserialize)]
struct Response<'a> {
    code: u32,
    #[serde(borrow)]
    payload: &'a RawValue,
}

fn process(input: &str) -> Result<()> {
    let response: Response = serde_json::from_str(input)?;

    let payload = response.payload.get();
    if payload.starts_with('{') {
        // handle a payload which is a JSON map
    } else {
        // handle any other type
    }

    Ok(())
}

fn main() -> Result<()> {
    process(r#" {"code": 200, "payload": {}} "#)?;
    Ok(())
}

`impl Debug for RawValue`

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

`impl Display for RawValue`

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

`impl Freeze for RawValue`

`impl RefUnwindSafe for RawValue`

`impl Send for RawValue`

`impl Serialize for RawValue`

fn serialize<S>(self: &Self, serializer: S) -> Result<<S as >::Ok, <S as >::Error> where S: Serializer

`impl Sized for RawValue`

`impl Sync for RawValue`

`impl ToOwned for RawValue`

fn to_owned(self: &Self) -> <Self as >::Owned

`impl Unpin for RawValue`

`impl UnsafeUnpin for RawValue`

`impl UnwindSafe for RawValue`

`impl<T> Any for RawValue`

fn type_id(self: &Self) -> TypeId

`impl<T> Borrow for RawValue`

fn borrow(self: &Self) -> &T

`impl<T> BorrowMut for RawValue`

fn borrow_mut(self: &mut Self) -> &mut T

`impl<T> ToString for RawValue`

fn to_string(self: &Self) -> String