Struct DynamicEnum 

pub struct DynamicEnum { /* private fields */ }

A dynamic representation of an enum.

This allows for enums to be configured at runtime.

Example

// The original enum value
let mut value: Option<usize> = Some(123);

// Create a DynamicEnum to represent the new value
let mut dyn_enum = DynamicEnum::new(
  "None",
  DynamicVariant::Unit
);

// Apply the DynamicEnum as a patch to the original value
value.apply(dyn_enum.as_partial_reflect());

// Tada!
assert_eq!(None, value);

Implementations

impl DynamicEnum

pub fn new<I, V>(variant_name: I, variant: V) -> DynamicEnum

where I: Into<String>, V: Into<DynamicVariant>,

Create a new DynamicEnum to represent an enum at runtime.

Arguments

• variant_name: The name of the variant to set
• variant: The variant data

Examples found in repository

examples/reflection/dynamic_types.rs (line 268)

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 new_with_index<I, V>( variant_index: usize, variant_name: I, variant: V, ) -> DynamicEnum

where I: Into<String>, V: Into<DynamicVariant>,

Create a new DynamicEnum with a variant index to represent an enum at runtime.

Arguments

• variant_index: The index of the variant to set
• variant_name: The name of the variant to set
• variant: The variant data

pub fn set_represented_type( &mut self, represented_type: Option<&'static TypeInfo>, )

Sets the type to be represented by this DynamicEnum.

Panics

Panics if the given type is not a TypeInfo::Enum.

pub fn set_variant<I, V>(&mut self, name: I, variant: V)

where I: Into<String>, V: Into<DynamicVariant>,

Set the current enum variant represented by this struct.

pub fn set_variant_with_index<I, V>( &mut self, variant_index: usize, variant_name: I, variant: V, )

where I: Into<String>, V: Into<DynamicVariant>,

Set the current enum variant represented by this struct along with its variant index.

pub fn variant(&self) -> &DynamicVariant

Get a reference to the DynamicVariant contained in self.

pub fn variant_mut(&mut self) -> &mut DynamicVariant

Get a mutable reference to the DynamicVariant contained in self.

Using the mut reference to switch to a different variant will not update the internal tracking of the variant name and index.

If you want to switch variants, prefer one of the setters: DynamicEnum::set_variant or DynamicEnum::set_variant_with_index.

pub fn from<TEnum>(value: TEnum) -> DynamicEnum

where TEnum: Enum,

Create a DynamicEnum from an existing one.

This is functionally the same as DynamicEnum::from_ref except it takes an owned value.

pub fn from_ref<TEnum>(value: &TEnum) -> DynamicEnum

where TEnum: Enum + ?Sized,

Create a DynamicEnum from an existing one.

This is functionally the same as DynamicEnum::from except it takes a reference.

Trait Implementations

impl Debug for DynamicEnum

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

Formats the value using the given formatter.

impl Default for DynamicEnum

fn default() -> DynamicEnum

Returns the “default value” for a type.

impl Enum for DynamicEnum

fn field(&self, name: &str) -> Option<&(dyn PartialReflect + 'static)>

Returns a reference to the value of the field (in the current variant) with the given name.

fn field_at(&self, index: usize) -> Option<&(dyn PartialReflect + 'static)>

Returns a reference to the value of the field (in the current variant) at the given index.

fn field_mut( &mut self, name: &str, ) -> Option<&mut (dyn PartialReflect + 'static)>

Returns a mutable reference to the value of the field (in the current variant) with the given name.

fn field_at_mut( &mut self, index: usize, ) -> Option<&mut (dyn PartialReflect + 'static)>

Returns a mutable reference to the value of the field (in the current variant) at the given index.

fn index_of(&self, name: &str) -> Option<usize>

Returns the index of the field (in the current variant) with the given name.

fn name_at(&self, index: usize) -> Option<&str>

Returns the name of the field (in the current variant) with the given index.

fn iter_fields(&self) -> VariantFieldIter<'_>

Returns an iterator over the values of the current variant’s fields.

fn field_len(&self) -> usize

Returns the number of fields in the current variant.

fn variant_name(&self) -> &str

The name of the current variant.

fn variant_index(&self) -> usize

The index of the current variant.

fn variant_type(&self) -> VariantType

The type of the current variant.

fn to_dynamic_enum(&self) -> DynamicEnum

Creates a new DynamicEnum from this enum.

fn is_variant(&self, variant_type: VariantType) -> bool

Returns true if the current variant’s type matches the given one.

fn variant_path(&self) -> String

Returns the full path to the current variant.

fn get_represented_enum_info(&self) -> Option<&'static EnumInfo>

Will return None if TypeInfo is not available.

impl PartialReflect for DynamicEnum

fn get_represented_type_info(&self) -> Option<&'static TypeInfo>

Returns the TypeInfo of the type represented by this value.

fn into_partial_reflect(self: Box<DynamicEnum>) -> Box<dyn PartialReflect>

Casts this type to a boxed, reflected value.

fn as_partial_reflect(&self) -> &(dyn PartialReflect + 'static)

Casts this type to a reflected value.

fn as_partial_reflect_mut(&mut self) -> &mut (dyn PartialReflect + 'static)

Casts this type to a mutable, reflected value.

fn try_into_reflect( self: Box<DynamicEnum>, ) -> Result<Box<dyn Reflect>, Box<dyn PartialReflect>>

Attempts to cast this type to a boxed, fully-reflected value.

fn try_as_reflect(&self) -> Option<&(dyn Reflect + 'static)>

Attempts to cast this type to a fully-reflected value.

fn try_as_reflect_mut(&mut self) -> Option<&mut (dyn Reflect + 'static)>

Attempts to cast this type to a mutable, fully-reflected value.

fn try_apply( &mut self, value: &(dyn PartialReflect + 'static), ) -> Result<(), ApplyError>

Tries to apply a reflected value to this value.

fn reflect_kind(&self) -> ReflectKind

Returns a zero-sized enumeration of “kinds” of type.

fn reflect_ref(&self) -> ReflectRef<'_>

Returns an immutable enumeration of “kinds” of type.

fn reflect_mut(&mut self) -> ReflectMut<'_>

Returns a mutable enumeration of “kinds” of type.

fn reflect_owned(self: Box<DynamicEnum>) -> ReflectOwned

Returns an owned enumeration of “kinds” of type.

fn reflect_hash(&self) -> Option<u64>

Returns a hash of the value (which includes the type).

fn reflect_partial_eq( &self, value: &(dyn PartialReflect + 'static), ) -> Option<bool>

Returns a “partial equality” comparison result.

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

Debug formatter for the value.

fn is_dynamic(&self) -> bool

Indicates whether or not this type is a dynamic type.

fn apply(&mut self, value: &(dyn PartialReflect + 'static))

Applies a reflected value to this value.

fn to_dynamic(&self) -> Box<dyn PartialReflect>

Converts this reflected value into its dynamic representation based on its kind.

fn reflect_clone(&self) -> Result<Box<dyn Reflect>, ReflectCloneError>

Attempts to clone Self using reflection.

fn reflect_clone_and_take<T>(&self) -> Result<T, ReflectCloneError>

where T: 'static, Self: Sized + TypePath,

For a type implementing PartialReflect, combines reflect_clone and take in a useful fashion, automatically constructing an appropriate ReflectCloneError if the downcast fails.

impl TypePath for DynamicEnum

fn type_path() -> &'static str

Returns the fully qualified path of the underlying type.

fn short_type_path() -> &'static str

Returns a short, pretty-print enabled path to the type.

fn type_ident() -> Option<&'static str>

Returns the name of the type, or None if it is anonymous.

fn crate_name() -> Option<&'static str>

Returns the name of the crate the type is in, or None if it is anonymous.

fn module_path() -> Option<&'static str>

Returns the path to the module the type is in, or None if it is anonymous.