Struct RawValue

pub struct RawValue { /* private fields */ }

Available on crate feature raw_value only.

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

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 Clone for Box<RawValue>

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for RawValue

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

Formats the value using the given formatter.

impl Default for Box<RawValue>

fn default() -> Self

Returns the “default value” for a type.

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

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

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

fn deserialize<D>(deserializer: D) -> Result<Self, D::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::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::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::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::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::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::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::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::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::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::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::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::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::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::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::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::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::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::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::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::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::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::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::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::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::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::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::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::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::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::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::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

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) -> Self::Deserializer

Convert this value into a deserializer.

impl Serialize for RawValue

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::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) -> Self::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.

Layout

Note: Most layout information is completely unstable and may even differ between compilations. The only exception is types with certain repr(...) attributes. Please see the Rust Reference's “Type Layout” chapter for details on type layout guarantees.

Size: (unsized)