Struct RawValue 

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:

#[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.

#[derive(Deserialize)]
struct SomeStruct {
    raw_value: Box<RawValue>,
}

Implementations

impl RawValue

pub const NULL: &'static RawValue

A constant RawValue with the JSON value null.

pub const TRUE: &'static RawValue

A constant RawValue with the JSON value true.

pub const FALSE: &'static RawValue

A constant RawValue with the JSON value false.

pub fn from_string(json: String) -> Result<Box<RawValue>, 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.

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

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]");

pub 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(())
}

Trait Implementations

impl AsyncCheck for Box<RawValue>

fn check_async<'a>(&'a self, _ctx: &'a mut Context) -> BoxFuture<'a, ()>

impl<'de> BorrowType<'de> for Box<RawValue>

fn decode(value: Input<'de>, ctx: &mut Context, coerce: bool) -> Option<Self>

fn encode(&self, ctx: &mut Context) -> Value

fn schema(ctx: &mut SchemaContext, coerce: bool) -> Value

fn validate_into(&self, ctx: &mut Context)

fn validate_rules(&self, rules: &Rules, ctx: &mut Context)

fn kind() -> TypeKind

fn encode_input(&self, ctx: &mut Context) -> Value

fn prepare_default(self, ctx: &mut Context) -> Option<Self>

fn normalize(self, rules: &Rules, ctx: &mut Context) -> Option<Self>

fn missing() -> Option<Self>

fn allows_missing() -> bool

fn async_required(_seen: &mut HashSet<&'static str>) -> bool

impl Debug for RawValue

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

Formats the value using the given formatter.

impl<'de, 'a> Deserialize<'de> for &'a RawValue

where 'de: 'a,

fn deserialize<D>( deserializer: D, ) -> Result<&'a RawValue, <D as Deserializer<'de>>::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<'de> Deserializer<'de> for &'de RawValue

type Error = Error

The error type that can be returned if some error occurs during deserialization.

fn deserialize_any<V>( self, visitor: V, ) -> Result<<V as Visitor<'de>>::Value, Error>

where V: Visitor<'de>,

Require the Deserializer to figure out how to drive the visitor based on what data type is in the input.

fn deserialize_bool<V>( self, visitor: V, ) -> Result<<V as Visitor<'de>>::Value, Error>

where V: Visitor<'de>,

Hint that the Deserialize type is expecting a bool value.

fn deserialize_i8<V>( self, visitor: V, ) -> Result<<V as Visitor<'de>>::Value, Error>

where V: Visitor<'de>,

Hint that the Deserialize type is expecting an i8 value.

fn deserialize_i16<V>( self, visitor: V, ) -> Result<<V as Visitor<'de>>::Value, Error>

where V: Visitor<'de>,

Hint that the Deserialize type is expecting an i16 value.

fn deserialize_i32<V>( self, visitor: V, ) -> Result<<V as Visitor<'de>>::Value, Error>

where V: Visitor<'de>,

Hint that the Deserialize type is expecting an i32 value.

fn deserialize_i64<V>( self, visitor: V, ) -> Result<<V as Visitor<'de>>::Value, Error>

where V: Visitor<'de>,

Hint that the Deserialize type is expecting an i64 value.

fn deserialize_i128<V>( self, visitor: V, ) -> Result<<V as Visitor<'de>>::Value, Error>

where V: Visitor<'de>,

Hint that the Deserialize type is expecting an i128 value.

fn deserialize_u8<V>( self, visitor: V, ) -> Result<<V as Visitor<'de>>::Value, Error>

where V: Visitor<'de>,

Hint that the Deserialize type is expecting a u8 value.

fn deserialize_u16<V>( self, visitor: V, ) -> Result<<V as Visitor<'de>>::Value, Error>

where V: Visitor<'de>,

Hint that the Deserialize type is expecting a u16 value.

fn deserialize_u32<V>( self, visitor: V, ) -> Result<<V as Visitor<'de>>::Value, Error>

where V: Visitor<'de>,

Hint that the Deserialize type is expecting a u32 value.

fn deserialize_u64<V>( self, visitor: V, ) -> Result<<V as Visitor<'de>>::Value, Error>

where V: Visitor<'de>,

Hint that the Deserialize type is expecting a u64 value.

fn deserialize_u128<V>( self, visitor: V, ) -> Result<<V as Visitor<'de>>::Value, Error>

where V: Visitor<'de>,

Hint that the Deserialize type is expecting an u128 value.

fn deserialize_f32<V>( self, visitor: V, ) -> Result<<V as Visitor<'de>>::Value, Error>

where V: Visitor<'de>,

Hint that the Deserialize type is expecting a f32 value.

fn deserialize_f64<V>( self, visitor: V, ) -> Result<<V as Visitor<'de>>::Value, Error>

where V: Visitor<'de>,

Hint that the Deserialize type is expecting a f64 value.

fn deserialize_char<V>( self, visitor: V, ) -> Result<<V as Visitor<'de>>::Value, Error>

where V: Visitor<'de>,

Hint that the Deserialize type is expecting a char value.

fn deserialize_str<V>( self, visitor: V, ) -> Result<<V as Visitor<'de>>::Value, Error>

where V: Visitor<'de>,

Hint that the Deserialize type is expecting a string value and does not benefit from taking ownership of buffered data owned by the Deserializer.

fn deserialize_string<V>( self, visitor: V, ) -> Result<<V as Visitor<'de>>::Value, Error>

where V: Visitor<'de>,

Hint that the Deserialize type is expecting a string value and would benefit from taking ownership of buffered data owned by the Deserializer.

fn deserialize_bytes<V>( self, visitor: V, ) -> Result<<V as Visitor<'de>>::Value, Error>

where V: Visitor<'de>,

Hint that the Deserialize type is expecting a byte array and does not benefit from taking ownership of buffered data owned by the Deserializer.

fn deserialize_byte_buf<V>( self, visitor: V, ) -> Result<<V as Visitor<'de>>::Value, Error>

where V: Visitor<'de>,

Hint that the Deserialize type is expecting a byte array and would benefit from taking ownership of buffered data owned by the Deserializer.

fn deserialize_option<V>( self, visitor: V, ) -> Result<<V as Visitor<'de>>::Value, Error>

where V: Visitor<'de>,

Hint that the Deserialize type is expecting an optional value.

fn deserialize_unit<V>( self, visitor: V, ) -> Result<<V as Visitor<'de>>::Value, Error>

where V: Visitor<'de>,

Hint that the Deserialize type is expecting a unit value.

fn deserialize_unit_struct<V>( self, name: &'static str, visitor: V, ) -> Result<<V as Visitor<'de>>::Value, Error>

where V: Visitor<'de>,

Hint that the Deserialize type is expecting a unit struct with a particular name.

fn deserialize_newtype_struct<V>( self, name: &'static str, visitor: V, ) -> Result<<V as Visitor<'de>>::Value, Error>

where V: Visitor<'de>,

Hint that the Deserialize type is expecting a newtype struct with a particular name.

fn deserialize_seq<V>( self, visitor: V, ) -> Result<<V as Visitor<'de>>::Value, Error>

where V: Visitor<'de>,

Hint that the Deserialize type is expecting a sequence of values.

fn deserialize_tuple<V>( self, len: usize, visitor: V, ) -> Result<<V as Visitor<'de>>::Value, Error>

where V: Visitor<'de>,

Hint that the Deserialize type is expecting a sequence of values and knows how many values there are without looking at the serialized data.

fn deserialize_tuple_struct<V>( self, name: &'static str, len: usize, visitor: V, ) -> Result<<V as Visitor<'de>>::Value, Error>

where V: Visitor<'de>,

Hint that the Deserialize type is expecting a tuple struct with a particular name and number of fields.

fn deserialize_map<V>( self, visitor: V, ) -> Result<<V as Visitor<'de>>::Value, Error>

where V: Visitor<'de>,

Hint that the Deserialize type is expecting a map of key-value pairs.

fn deserialize_struct<V>( self, name: &'static str, fields: &'static [&'static str], visitor: V, ) -> Result<<V as Visitor<'de>>::Value, Error>

where V: Visitor<'de>,

Hint that the Deserialize type is expecting a struct with a particular name and fields.

fn deserialize_enum<V>( self, name: &'static str, variants: &'static [&'static str], visitor: V, ) -> Result<<V as Visitor<'de>>::Value, Error>

where V: Visitor<'de>,

Hint that the Deserialize type is expecting an enum value with a particular name and possible variants.

fn deserialize_identifier<V>( self, visitor: V, ) -> Result<<V as Visitor<'de>>::Value, Error>

where V: Visitor<'de>,

Hint that the Deserialize type is expecting the name of a struct field or the discriminant of an enum variant.

fn deserialize_ignored_any<V>( self, visitor: V, ) -> Result<<V as Visitor<'de>>::Value, Error>

where V: Visitor<'de>,

Hint that the Deserialize type needs to deserialize a value whose type doesn’t matter because it is ignored.

fn is_human_readable(&self) -> bool

Determine whether Deserialize implementations should expect to deserialize their human-readable form.

impl Display for RawValue

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

Formats the value using the given formatter.

impl<'de> IntoDeserializer<'de, Error> for &'de RawValue

type Deserializer = &'de RawValue

The type of the deserializer being converted into.

fn into_deserializer( self, ) -> <&'de RawValue as IntoDeserializer<'de, Error>>::Deserializer

Convert this value into a deserializer.

impl JsonType for Box<RawValue>

fn decode(value: Value, ctx: &mut Context, _: bool) -> Option<Self>

fn decode_input(input: Input<'_>, ctx: &mut Context, _: bool) -> Option<Self>

Decode a raw subtree. Custom types can override this to bypass Value entirely.

fn encode(&self, ctx: &mut Context) -> Value

fn schema(_: &mut SchemaContext, _: bool) -> Value

fn prepare_default(self, ctx: &mut Context) -> Option<Self>

fn encode_input(&self, ctx: &mut Context) -> Value

Representation using input aliases and including output-excluded fields. Used to validate typed defaults without losing required input information.

fn validate_into(&self, _ctx: &mut Context)

fn normalize(self, rules: &Rules, ctx: &mut Context) -> Option<Self>

fn validate_rules(&self, rules: &Rules, ctx: &mut Context)

fn async_required(_seen: &mut HashSet<&'static str>) -> bool

fn missing() -> Option<Self>

fn allows_missing() -> bool

fn kind() -> TypeKind

impl Serialize for RawValue

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

where S: Serializer,

Serialize this value into the given Serde serializer.

impl ToOwned for RawValue

type Owned = Box<RawValue>

The resulting type after obtaining ownership.

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

Creates owned data from borrowed data, usually by cloning.

fn clone_into(&self, target: &mut Self::Owned)

Uses borrowed data to replace owned data, usually by cloning.