Trait hdk::prelude::holochain_serialized_bytes::serde::Deserializer [−][src]
pub trait Deserializer<'de> {
type Error: Error;
Show 32 methods
fn deserialize_any<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Self::Error>
where
V: Visitor<'de>;
fn deserialize_bool<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Self::Error>
where
V: Visitor<'de>;
fn deserialize_i8<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Self::Error>
where
V: Visitor<'de>;
fn deserialize_i16<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Self::Error>
where
V: Visitor<'de>;
fn deserialize_i32<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Self::Error>
where
V: Visitor<'de>;
fn deserialize_i64<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Self::Error>
where
V: Visitor<'de>;
fn deserialize_u8<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Self::Error>
where
V: Visitor<'de>;
fn deserialize_u16<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Self::Error>
where
V: Visitor<'de>;
fn deserialize_u32<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Self::Error>
where
V: Visitor<'de>;
fn deserialize_u64<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Self::Error>
where
V: Visitor<'de>;
fn deserialize_f32<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Self::Error>
where
V: Visitor<'de>;
fn deserialize_f64<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Self::Error>
where
V: Visitor<'de>;
fn deserialize_char<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Self::Error>
where
V: Visitor<'de>;
fn deserialize_str<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Self::Error>
where
V: Visitor<'de>;
fn deserialize_string<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Self::Error>
where
V: Visitor<'de>;
fn deserialize_bytes<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Self::Error>
where
V: Visitor<'de>;
fn deserialize_byte_buf<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Self::Error>
where
V: Visitor<'de>;
fn deserialize_option<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Self::Error>
where
V: Visitor<'de>;
fn deserialize_unit<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Self::Error>
where
V: Visitor<'de>;
fn deserialize_unit_struct<V>(
self,
name: &'static str,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Self::Error>
where
V: Visitor<'de>;
fn deserialize_newtype_struct<V>(
self,
name: &'static str,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Self::Error>
where
V: Visitor<'de>;
fn deserialize_seq<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Self::Error>
where
V: Visitor<'de>;
fn deserialize_tuple<V>(
self,
len: usize,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Self::Error>
where
V: Visitor<'de>;
fn deserialize_tuple_struct<V>(
self,
name: &'static str,
len: usize,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Self::Error>
where
V: Visitor<'de>;
fn deserialize_map<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Self::Error>
where
V: Visitor<'de>;
fn deserialize_struct<V>(
self,
name: &'static str,
fields: &'static [&'static str],
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Self::Error>
where
V: Visitor<'de>;
fn deserialize_enum<V>(
self,
name: &'static str,
variants: &'static [&'static str],
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Self::Error>
where
V: Visitor<'de>;
fn deserialize_identifier<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Self::Error>
where
V: Visitor<'de>;
fn deserialize_ignored_any<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Self::Error>
where
V: Visitor<'de>;
fn deserialize_i128<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Self::Error>
where
V: Visitor<'de>,
{ ... }
fn deserialize_u128<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Self::Error>
where
V: Visitor<'de>,
{ ... }
fn is_human_readable(&self) -> bool { ... }
}
Expand description
A data format that can deserialize any data structure supported by Serde.
The role of this trait is to define the deserialization half of the Serde
data model, which is a way to categorize every Rust data type into one of
29 possible types. Each method of the Deserializer
trait corresponds to one
of the types of the data model.
Implementations of Deserialize
map themselves into this data model by
passing to the Deserializer
a Visitor
implementation that can receive
these various types.
The types that make up the Serde data model are:
- 14 primitive types
- bool
- i8, i16, i32, i64, i128
- u8, u16, u32, u64, u128
- f32, f64
- char
- string
- UTF-8 bytes with a length and no null terminator.
- When serializing, all strings are handled equally. When deserializing, there are three flavors of strings: transient, owned, and borrowed.
- byte array - [u8]
- Similar to strings, during deserialization byte arrays can be transient, owned, or borrowed.
- option
- Either none or some value.
- unit
- The type of
()
in Rust. It represents an anonymous value containing no data.
- The type of
- unit_struct
- For example
struct Unit
orPhantomData<T>
. It represents a named value containing no data.
- For example
- unit_variant
- For example the
E::A
andE::B
inenum E { A, B }
.
- For example the
- newtype_struct
- For example
struct Millimeters(u8)
.
- For example
- newtype_variant
- For example the
E::N
inenum E { N(u8) }
.
- For example the
- seq
- A variably sized heterogeneous sequence of values, for example
Vec<T>
orHashSet<T>
. When serializing, the length may or may not be known before iterating through all the data. When deserializing, the length is determined by looking at the serialized data.
- A variably sized heterogeneous sequence of values, for example
- tuple
- A statically sized heterogeneous sequence of values for which the
length will be known at deserialization time without looking at the
serialized data, for example
(u8,)
or(String, u64, Vec<T>)
or[u64; 10]
.
- A statically sized heterogeneous sequence of values for which the
length will be known at deserialization time without looking at the
serialized data, for example
- tuple_struct
- A named tuple, for example
struct Rgb(u8, u8, u8)
.
- A named tuple, for example
- tuple_variant
- For example the
E::T
inenum E { T(u8, u8) }
.
- For example the
- map
- A heterogeneous key-value pairing, for example
BTreeMap<K, V>
.
- A heterogeneous key-value pairing, for example
- struct
- A heterogeneous key-value pairing in which the keys are strings and
will be known at deserialization time without looking at the serialized
data, for example
struct S { r: u8, g: u8, b: u8 }
.
- A heterogeneous key-value pairing in which the keys are strings and
will be known at deserialization time without looking at the serialized
data, for example
- struct_variant
- For example the
E::S
inenum E { S { r: u8, g: u8, b: u8 } }
.
- For example the
The Deserializer
trait supports two entry point styles which enables
different kinds of deserialization.
-
The
deserialize
method. Self-describing data formats like JSON are able to look at the serialized data and tell what it represents. For example the JSON deserializer may see an opening curly brace ({
) and know that it is seeing a map. If the data format supportsDeserializer::deserialize_any
, it will drive the Visitor using whatever type it sees in the input. JSON uses this approach when deserializingserde_json::Value
which is an enum that can represent any JSON document. Without knowing what is in a JSON document, we can deserialize it toserde_json::Value
by going throughDeserializer::deserialize_any
. -
The various
deserialize_*
methods. Non-self-describing formats like Bincode need to be told what is in the input in order to deserialize it. Thedeserialize_*
methods are hints to the deserializer for how to interpret the next piece of input. Non-self-describing formats are not able to deserialize something likeserde_json::Value
which relies onDeserializer::deserialize_any
.
When implementing Deserialize
, you should avoid relying on
Deserializer::deserialize_any
unless you need to be told by the
Deserializer what type is in the input. Know that relying on
Deserializer::deserialize_any
means your data type will be able to
deserialize from self-describing formats only, ruling out Bincode and many
others.
Lifetime
The 'de
lifetime of this trait is the lifetime of data that may be
borrowed from the input when deserializing. See the page Understanding
deserializer lifetimes for a more detailed explanation of these lifetimes.
Example implementation
The example data format presented on the website contains example code for
a basic JSON Deserializer
.
Associated Types
Required methods
Require the Deserializer
to figure out how to drive the visitor based
on what data type is in the input.
When implementing Deserialize
, you should avoid relying on
Deserializer::deserialize_any
unless you need to be told by the
Deserializer what type is in the input. Know that relying on
Deserializer::deserialize_any
means your data type will be able to
deserialize from self-describing formats only, ruling out Bincode and
many others.
Hint that the Deserialize
type is expecting a bool
value.
Hint that the Deserialize
type is expecting an i8
value.
Hint that the Deserialize
type is expecting an i16
value.
Hint that the Deserialize
type is expecting an i32
value.
Hint that the Deserialize
type is expecting an i64
value.
Hint that the Deserialize
type is expecting a u8
value.
Hint that the Deserialize
type is expecting a u16
value.
Hint that the Deserialize
type is expecting a u32
value.
Hint that the Deserialize
type is expecting a u64
value.
Hint that the Deserialize
type is expecting a f32
value.
Hint that the Deserialize
type is expecting a f64
value.
Hint that the Deserialize
type is expecting a char
value.
Hint that the Deserialize
type is expecting a string value and does
not benefit from taking ownership of buffered data owned by the
Deserializer
.
If the Visitor
would benefit from taking ownership of String
data,
indiciate this to the Deserializer
by using deserialize_string
instead.
Hint that the Deserialize
type is expecting a string value and would
benefit from taking ownership of buffered data owned by the
Deserializer
.
If the Visitor
would not benefit from taking ownership of String
data, indicate that to the Deserializer
by using deserialize_str
instead.
Hint that the Deserialize
type is expecting a byte array and does not
benefit from taking ownership of buffered data owned by the
Deserializer
.
If the Visitor
would benefit from taking ownership of Vec<u8>
data,
indicate this to the Deserializer
by using deserialize_byte_buf
instead.
Hint that the Deserialize
type is expecting a byte array and would
benefit from taking ownership of buffered data owned by the
Deserializer
.
If the Visitor
would not benefit from taking ownership of Vec<u8>
data, indicate that to the Deserializer
by using deserialize_bytes
instead.
Hint that the Deserialize
type is expecting an optional value.
This allows deserializers that encode an optional value as a nullable
value to convert the null value into None
and a regular value into
Some(value)
.
Hint that the Deserialize
type is expecting a unit value.
Hint that the Deserialize
type is expecting a unit struct with a
particular name.
Hint that the Deserialize
type is expecting a newtype struct with a
particular name.
Hint that the Deserialize
type is expecting a sequence of values.
Hint that the Deserialize
type is expecting a sequence of values and
knows how many values there are without looking at the serialized data.
Hint that the Deserialize
type is expecting a tuple struct with a
particular name and number of fields.
Hint that the Deserialize
type is expecting a map of key-value pairs.
Hint that the Deserialize
type is expecting a struct with a particular
name and fields.
Hint that the Deserialize
type is expecting an enum value with a
particular name and possible variants.
Hint that the Deserialize
type is expecting the name of a struct
field or the discriminant of an enum variant.
Hint that the Deserialize
type needs to deserialize a value whose type
doesn’t matter because it is ignored.
Deserializers for non-self-describing formats may not support this mode.
Provided methods
Hint that the Deserialize
type is expecting an i128
value.
This method is available only on Rust compiler versions >=1.26. The default behavior unconditionally returns an error.
Hint that the Deserialize
type is expecting an u128
value.
This method is available only on Rust compiler versions >=1.26. The default behavior unconditionally returns an error.
fn is_human_readable(&self) -> bool
fn is_human_readable(&self) -> bool
Determine whether Deserialize
implementations should expect to
deserialize their human-readable form.
Some types have a human-readable form that may be somewhat expensive to construct, as well as a binary form that is compact and efficient. Generally text-based formats like JSON and YAML will prefer to use the human-readable one and binary formats like Bincode will prefer the compact one.
use serde::de::{self, Deserialize, Deserializer};
impl<'de> Deserialize<'de> for Timestamp {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: Deserializer<'de>,
{
if deserializer.is_human_readable() {
// Deserialize from a human-readable string like "2015-05-15T17:01:00Z".
let s = String::deserialize(deserializer)?;
Timestamp::from_str(&s).map_err(de::Error::custom)
} else {
// Deserialize from a compact binary representation, seconds since
// the Unix epoch.
let n = u64::deserialize(deserializer)?;
Ok(Timestamp::EPOCH + Duration::seconds(n))
}
}
}
The default implementation of this method returns true
. Data formats
may override this to false
to request a compact form for types that
support one. Note that modifying this method to change a format from
human-readable to compact or vice versa should be regarded as a breaking
change, as a value serialized in human-readable mode is not required to
deserialize from the same data in compact mode.
Implementations on Foreign Types
pub fn deserialize_any<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Error> where
V: Visitor<'de>,
pub fn deserialize_i8<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Error> where
V: Visitor<'de>,
pub fn deserialize_i16<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Error> where
V: Visitor<'de>,
pub fn deserialize_i32<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Error> where
V: Visitor<'de>,
pub fn deserialize_i64<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Error> where
V: Visitor<'de>,
pub fn deserialize_u8<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Error> where
V: Visitor<'de>,
pub fn deserialize_u16<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Error> where
V: Visitor<'de>,
pub fn deserialize_u32<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Error> where
V: Visitor<'de>,
pub fn deserialize_u64<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Error> where
V: Visitor<'de>,
pub fn deserialize_f32<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Error> where
V: Visitor<'de>,
pub fn deserialize_f64<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Error> where
V: Visitor<'de>,
pub fn deserialize_i128<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Error> where
V: Visitor<'de>,
pub fn deserialize_u128<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Error> where
V: Visitor<'de>,
pub fn deserialize_option<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Error> where
V: Visitor<'de>,
pub fn deserialize_enum<V>(
self,
_name: &str,
_variants: &'static [&'static str],
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Error> where
V: Visitor<'de>,
pub fn deserialize_newtype_struct<V>(
self,
name: &'static str,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Error> where
V: Visitor<'de>,
pub fn deserialize_bool<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Error> where
V: Visitor<'de>,
pub fn deserialize_char<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Error> where
V: Visitor<'de>,
pub fn deserialize_str<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Error> where
V: Visitor<'de>,
pub fn deserialize_string<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Error> where
V: Visitor<'de>,
pub fn deserialize_bytes<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Error> where
V: Visitor<'de>,
pub fn deserialize_byte_buf<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Error> where
V: Visitor<'de>,
pub fn deserialize_unit<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Error> where
V: Visitor<'de>,
pub fn deserialize_unit_struct<V>(
self,
_name: &'static str,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Error> where
V: Visitor<'de>,
pub fn deserialize_seq<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Error> where
V: Visitor<'de>,
pub fn deserialize_tuple<V>(
self,
_len: usize,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Error> where
V: Visitor<'de>,
pub fn deserialize_tuple_struct<V>(
self,
_name: &'static str,
_len: usize,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Error> where
V: Visitor<'de>,
pub fn deserialize_map<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Error> where
V: Visitor<'de>,
pub 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>,
pub fn deserialize_any<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Error> where
V: Visitor<'de>,
pub fn deserialize_i8<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Error> where
V: Visitor<'de>,
pub fn deserialize_i16<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Error> where
V: Visitor<'de>,
pub fn deserialize_i32<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Error> where
V: Visitor<'de>,
pub fn deserialize_i64<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Error> where
V: Visitor<'de>,
pub fn deserialize_u8<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Error> where
V: Visitor<'de>,
pub fn deserialize_u16<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Error> where
V: Visitor<'de>,
pub fn deserialize_u32<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Error> where
V: Visitor<'de>,
pub fn deserialize_u64<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Error> where
V: Visitor<'de>,
pub fn deserialize_f32<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Error> where
V: Visitor<'de>,
pub fn deserialize_f64<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Error> where
V: Visitor<'de>,
pub fn deserialize_i128<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Error> where
V: Visitor<'de>,
pub fn deserialize_u128<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, Error> where
V: Visitor<'de>,
pub fn deserialize_bool<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, <&'a Number as Deserializer<'de>>::Error> where
V: Visitor<'de>,
pub fn deserialize_char<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, <&'a Number as Deserializer<'de>>::Error> where
V: Visitor<'de>,
pub fn deserialize_str<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, <&'a Number as Deserializer<'de>>::Error> where
V: Visitor<'de>,
pub fn deserialize_string<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, <&'a Number as Deserializer<'de>>::Error> where
V: Visitor<'de>,
pub fn deserialize_bytes<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, <&'a Number as Deserializer<'de>>::Error> where
V: Visitor<'de>,
pub fn deserialize_byte_buf<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, <&'a Number as Deserializer<'de>>::Error> where
V: Visitor<'de>,
pub fn deserialize_option<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, <&'a Number as Deserializer<'de>>::Error> where
V: Visitor<'de>,
pub fn deserialize_unit<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, <&'a Number as Deserializer<'de>>::Error> where
V: Visitor<'de>,
pub fn deserialize_unit_struct<V>(
self,
name: &'static str,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, <&'a Number as Deserializer<'de>>::Error> where
V: Visitor<'de>,
pub fn deserialize_newtype_struct<V>(
self,
name: &'static str,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, <&'a Number as Deserializer<'de>>::Error> where
V: Visitor<'de>,
pub fn deserialize_seq<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, <&'a Number as Deserializer<'de>>::Error> where
V: Visitor<'de>,
pub fn deserialize_tuple<V>(
self,
len: usize,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, <&'a Number as Deserializer<'de>>::Error> where
V: Visitor<'de>,
pub fn deserialize_tuple_struct<V>(
self,
name: &'static str,
len: usize,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, <&'a Number as Deserializer<'de>>::Error> where
V: Visitor<'de>,
pub fn deserialize_map<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, <&'a Number as Deserializer<'de>>::Error> where
V: Visitor<'de>,
pub fn deserialize_struct<V>(
self,
name: &'static str,
fields: &'static [&'static str],
visitor: V
) -> Result<<V as Visitor<'de>>::Value, <&'a Number as Deserializer<'de>>::Error> where
V: Visitor<'de>,
pub fn deserialize_enum<V>(
self,
name: &'static str,
variants: &'static [&'static str],
visitor: V
) -> Result<<V as Visitor<'de>>::Value, <&'a Number as Deserializer<'de>>::Error> where
V: Visitor<'de>,
pub fn deserialize_identifier<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, <&'a Number as Deserializer<'de>>::Error> where
V: Visitor<'de>,
pub fn deserialize_ignored_any<V>(
self,
visitor: V
) -> Result<<V as Visitor<'de>>::Value, <&'a Number as Deserializer<'de>>::Error> where
V: Visitor<'de>,
Parses a JSON string as bytes. Note that this function does not check whether the bytes represent a valid UTF-8 string.
The relevant part of the JSON specification is Section 8.2 of RFC 7159:
When all the strings represented in a JSON text are composed entirely of Unicode characters (however escaped), then that JSON text is interoperable in the sense that all software implementations that parse it will agree on the contents of names and of string values in objects and arrays.
However, the ABNF in this specification allows member names and string values to contain bit sequences that cannot encode Unicode characters; for example, “\uDEAD” (a single unpaired UTF-16 surrogate). Instances of this have been observed, for example, when a library truncates a UTF-16 string without checking whether the truncation split a surrogate pair. The behavior of software that receives JSON texts containing such values is unpredictable; for example, implementations might return different values for the length of a string value or even suffer fatal runtime exceptions.
The behavior of serde_json is specified to fail on non-UTF-8 strings when deserializing into Rust UTF-8 string types such as String, and succeed with non-UTF-8 bytes when deserializing using this method.
Escape sequences are processed as usual, and for \uXXXX
escapes it is
still checked if the hex number represents a valid Unicode code point.
Examples
You can use this to parse JSON strings containing invalid UTF-8 bytes, or unpaired surrogates.
use serde_bytes::ByteBuf;
fn look_at_bytes() -> Result<(), serde_json::Error> {
let json_data = b"\"some bytes: \xe5\x00\xe5\"";
let bytes: ByteBuf = serde_json::from_slice(json_data)?;
assert_eq!(b'\xe5', bytes[12]);
assert_eq!(b'\0', bytes[13]);
assert_eq!(b'\xe5', bytes[14]);
Ok(())
}
Backslash escape sequences like \n
are still interpreted and required
to be valid. \u
escape sequences are required to represent a valid
Unicode code point or lone surrogate.
use serde_bytes::ByteBuf;
fn look_at_bytes() -> Result<(), serde_json::Error> {
let json_data = b"\"lone surrogate: \\uD801\"";
let bytes: ByteBuf = serde_json::from_slice(json_data)?;
let expected = b"lone surrogate: \xED\xA0\x81";
assert_eq!(expected, bytes.as_slice());
Ok(())
}
Parses a null
as a None, and any other values as a Some(...)
.
Parses a newtype struct as the underlying value.
Parses an enum as an object like {"$KEY":$VALUE}
, where $VALUE is either a straight
value, a [..]
, or a {..}
.