Values and Types
The following primitive types are supported natively.
| Category | Equivalent Rust types | type_of() | to_string() |
|---|---|---|---|
| System integer | rhai::INT (default i64, i32 under only_i32) | "i32" or "i64" | "42", "123" etc. |
| Other integer number | u8, i8, u16, i16, u32, i32, u64, i64 | "i32", "u64" etc. | "42", "123" etc. |
| Integer numeric range | std::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 value | bool | "bool" | "true" or "false" |
| Unicode character | char | "char" | "A", "x" etc. |
| Immutable Unicode string | rhai::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 pointer | rhai::FnPtr | "Fn" | "Fn(foo)" etc. |
| Dynamic value (i.e. can be anything) | rhai::Dynamic | the actual type | actual value |
Shared value (a reference-counted, shared Dynamic value, created via closures, disabled with no_closure) | the actual type | actual value | |
| Nothing/void/nil/null/Unit (or whatever it is called) | () | "()" | "" (empty string) |
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.
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.
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.