Out-of-Bounds Index for Arrays

Requires internals

This is an advanced feature that requires the internals feature to be enabled.

Normally, when an index is out-of-bounds for an array, an error is raised.

It is possible to completely control this behavior via a special callback function registered into an Engine via on_invalid_array_index.

Using this callback, for instance, it is simple to instruct Rhai to extend the array to accommodate this new element, or to return a default value instead of raising an error.

Function Signature

The function signature passed to Engine::on_invalid_array_index takes the following form.

Fn(array: &mut Array, index: i64, context: EvalContext) -> Result<Target, Box<EvalAltResult>>


array&mut Arraythe array being accessed
indexi64index value
contextEvalContextthe current evaluation context

Return value

The return value is Result<Target, Box<EvalAltResult>>.

Target is an advanced type, available only under the internals feature, that represents a reference to a Dynamic value.

It can be used to point to a particular value within the array or a new temporary value.


engine.on_invalid_array_index(|arr, index, _| {
    match index {
        -100 => {
            // The array can be modified in place

            // Return a mutable reference to an element
            let value_ref = arr.last_mut().unwrap();
        100 => {
            // Return a temporary value (not a reference)
            let value = Dynamic::from(100_i64);
        // Return the standard out-of-bounds error
        _ => Err(EvalAltResult::ErrorArrayBounds(
                arr.len(), index, Position::NONE