Struct Deserializer

pub struct Deserializer<'de> { /* private fields */ }

The RON deserializer.

If you just want to simply deserialize a value, you can use the from_str convenience function.

Implementations

impl<'de> Deserializer<'de>

pub fn from_str(input: &'de str) -> Result<Deserializer<'de>, SpannedError>

Examples found in repository

examples/reflection/reflection.rs (line 101)

fn setup(type_registry: Res<AppTypeRegistry>) {
    let mut value = Foo {
        a: 1,
        _ignored: NonReflectedValue { _a: 10 },
        nested: Bar { b: 8 },
    };

    // You can set field values like this. The type must match exactly or this will fail.
    *value.get_field_mut("a").unwrap() = 2usize;
    assert_eq!(value.a, 2);
    assert_eq!(*value.get_field::<usize>("a").unwrap(), 2);

    // You can also get the `&dyn PartialReflect` value of a field like this
    let field = value.field("a").unwrap();

    // But values introspected via `PartialReflect` will not return `dyn Reflect` trait objects
    // (even if the containing type does implement `Reflect`), so we need to convert them:
    let fully_reflected_field = field.try_as_reflect().unwrap();

    // Now, you can downcast your `Reflect` value like this:
    assert_eq!(*fully_reflected_field.downcast_ref::<usize>().unwrap(), 2);

    // For this specific case, we also support the shortcut `try_downcast_ref`:
    assert_eq!(*field.try_downcast_ref::<usize>().unwrap(), 2);

    // `DynamicStruct` also implements the `Struct` and `Reflect` traits.
    let mut patch = DynamicStruct::default();
    patch.insert("a", 4usize);

    // You can "apply" Reflect implementations on top of other Reflect implementations.
    // This will only set fields with the same name, and it will fail if the types don't match.
    // You can use this to "patch" your types with new values.
    value.apply(&patch);
    assert_eq!(value.a, 4);

    let type_registry = type_registry.read();
    // By default, all derived `Reflect` types can be Serialized using serde. No need to derive
    // Serialize!
    let serializer = ReflectSerializer::new(&value, &type_registry);
    let ron_string =
        ron::ser::to_string_pretty(&serializer, ron::ser::PrettyConfig::default()).unwrap();
    info!("{}\n", ron_string);

    // Dynamic properties can be deserialized
    let reflect_deserializer = ReflectDeserializer::new(&type_registry);
    let mut deserializer = ron::de::Deserializer::from_str(&ron_string).unwrap();
    let reflect_value = reflect_deserializer.deserialize(&mut deserializer).unwrap();

    // Deserializing returns a `Box<dyn PartialReflect>` value.
    // Generally, deserializing a value will return the "dynamic" variant of a type.
    // For example, deserializing a struct will return the DynamicStruct type.
    // "Opaque types" will be deserialized as themselves.
    assert_eq!(
        reflect_value.reflect_type_path(),
        DynamicStruct::type_path(),
    );

    // Reflect has its own `partial_eq` implementation, named `reflect_partial_eq`. This behaves
    // like normal `partial_eq`, but it treats "dynamic" and "non-dynamic" types the same. The
    // `Foo` struct and deserialized `DynamicStruct` are considered equal for this reason:
    assert!(reflect_value.reflect_partial_eq(&value).unwrap());

    // By "patching" `Foo` with the deserialized DynamicStruct, we can "Deserialize" Foo.
    // This means we can serialize and deserialize with a single `Reflect` derive!
    value.apply(&*reflect_value);
}

examples/reflection/dynamic_types.rs (line 77)

fn main() {
    #[derive(Reflect, Default, PartialEq, Debug)]
    #[reflect(Identifiable, Default)]
    struct Player {
        id: u32,
    }

    #[reflect_trait]
    trait Identifiable {
        fn id(&self) -> u32;
    }

    impl Identifiable for Player {
        fn id(&self) -> u32 {
            self.id
        }
    }

    // Normally, when instantiating a type, you get back exactly that type.
    // This is because the type is known at compile time.
    // We call this the "concrete" or "canonical" type.
    let player: Player = Player { id: 123 };

    // When working with reflected types, however, we often "erase" this type information
    // using the `Reflect` trait object.
    // This trait object also gives us access to all the methods in the `PartialReflect` trait too.
    // The underlying type is still the same (in this case, `Player`),
    // but now we've hidden that information from the compiler.
    let reflected: Box<dyn Reflect> = Box::new(player);

    // Because it's the same type under the hood, we can still downcast it back to the original type.
    assert!(reflected.downcast_ref::<Player>().is_some());

    // We can attempt to clone our value using `PartialReflect::reflect_clone`.
    // This will recursively call `PartialReflect::reflect_clone` on all fields of the type.
    // Or, if we had registered `ReflectClone` using `#[reflect(Clone)]`, it would simply call `Clone::clone` directly.
    let cloned: Box<dyn Reflect> = reflected.reflect_clone().unwrap();
    assert_eq!(cloned.downcast_ref::<Player>(), Some(&Player { id: 123 }));

    // Another way we can "clone" our data is by converting it to a dynamic type.
    // Notice here we bind it as a `dyn PartialReflect` instead of `dyn Reflect`.
    // This is because it returns a dynamic type that simply represents the original type.
    // In this case, because `Player` is a struct, it will return a `DynamicStruct`.
    let dynamic: Box<dyn PartialReflect> = reflected.to_dynamic();
    assert!(dynamic.is_dynamic());

    // And if we try to convert it back to a `dyn Reflect` trait object, we'll get `None`.
    // Dynamic types cannot be directly cast to `dyn Reflect` trait objects.
    assert!(dynamic.try_as_reflect().is_none());

    // Generally dynamic types are used to represent (or "proxy") the original type,
    // so that we can continue to access its fields and overall structure.
    let dynamic_ref = dynamic.reflect_ref().as_struct().unwrap();
    let id = dynamic_ref.field("id").unwrap().try_downcast_ref::<u32>();
    assert_eq!(id, Some(&123));

    // It also enables us to create a representation of a type without having compile-time
    // access to the actual type. This is how the reflection deserializers work.
    // They generally can't know how to construct a type ahead of time,
    // so they instead build and return these dynamic representations.
    let input = "(id: 123)";
    let mut registry = TypeRegistry::default();
    registry.register::<Player>();
    let registration = registry.get(std::any::TypeId::of::<Player>()).unwrap();
    let deserialized = TypedReflectDeserializer::new(registration, &registry)
        .deserialize(&mut ron::Deserializer::from_str(input).unwrap())
        .unwrap();

    // Our deserialized output is a `DynamicStruct` that proxies/represents a `Player`.
    assert!(deserialized.represents::<Player>());

    // And while this does allow us to access the fields and structure of the type,
    // there may be instances where we need the actual type.
    // For example, if we want to convert our `dyn Reflect` into a `dyn Identifiable`,
    // we can't use the `DynamicStruct` proxy.
    let reflect_identifiable = registration
        .data::<ReflectIdentifiable>()
        .expect("`ReflectIdentifiable` should be registered");

    // Trying to access the registry with our `deserialized` will give a compile error
    // since it doesn't implement `Reflect`, only `PartialReflect`.
    // Similarly, trying to force the operation will fail.
    // This fails since the underlying type of `deserialized` is `DynamicStruct` and not `Player`.
    assert!(deserialized
        .try_as_reflect()
        .and_then(|reflect_trait_obj| reflect_identifiable.get(reflect_trait_obj))
        .is_none());

    // So how can we go from a dynamic type to a concrete type?
    // There are two ways:

    // 1. Using `PartialReflect::apply`.
    {
        // If you know the type at compile time, you can construct a new value and apply the dynamic
        // value to it.
        let mut value = Player::default();
        value.apply(deserialized.as_ref());
        assert_eq!(value.id, 123);

        // If you don't know the type at compile time, you need a dynamic way of constructing
        // an instance of the type. One such way is to use the `ReflectDefault` type data.
        let reflect_default = registration
            .data::<ReflectDefault>()
            .expect("`ReflectDefault` should be registered");

        let mut value: Box<dyn Reflect> = reflect_default.default();
        value.apply(deserialized.as_ref());

        let identifiable: &dyn Identifiable = reflect_identifiable.get(value.as_reflect()).unwrap();
        assert_eq!(identifiable.id(), 123);
    }

    // 2. Using `FromReflect`
    {
        // If you know the type at compile time, you can use the `FromReflect` trait to convert the
        // dynamic value into the concrete type directly.
        let value: Player = Player::from_reflect(deserialized.as_ref()).unwrap();
        assert_eq!(value.id, 123);

        // If you don't know the type at compile time, you can use the `ReflectFromReflect` type data
        // to perform the conversion dynamically.
        let reflect_from_reflect = registration
            .data::<ReflectFromReflect>()
            .expect("`ReflectFromReflect` should be registered");

        let value: Box<dyn Reflect> = reflect_from_reflect
            .from_reflect(deserialized.as_ref())
            .unwrap();
        let identifiable: &dyn Identifiable = reflect_identifiable.get(value.as_reflect()).unwrap();
        assert_eq!(identifiable.id(), 123);
    }

    // Lastly, while dynamic types are commonly generated via reflection methods like
    // `PartialReflect::to_dynamic` or via the reflection deserializers,
    // you can also construct them manually.
    let mut my_dynamic_list = DynamicList::from_iter([1u32, 2u32, 3u32]);

    // This is useful when you just need to apply some subset of changes to a type.
    let mut my_list: Vec<u32> = Vec::new();
    my_list.apply(&my_dynamic_list);
    assert_eq!(my_list, vec![1, 2, 3]);

    // And if you want it to actually proxy a type, you can configure it to do that as well:
    assert!(!my_dynamic_list
        .as_partial_reflect()
        .represents::<Vec<u32>>());
    my_dynamic_list.set_represented_type(Some(<Vec<u32>>::type_info()));
    assert!(my_dynamic_list
        .as_partial_reflect()
        .represents::<Vec<u32>>());

    // ============================= REFERENCE ============================= //
    // For reference, here are all the available dynamic types:

    // 1. `DynamicTuple`
    {
        let mut dynamic_tuple = DynamicTuple::default();
        dynamic_tuple.insert(1u32);
        dynamic_tuple.insert(2u32);
        dynamic_tuple.insert(3u32);

        let mut my_tuple: (u32, u32, u32) = (0, 0, 0);
        my_tuple.apply(&dynamic_tuple);
        assert_eq!(my_tuple, (1, 2, 3));
    }

    // 2. `DynamicArray`
    {
        let dynamic_array = DynamicArray::from_iter([1u32, 2u32, 3u32]);

        let mut my_array = [0u32; 3];
        my_array.apply(&dynamic_array);
        assert_eq!(my_array, [1, 2, 3]);
    }

    // 3. `DynamicList`
    {
        let dynamic_list = DynamicList::from_iter([1u32, 2u32, 3u32]);

        let mut my_list: Vec<u32> = Vec::new();
        my_list.apply(&dynamic_list);
        assert_eq!(my_list, vec![1, 2, 3]);
    }

    // 4. `DynamicSet`
    {
        let mut dynamic_set = DynamicSet::from_iter(["x", "y", "z"]);
        assert!(dynamic_set.contains(&"x"));

        dynamic_set.remove(&"y");

        let mut my_set: HashSet<&str> = HashSet::default();
        my_set.apply(&dynamic_set);
        assert_eq!(my_set, HashSet::from_iter(["x", "z"]));
    }

    // 5. `DynamicMap`
    {
        let dynamic_map = DynamicMap::from_iter([("x", 1u32), ("y", 2u32), ("z", 3u32)]);

        let mut my_map: HashMap<&str, u32> = HashMap::default();
        my_map.apply(&dynamic_map);
        assert_eq!(my_map.get("x"), Some(&1));
        assert_eq!(my_map.get("y"), Some(&2));
        assert_eq!(my_map.get("z"), Some(&3));
    }

    // 6. `DynamicStruct`
    {
        #[derive(Reflect, Default, Debug, PartialEq)]
        struct MyStruct {
            x: u32,
            y: u32,
            z: u32,
        }

        let mut dynamic_struct = DynamicStruct::default();
        dynamic_struct.insert("x", 1u32);
        dynamic_struct.insert("y", 2u32);
        dynamic_struct.insert("z", 3u32);

        let mut my_struct = MyStruct::default();
        my_struct.apply(&dynamic_struct);
        assert_eq!(my_struct, MyStruct { x: 1, y: 2, z: 3 });
    }

    // 7. `DynamicTupleStruct`
    {
        #[derive(Reflect, Default, Debug, PartialEq)]
        struct MyTupleStruct(u32, u32, u32);

        let mut dynamic_tuple_struct = DynamicTupleStruct::default();
        dynamic_tuple_struct.insert(1u32);
        dynamic_tuple_struct.insert(2u32);
        dynamic_tuple_struct.insert(3u32);

        let mut my_tuple_struct = MyTupleStruct::default();
        my_tuple_struct.apply(&dynamic_tuple_struct);
        assert_eq!(my_tuple_struct, MyTupleStruct(1, 2, 3));
    }

    // 8. `DynamicEnum`
    {
        #[derive(Reflect, Default, Debug, PartialEq)]
        enum MyEnum {
            #[default]
            Empty,
            Xyz(u32, u32, u32),
        }

        let mut values = DynamicTuple::default();
        values.insert(1u32);
        values.insert(2u32);
        values.insert(3u32);

        let dynamic_variant = DynamicVariant::Tuple(values);
        let dynamic_enum = DynamicEnum::new("Xyz", dynamic_variant);

        let mut my_enum = MyEnum::default();
        my_enum.apply(&dynamic_enum);
        assert_eq!(my_enum, MyEnum::Xyz(1, 2, 3));
    }
}

pub fn from_bytes(input: &'de [u8]) -> Result<Deserializer<'de>, SpannedError>

pub fn from_str_with_options( input: &'de str, options: Options, ) -> Result<Deserializer<'de>, SpannedError>

pub fn from_bytes_with_options( input: &'de [u8], options: Options, ) -> Result<Deserializer<'de>, SpannedError>

pub fn remainder(&self) -> Cow<'_, str>

pub fn span_error(&self, code: Error) -> SpannedError

impl<'de> Deserializer<'de>

pub fn end(&mut self) -> Result<(), Error>

Check if the remaining bytes are whitespace only, otherwise return an error.

Trait Implementations

impl<'de, 'a> Deserializer<'de> for &'a mut Deserializer<'de>

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_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_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 deserialize_i128<V>( self, visitor: V, ) -> Result<<V as Visitor<'de>>::Value, Self::Error>

where V: Visitor<'de>,

Hint that the Deserialize type is expecting an i128 value.

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

where V: Visitor<'de>,

Hint that the Deserialize type is expecting an u128 value.

fn is_human_readable(&self) -> bool

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