Values and Types

The following primitive types are supported natively.

CategoryEquivalent Rust typestype_of()to_string()
System integerrhai::INT (default i64, i32 under only_i32)"i32" or "i64""42", "123" etc.
Other integer numberu8, i8, u16, i16, u32, i32, u64, i64"i32", "u64" etc."42", "123" etc.
Integer numeric rangestd::ops::Range<rhai::INT>, std::ops::RangeInclusive<rhai::INT>"range", "range=""2..7", "0..=15" etc.
Floating-point number (disabled with no_float)rhai::FLOAT (default f64, f32 under f32_float)"f32" or "f64""123.4567" etc.
Fixed precision decimal number (requires decimal)rust_decimal::Decimal"decimal""42", "123.4567" etc.
Boolean valuebool"bool""true" or "false"
Unicode characterchar"char""A", "x" etc.
Immutable Unicode stringrhai::ImmutableString (Rc<SmartString>, Arc<SmartString> under sync)"string""hello" etc.
Array (disabled with no_index)rhai::Array (Vec<Dynamic>)"array""[ 1, 2, 3 ]" etc.
Byte array – BLOB (disabled with no_index)rhai::Blob (Vec<u8>)"blob""[01020304abcd]" etc.
Object map (disabled with no_object)rhai::Map (BTreeMap<SmartString, Dynamic>)"map""#{ "a": 1, "b": true }" etc.
Timestamp (disabled with no_time or no_std)std::time::Instant (instant::Instant if WASM build)"timestamp""<timestamp>"
Function pointerrhai::FnPtr"Fn""Fn(foo)" etc.
Dynamic value (i.e. can be anything)rhai::Dynamicthe actual typeactual value
Shared value (a reference-counted, shared Dynamic value, created via closures, disabled with no_closure)the actual typeactual value
Nothing/void/nil/null/Unit (or whatever it is called)()"()""" (empty string)

No automatic type conversion for integers

The various integer types are treated strictly distinct by Rhai, meaning that i32 and i64 and u32 and u8 are completely different.

They cannot even be added together or compared with each other.

Nor can a smaller integer type be up-casted to a larger integer type.

This is very similar to Rust.

Default Types

The default integer type is i64. If other integer types are not needed, it is possible to exclude them and make a smaller build with the only_i64 feature.

If only 32-bit integers are needed, enabling the only_i32 feature will remove support for all integer types other than i32, including i64. This is useful on some 32-bit targets where using 64-bit integers incur a performance penalty.

Warning: Default integer is i64

Rhai’s default integer type is i64, which is DIFFERENT from Rust’s i32.

It is very easy to unsuspectingly set an i32 into Rhai, which still works but will incur a significant runtime performance hit since the Engine will treat i32 as an opaque custom type (unless using the only_i32 feature).

i64 is the default even on 32-bit systems. To use i32 on 32-bit systems requires the only_i32 feature.

Tip: Floating-point numbers

If no floating-point is needed or supported, use the no_float feature to remove it.

Some applications require fixed-precision decimal numbers, which can be enabled via the decimal feature.

Immutable strings

Strings in Rhai are immutable, meaning that they can be shared but not modified.

Internally, the ImmutableString type is a wrapper over Rc<String> or Arc<String> (depending on sync).

Any modification done to a Rhai string causes the string to be cloned and the modifications made to the copy.

Tip: Convert to string

The to_string function converts a standard type into a string for display purposes.

The to_debug function converts a standard type into a string in debug format.