Struct DynamicFunctionMut

pub struct DynamicFunctionMut<'env> { /* private fields */ }

A dynamic representation of a function.

This type can be used to represent any callable that satisfies FnMut (or the reflection-based equivalent, ReflectFnMut). That is, any function or closure.

For functions that do not need to capture their environment mutably, it’s recommended to use DynamicFunction instead.

This type can be seen as a superset of DynamicFunction.

See the module-level documentation for more information.

You will generally not need to construct this manually. Instead, many functions and closures can be automatically converted using the IntoFunctionMut trait.

Example

Most of the time, a DynamicFunctionMut can be created using the IntoFunctionMut trait:

let mut list: Vec<i32> = vec![1, 2, 3];

// `replace` is a closure that captures a mutable reference to `list`
let mut replace = |index: usize, value: i32| -> i32 {
  let old_value = list[index];
  list[index] = value;
  old_value
};

// Since this closure mutably borrows data, we can't convert it into a regular `DynamicFunction`,
// as doing so would result in a compile-time error:
// let mut func: DynamicFunction = replace.into_function();

// Instead, we convert it into a `DynamicFunctionMut` using `IntoFunctionMut::into_function_mut`:
let mut func: DynamicFunctionMut = replace.into_function_mut();

// Dynamically call it:
let args = ArgList::default().with_owned(1_usize).with_owned(-2_i32);
let value = func.call(args).unwrap().unwrap_owned();

// Check the result:
assert_eq!(value.try_take::<i32>().unwrap(), 2);

// Note that `func` still has a reference to `list`,
// so we need to drop it before we can access `list` again.
// Alternatively, we could have invoked `func` with
// `DynamicFunctionMut::call_once` to immediately consume it.
drop(func);
assert_eq!(list, vec![1, -2, 3]);

Implementations

impl<'env> DynamicFunctionMut<'env>

pub fn new<F>( func: F, info: impl TryInto, ) -> DynamicFunctionMut<'env>

where F: for<'a> FnMut(ArgList<'a>) -> Result<Return<'a>, FunctionError> + 'env, <impl TryInto<FunctionInfo> as TryInto<FunctionInfo>>::Error: Debug,

Create a new DynamicFunctionMut.

The given function can be used to call out to any other callable, including functions, closures, or methods.

It’s important that the function signature matches the provided FunctionInfo. as this will be used to validate arguments when calling the function. This is also required in order for function overloading to work correctly.

Panics

This function may panic for any of the following reasons:

• No SignatureInfo is provided.
• A provided SignatureInfo has more arguments than ArgCount::MAX_COUNT.
• The conversion to FunctionInfo fails.

pub fn with_name( self, name: impl Into<Cow<'static, str>>, ) -> DynamicFunctionMut<'env>

Set the name of the function.

For DynamicFunctionMuts created using IntoFunctionMut, the default name will always be the full path to the function as returned by core::any::type_name, unless the function is a closure, anonymous function, or function pointer, in which case the name will be None.

pub fn with_overload<'a, F, Marker>(self, function: F) -> DynamicFunctionMut<'a>

where 'env: 'a, F: IntoFunctionMut<'a, Marker>,

Add an overload to this function.

Overloads allow a single DynamicFunctionMut to represent multiple functions of different signatures.

This can be used to handle multiple monomorphizations of a generic function or to allow functions with a variable number of arguments.

Any functions with the same argument signature will be overwritten by the one from the new function, F. For example, if the existing function had the signature (i32, i32) -> i32, and the new function, F, also had the signature (i32, i32) -> i32, the one from F would replace the one from the existing function.

Overloaded functions retain the name of the original function.

Note that it may be impossible to overload closures that mutably borrow from their environment due to Rust’s borrowing rules. However, it’s still possible to overload functions that do not capture their environment mutably, or those that maintain mutually exclusive mutable references to their environment.

Panics

Panics if the function, F, contains a signature already found in this function.

For a non-panicking version, see try_with_overload.

Example

let mut total_i32 = 0;
let mut add_i32 = |a: i32| total_i32 += a;

let mut total_f32 = 0.0;
let mut add_f32 = |a: f32| total_f32 += a;

// Currently, the only generic type `func` supports is `i32`.
let mut func = add_i32.into_function_mut();

// However, we can add an overload to handle `f32` as well:
func = func.with_overload(add_f32);

// Test `i32`:
let args = bevy_reflect::func::ArgList::new().with_owned(123_i32);
func.call(args).unwrap();

// Test `f32`:
let args = bevy_reflect::func::ArgList::new().with_owned(1.23_f32);
func.call(args).unwrap();

drop(func);
assert_eq!(total_i32, 123);
assert_eq!(total_f32, 1.23);

pub fn try_with_overload<F, Marker>( self, function: F, ) -> Result<DynamicFunctionMut<'env>, (Box<DynamicFunctionMut<'env>>, FunctionOverloadError)>

