Struct `RawValue`

#[repr(transparent)]
pub struct RawValue { /* private fields */ }

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`

const NULL: &'static RawValue = _;

A constant RawValue with the JSON value null.

const TRUE: &'static RawValue = _;

A constant RawValue with the JSON value true.

const FALSE: &'static RawValue = _;

A constant RawValue with the JSON value false.

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.

unsafe fn from_string_unchecked(json: String) -> Box<Self>

Convert an owned String of JSON data to an owned RawValue without checking that it contains valid JSON.

This is the unchecked counterpart of RawValue::from_string, for strings that are already known to be valid JSON, such as the output of another JSON serializer. Unlike from_string, it does not re-parse the string; the only cost is String::into_boxed_str.

Safety

The string passed in must contain a single well-formed JSON value with no leading or trailing whitespace. RawValue is written verbatim into JSON output wherever it is embedded, and other code (including unsafe code) is allowed to rely on RawValue upholding this invariant, in the same way that unsafe code may rely on str containing valid UTF-8.

In debug builds this contract is checked with a debug_assert! that re-parses the input; the check is compiled out in release builds, so only release performance matches the "no re-parse" guarantee above.

Example

use serde_json::value::RawValue;

let json = serde_json::to_string(&[1, 2, 3])?;

// SAFETY: `json` was produced by serde_json's own serializer, so it is
// a single well-formed JSON value without surrounding whitespace.
let raw = unsafe { RawValue::from_string_unchecked(json) };

assert_eq!(raw.get(), "[1,2,3]");
# Ok::<(), serde_json::Error>(())

fn get(&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(())
}