reorganize module

_archive/rhai_engine/rhaibook/rust/fallible.md

@@ -0,0 +1,54 @@
+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.
+~~~