where F: IntoFunctionMut<'env, Marker>,

Attempt to add an overload to this function.

If the function, F, contains a signature already found in this function, an error will be returned along with the original function.

For a panicking version, see with_overload.

pub fn call<'a>( &mut self, args: ArgList<'a>, ) -> Result<Return<'a>, FunctionError>

Call the function with the given arguments.

Variables that are captured mutably by this function won’t be usable until this function is dropped. Consider using call_once if you want to consume the function immediately after calling it.

Example

let mut total = 0;
let add = |a: i32, b: i32| -> i32 {
  total = a + b;
  total
};

let mut func = add.into_function_mut().with_name("add");
let args = ArgList::new().with_owned(25_i32).with_owned(75_i32);
let result = func.call(args).unwrap().unwrap_owned();
assert_eq!(result.try_take::<i32>().unwrap(), 100);

Errors

This method will return an error if the number of arguments provided does not match the number of arguments expected by the function’s FunctionInfo.

The function itself may also return any errors it needs to.

pub fn call_once(self, args: ArgList<'_>) -> Result<Return<'_>, FunctionError>

Call the function with the given arguments and consume it.

This is useful for functions that capture their environment mutably because otherwise any captured variables would still be borrowed by it.

Example

let mut count = 0;
let increment = |amount: i32| count += amount;

let increment_function = increment.into_function_mut();
let args = ArgList::new().with_owned(5_i32);

// We need to drop `increment_function` here so that we
// can regain access to `count`.
// `call_once` does this automatically for us.
increment_function.call_once(args).unwrap();
assert_eq!(count, 5);

Errors

This method will return an error if the number of arguments provided does not match the number of arguments expected by the function’s FunctionInfo.

The function itself may also return any errors it needs to.

Examples found in repository

examples/reflection/function_reflection.rs (line 83)

fn main() {
    // There are times when it may be helpful to store a function away for later.
    // In Rust, we can do this by storing either a function pointer or a function trait object.
    // For example, say we wanted to store the following function:
    fn add(left: i32, right: i32) -> i32 {
        left + right
    }

    // We could store it as either of the following:
    let fn_pointer: fn(i32, i32) -> i32 = add;
    let fn_trait_object: Box<dyn Fn(i32, i32) -> i32> = Box::new(add);

    // And we can call them like so:
    let result = fn_pointer(2, 2);
    assert_eq!(result, 4);
    let result = fn_trait_object(2, 2);
    assert_eq!(result, 4);

    // However, you'll notice that we have to know the types of the arguments and return value at compile time.
    // This means there's not really a way to store or call these functions dynamically at runtime.
    // Luckily, Bevy's reflection crate comes with a set of tools for doing just that!
    // We do this by first converting our function into the reflection-based `DynamicFunction` type
    // using the `IntoFunction` trait.
    let function: DynamicFunction<'static> = dbg!(add.into_function());

    // This time, you'll notice that `DynamicFunction` doesn't take any information about the function's arguments or return value.
    // This is because `DynamicFunction` checks the types of the arguments and return value at runtime.
    // Now we can generate a list of arguments:
    let args: ArgList = dbg!(ArgList::new().with_owned(2_i32).with_owned(2_i32));

    // And finally, we can call the function.
    // This returns a `Result` indicating whether the function was called successfully.
    // For now, we'll just unwrap it to get our `Return` value,
    // which is an enum containing the function's return value.
    let return_value: Return = dbg!(function.call(args).unwrap());

    // The `Return` value can be pattern matched or unwrapped to get the underlying reflection data.
    // For the sake of brevity, we'll just unwrap it here and downcast it to the expected type of `i32`.
    let value: Box<dyn PartialReflect> = return_value.unwrap_owned();
    assert_eq!(value.try_take::<i32>().unwrap(), 4);

    // The same can also be done for closures that capture references to their environment.
    // Closures that capture their environment immutably can be converted into a `DynamicFunction`
    // using the `IntoFunction` trait.
    let minimum = 5;
    let clamp = |value: i32| value.max(minimum);

    let function: DynamicFunction = dbg!(clamp.into_function());
    let args = dbg!(ArgList::new().with_owned(2_i32));
    let return_value = dbg!(function.call(args).unwrap());
    let value: Box<dyn PartialReflect> = return_value.unwrap_owned();
    assert_eq!(value.try_take::<i32>().unwrap(), 5);

    // We can also handle closures that capture their environment mutably
    // using the `IntoFunctionMut` trait.
    let mut count = 0;
    let increment = |amount: i32| count += amount;

    let closure: DynamicFunctionMut = dbg!(increment.into_function_mut());
    let args = dbg!(ArgList::new().with_owned(5_i32));

    // Because `DynamicFunctionMut` mutably borrows `total`,
    // it will need to be dropped before `total` can be accessed again.
    // This can be done manually with `drop(closure)` or by using the `DynamicFunctionMut::call_once` method.
    dbg!(closure.call_once(args).unwrap());
    assert_eq!(count, 5);

    // Generic functions can also be converted into a `DynamicFunction`,
    // however, they will need to be manually monomorphized first.
    fn stringify<T: ToString>(value: T) -> String {
        value.to_string()
    }

    // We have to manually specify the concrete generic type we want to use.
    let function = stringify::<i32>.into_function();

    let args = ArgList::new().with_owned(123_i32);
    let return_value = function.call(args).unwrap();
    let value: Box<dyn PartialReflect> = return_value.unwrap_owned();
    assert_eq!(value.try_take::<String>().unwrap(), "123");

    // To make things a little easier, we can also "overload" functions.
    // This makes it so that a single `DynamicFunction` can represent multiple functions,
    // and the correct one is chosen based on the types of the arguments.
    // Each function overload must have a unique argument signature.
    let function = stringify::<i32>
        .into_function()
        .with_overload(stringify::<f32>);

    // Now our `function` accepts both `i32` and `f32` arguments.
    let args = ArgList::new().with_owned(1.23_f32);
    let return_value = function.call(args).unwrap();
    let value: Box<dyn PartialReflect> = return_value.unwrap_owned();
    assert_eq!(value.try_take::<String>().unwrap(), "1.23");

    // Function overloading even allows us to have a variable number of arguments.
    let function = (|| 0)
        .into_function()
        .with_overload(|a: i32| a)
        .with_overload(|a: i32, b: i32| a + b)
        .with_overload(|a: i32, b: i32, c: i32| a + b + c);

    let args = ArgList::new()
        .with_owned(1_i32)
        .with_owned(2_i32)
        .with_owned(3_i32);
    let return_value = function.call(args).unwrap();
    let value: Box<dyn PartialReflect> = return_value.unwrap_owned();
    assert_eq!(value.try_take::<i32>().unwrap(), 6);

    // As stated earlier, `IntoFunction` works for many kinds of simple functions.
    // Functions with non-reflectable arguments or return values may not be able to be converted.
    // Generic functions are also not supported (unless manually monomorphized like `foo::<i32>.into_function()`).
    // Additionally, the lifetime of the return value is tied to the lifetime of the first argument.
    // However, this means that many methods (i.e. functions with a `self` parameter) are also supported:
    #[derive(Reflect, Default)]
    struct Data {
        value: String,
    }

    impl Data {
        fn set_value(&mut self, value: String) {
            self.value = value;
        }

        // Note that only `&'static str` implements `Reflect`.
        // To get around this limitation we can use `&String` instead.
        fn get_value(&self) -> &String {
            &self.value
        }
    }

    let mut data = Data::default();

    let set_value = dbg!(Data::set_value.into_function());
    let args = dbg!(ArgList::new().with_mut(&mut data)).with_owned(String::from("Hello, world!"));
    dbg!(set_value.call(args).unwrap());
    assert_eq!(data.value, "Hello, world!");

    let get_value = dbg!(Data::get_value.into_function());
    let args = dbg!(ArgList::new().with_ref(&data));
    let return_value = dbg!(get_value.call(args).unwrap());
    let value: &dyn PartialReflect = return_value.unwrap_ref();
    assert_eq!(value.try_downcast_ref::<String>().unwrap(), "Hello, world!");

    // For more complex use cases, you can always create a custom `DynamicFunction` manually.
    // This is useful for functions that can't be converted via the `IntoFunction` trait.
    // For example, this function doesn't implement `IntoFunction` due to the fact that
    // the lifetime of the return value is not tied to the lifetime of the first argument.
    fn get_or_insert(value: i32, container: &mut Option<i32>) -> &i32 {
        if container.is_none() {
            *container = Some(value);
        }

        container.as_ref().unwrap()
    }

    let get_or_insert_function = dbg!(DynamicFunction::new(
        |mut args: ArgList| -> FunctionResult {
            // The `ArgList` contains the arguments in the order they were pushed.
            // The `DynamicFunction` will validate that the list contains
            // exactly the number of arguments we expect.
            // We can retrieve them out in order (note that this modifies the `ArgList`):
            let value = args.take::<i32>()?;
            let container = args.take::<&mut Option<i32>>()?;

            // We could have also done the following to make use of type inference:
            // let value = args.take_owned()?;
            // let container = args.take_mut()?;

            Ok(Return::Ref(get_or_insert(value, container)))
        },
        // Functions can be either anonymous or named.
        // It's good practice, though, to try and name your functions whenever possible.
        // This makes it easier to debug and is also required for function registration.
        // We can either give it a custom name or use the function's type name as
        // derived from `std::any::type_name_of_val`.
        SignatureInfo::named(std::any::type_name_of_val(&get_or_insert))
            // We can always change the name if needed.
            // It's a good idea to also ensure that the name is unique,
            // such as by using its type name or by prefixing it with your crate name.
            .with_name("my_crate::get_or_insert")
            // Since our function takes arguments, we should provide that argument information.
            // This is used to validate arguments when calling the function.
            // And it aids consumers of the function with their own validation and debugging.
            // Arguments should be provided in the order they are defined in the function.
            .with_arg::<i32>("value")
            .with_arg::<&mut Option<i32>>("container")
            // We can provide return information as well.
            .with_return::<&i32>(),
    ));

    let mut container: Option<i32> = None;

    let args = dbg!(ArgList::new().with_owned(5_i32).with_mut(&mut container));
    let value = dbg!(get_or_insert_function.call(args).unwrap()).unwrap_ref();
    assert_eq!(value.try_downcast_ref::<i32>(), Some(&5));

    let args = dbg!(ArgList::new().with_owned(500_i32).with_mut(&mut container));
    let value = dbg!(get_or_insert_function.call(args).unwrap()).unwrap_ref();
    assert_eq!(value.try_downcast_ref::<i32>(), Some(&5));
}

pub fn info(&self) -> &FunctionInfo

Returns the function info.

pub fn name(&self) -> Option<&Cow<'static, str>>

The name of the function.

For DynamicFunctionMuts created using IntoFunctionMut, the default name will always be the full path to the function as returned by core::any::type_name, unless the function is a closure, anonymous function, or function pointer, in which case the name will be None.

This can be overridden using with_name.

pub fn is_overloaded(&self) -> bool

Returns true if the function is overloaded.

Example

let mut total_i32 = 0;
let increment = (|value: i32| total_i32 += value).into_function_mut();
assert!(!increment.is_overloaded());

let mut total_f32 = 0.0;
let increment = increment.with_overload(|value: f32| total_f32 += value);
assert!(increment.is_overloaded());

pub fn arg_count(&self) -> ArgCount

Returns the number of arguments the function expects.

For overloaded functions that can have a variable number of arguments, this will contain the full set of counts for all signatures.

Example

let add = (|a: i32, b: i32| a + b).into_function_mut();
assert!(add.arg_count().contains(2));

let add = add.with_overload(|a: f32, b: f32, c: f32| a + b + c);
assert!(add.arg_count().contains(2));
assert!(add.arg_count().contains(3));

Trait Implementations

impl<'env> Debug for DynamicFunctionMut<'env>

Outputs the function’s signature.

This takes the format: DynamicFunctionMut(fn {name}({arg1}: {type1}, {arg2}: {type2}, ...) -> {return_type}).

Names for arguments and the function itself are optional and will default to _ if not provided.

If the function is overloaded, the output will include the signatures of all overloads as a set. For example, DynamicFunctionMut(fn add{(_: i32, _: i32) -> i32, (_: f32, _: f32) -> f32}).

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

Formats the value using the given formatter.

impl<'env> From<DynamicFunction<'env>> for DynamicFunctionMut<'env>

fn from(function: DynamicFunction<'env>) -> DynamicFunctionMut<'env>

Converts to this type from the input type.

impl<'env> IntoFunctionMut<'env, ()> for DynamicFunctionMut<'env>

fn into_function_mut(self) -> DynamicFunctionMut<'env>

Converts Self into a DynamicFunctionMut.