55 lines
1.7 KiB
Markdown
55 lines
1.7 KiB
Markdown
Register a Fallible Rust Function
|
|
=================================
|
|
|
|
{{#include ../links.md}}
|
|
|
|
~~~admonish tip.side.wide "Tip: Consider `Dynamic`"
|
|
|
|
A lot of times it is not necessary to register fallible functions.
|
|
|
|
Simply have the function returns [`Dynamic`].
|
|
Upon error, return [`()`] which is idiomatic in Rhai.
|
|
|
|
See [here](dynamic-return.md) for more details.
|
|
~~~
|
|
|
|
If a function is _fallible_ (i.e. it returns a `Result<_, _>`), it can also be registered with via
|
|
`Engine::register_fn`.
|
|
|
|
The function must return `Result<T, Box<EvalAltResult>>` where `T` is any clonable type.
|
|
|
|
In other words, the error type _must_ be `Box<EvalAltResult>`. It is `Box`ed in order to reduce
|
|
the size of the `Result` type since the error path is rarely hit.
|
|
|
|
```rust
|
|
use rhai::{Engine, EvalAltResult};
|
|
|
|
// Function that may fail - the error type must be 'Box<EvalAltResult>'
|
|
fn safe_divide(x: i64, y: i64) -> Result<i64, Box<EvalAltResult>> {
|
|
if y == 0 {
|
|
// Return an error if y is zero
|
|
Err("Division by zero!".into()) // shortcut to create Box<EvalAltResult::ErrorRuntime>
|
|
} else {
|
|
Ok(x / y)
|
|
}
|
|
}
|
|
|
|
let mut engine = Engine::new();
|
|
|
|
engine.register_fn("divide", safe_divide);
|
|
|
|
if let Err(error) = engine.eval::<i64>("divide(40, 0)") {
|
|
println!("Error: {error:?}"); // prints ErrorRuntime("Division by zero detected!", (1, 1)")
|
|
}
|
|
```
|
|
|
|
|
|
~~~admonish tip.small "Tip: Create a `Box<EvalAltResult>`"
|
|
|
|
`Box<EvalAltResult>` implements `From<&str>` and `From<String>` etc.
|
|
and the error text gets converted into `Box<EvalAltResult::ErrorRuntime>`.
|
|
|
|
The error values are `Box`-ed in order to reduce memory footprint of the error path,
|
|
which should be hit rarely.
|
|
~~~
|