Struct ruma_common::serde::Raw

source ·
pub struct Raw<T> { /* private fields */ }
Expand description

A wrapper around Box<RawValue>, to be used in place of any type in the Matrix endpoint definition to allow request and response types to contain that said type represented by the generic argument Ev.

Ruma offers the Raw wrapper to enable passing around JSON text that is only partially validated. This is useful when a client receives events that do not follow the spec perfectly or a server needs to generate reference hashes with the original canonical JSON string. All event structs and enums implement Serialize / Deserialize, Raw should be used to pass around events in a lossless way.


let json = r#"{ "type": "imagine a full event", "content": {...} }"#;

let deser = serde_json::from_str::<Raw<AnyTimelineEvent>>(json)
    .unwrap() // the first Result from serde_json::from_str, will not fail
    .deserialize() // deserialize to the inner type
    .unwrap(); // finally get to the AnyTimelineEvent

Implementations§

source§

impl<T> Raw<T>

source

pub fn new(val: &T) -> Result<Self>
where T: Serialize,

Create a Raw by serializing the given T.

Shorthand for serde_json::value::to_raw_value(val).map(Raw::from_json), but specialized to T.

§Errors

Fails if Ts Serialize implementation fails.

source

pub fn from_json(json: Box<RawJsonValue>) -> Self

Create a Raw from a boxed RawValue.

source

pub fn from_json_string(json: String) -> Result<Self>

Convert an owned String of JSON data to Raw<T>.

This function is equivalent to serde_json::from_str::<Raw<T>> except that an allocation and copy is avoided if both of the following are true:

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

pub fn json(&self) -> &RawJsonValue

Access the underlying json value.

source

pub fn into_json(self) -> Box<RawJsonValue>

Convert self into the underlying json value.

source

pub fn get_field<'a, U>(&'a self, field_name: &str) -> Result<Option<U>>
where U: Deserialize<'a>,

Try to access a given field inside this Raw, assuming it contains an object.

Returns Err(_) when the contained value is not an object, or the field exists but is fails to deserialize to the expected type.

Returns Ok(None) when the field doesn’t exist or is null.

§Example
if raw_event.get_field::<String>("type")?.as_deref() == Some("org.custom.matrix.event") {
    let event = raw_event.deserialize_as::<CustomMatrixEvent>()?;
    // ...
}
source

pub fn deserialize<'a>(&'a self) -> Result<T>
where T: Deserialize<'a>,

Try to deserialize the JSON as the expected type.

source

pub fn deserialize_as<'a, U>(&'a self) -> Result<U>
where U: Deserialize<'a>,

Try to deserialize the JSON as a custom type.

source

pub fn cast<U>(self) -> Raw<U>

Turns Raw<T> into Raw<U> without changing the underlying JSON.

This is useful for turning raw specific event types into raw event enum types.

source

pub fn cast_ref<U>(&self) -> &Raw<U>

Turns &Raw<T> into &Raw<U> without changing the underlying JSON.

This is useful for turning raw specific event types into raw event enum types.

Trait Implementations§

source§

impl<T> Clone for Raw<T>

source§

fn clone(&self) -> Self

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

impl<T> Debug for Raw<T>

source§

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

Formats the value using the given formatter. Read more
source§

impl<'de, T> Deserialize<'de> for Raw<T>

source§

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer. Read more
source§

impl<T> Serialize for Raw<T>

source§

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

Serialize this value into the given Serde serializer. Read more

Auto Trait Implementations§

§

impl<T> RefUnwindSafe for Raw<T>
where T: RefUnwindSafe,

§

impl<T> Send for Raw<T>
where T: Send,

§

impl<T> Sync for Raw<T>
where T: Sync,

§

impl<T> Unpin for Raw<T>
where T: Unpin,

§

impl<T> UnwindSafe for Raw<T>
where T: UnwindSafe,

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

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

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

§

impl<T, W> HasTypeWitness<W> for T
where W: MakeTypeWitness<Arg = T>, T: ?Sized,

§

const WITNESS: W = W::MAKE

A constant of the type witness
§

impl<T> Identity for T
where T: ?Sized,

§

type Type = T

The same type as Self, used to emulate type equality bounds (T == U) with associated type equality constraints (T: Identity<Type = U>).
§

const TYPE_EQ: TypeEq<T, <T as Identity>::Type> = TypeEq::NEW

Proof that Self is the same type as Self::Type, provides methods for casting between Self and Self::Type.
source§

impl<T> Instrument for T

source§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
source§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> ToOwned for T
where T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

§

fn vzip(self) -> V

source§

impl<T> WithSubscriber for T

source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

impl<T> DeserializeOwned for T
where T: for<'de> Deserialize<'de>,