Struct Raw

pub struct Raw<T> { /* private fields */ }

A wrapper around Box<RawValue> with a generic parameter for the expected Rust type.

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 structs and enums representing event types implement Deserialize, therefore they can be used with Raw. Since Raw does not change the JSON string, it 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

impl<T> Raw<T>

pub fn new(val: &T) -> Result<Raw<T>, Error>

where T: Serialize,

Available on crate feature events only.

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.

pub fn from_json(json: Box<RawValue>) -> Raw<T>

Available on crate feature events only.

Create a Raw from a boxed RawValue.

pub fn from_json_string(json: String) -> Result<Raw<T>, Error>

Available on crate feature events only.

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.

pub fn json(&self) -> &RawValue

Available on crate feature events only.

Access the underlying json value.

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

Available on crate feature events only.

Convert self into the underlying json value.

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

where U: Deserialize<'a>,

Available on crate feature events only.

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>()?;
    // ...
}

pub fn deserialize<'a>(&'a self) -> Result<T, Error>

where T: Deserialize<'a>,

Available on crate feature events only.

Try to deserialize the JSON as the expected type.

pub fn deserialize_as<'a, U>(&'a self) -> Result<U, Error>

where U: Deserialize<'a>,

Available on crate feature events only.

Try to deserialize the JSON as a custom type.

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

Available on crate feature events only.

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.

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

Available on crate feature events only.

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

impl<T> Clone for Raw<T>

fn clone(&self) -> Raw<T>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T> Debug for Raw<T>

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

Formats the value using the given formatter.

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

fn deserialize<D>( deserializer: D, ) -> Result<Raw<T>, <D as Deserializer<'de>>::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl From<Raw<ServerSigningKeys>> for Response

fn from(server_key: Raw<ServerSigningKeys>) -> Response

Converts to this type from the input type.

impl<T> RawExt<T> for Raw<T>

where T: EventContentFromType, <T as EventContent>::EventType: Display,

fn deserialize_with_type( &self, event_type: <T as EventContent>::EventType, ) -> Result<T, Error>

Try to deserialize the JSON as an event’s content with the given event type.

impl<T> Serialize for Raw<T>

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.