2017-10-28 22:33:00 +02:00
|
|
|
//! # Rhai - embedded scripting for Rust
|
2017-12-20 12:16:14 +01:00
|
|
|
//!
|
2021-01-30 00:19:54 +01:00
|
|
|
//! ![Rhai logo](https://rhai.rs/book/images/logo/rhai-banner-transparent-colour.svg)
|
2020-12-24 09:32:43 +01:00
|
|
|
//!
|
2020-10-10 07:41:55 +02:00
|
|
|
//! Rhai is a tiny, simple and fast embedded scripting language for Rust
|
2017-10-28 22:33:00 +02:00
|
|
|
//! that gives you a safe and easy way to add scripting to your applications.
|
2020-04-09 04:38:33 +02:00
|
|
|
//!
|
2020-12-24 09:32:43 +01:00
|
|
|
//! It provides a familiar syntax based on JavaScript+Rust and a simple Rust interface.
|
|
|
|
//!
|
|
|
|
//! # A Quick Example
|
|
|
|
//!
|
|
|
|
//! ## Contents of `my_script.rhai`
|
2017-12-20 12:16:14 +01:00
|
|
|
//!
|
2021-03-22 04:18:09 +01:00
|
|
|
//! ```ignore
|
2020-12-24 09:32:43 +01:00
|
|
|
//! /// Brute force factorial function
|
2017-10-28 22:33:00 +02:00
|
|
|
//! fn factorial(x) {
|
|
|
|
//! if x == 1 { return 1; }
|
2020-03-24 09:57:35 +01:00
|
|
|
//! x * factorial(x - 1)
|
2017-10-28 22:33:00 +02:00
|
|
|
//! }
|
|
|
|
//!
|
2020-04-09 04:38:33 +02:00
|
|
|
//! // Calling an external function 'compute'
|
|
|
|
//! compute(factorial(10))
|
2017-10-28 22:33:00 +02:00
|
|
|
//! ```
|
2017-12-20 12:16:14 +01:00
|
|
|
//!
|
2020-12-24 09:32:43 +01:00
|
|
|
//! ## The Rust part
|
2017-12-20 12:16:14 +01:00
|
|
|
//!
|
2021-03-22 04:18:09 +01:00
|
|
|
//! ```no_run
|
2021-03-15 04:36:30 +01:00
|
|
|
//! use rhai::{Engine, EvalAltResult};
|
2017-12-20 12:16:14 +01:00
|
|
|
//!
|
2020-04-21 17:25:12 +02:00
|
|
|
//! fn main() -> Result<(), Box<EvalAltResult>>
|
2020-03-09 14:09:53 +01:00
|
|
|
//! {
|
2020-04-09 04:38:33 +02:00
|
|
|
//! // Define external function
|
2020-03-09 14:09:53 +01:00
|
|
|
//! fn compute_something(x: i64) -> bool {
|
2020-03-24 09:57:35 +01:00
|
|
|
//! (x % 40) == 0
|
2020-03-09 14:09:53 +01:00
|
|
|
//! }
|
|
|
|
//!
|
2020-04-09 04:38:33 +02:00
|
|
|
//! // Create scripting engine
|
2020-03-09 14:09:53 +01:00
|
|
|
//! let mut engine = Engine::new();
|
|
|
|
//!
|
2020-04-09 04:38:33 +02:00
|
|
|
//! // Register external function as 'compute'
|
|
|
|
//! engine.register_fn("compute", compute_something);
|
2017-12-20 12:16:14 +01:00
|
|
|
//!
|
2020-04-07 07:23:06 +02:00
|
|
|
//! # #[cfg(not(feature = "no_std"))]
|
2022-01-12 01:12:28 +01:00
|
|
|
//! # #[cfg(not(target_family = "wasm"))]
|
|
|
|
//! #
|
2021-12-26 05:16:48 +01:00
|
|
|
//! // Evaluate the script, expecting a 'bool' result
|
|
|
|
//! let result = engine.eval_file::<bool>("my_script.rhai".into())?;
|
2021-12-25 16:49:14 +01:00
|
|
|
//!
|
|
|
|
//! assert_eq!(result, true);
|
2020-03-09 14:09:53 +01:00
|
|
|
//!
|
|
|
|
//! Ok(())
|
|
|
|
//! }
|
2017-10-28 22:33:00 +02:00
|
|
|
//! ```
|
|
|
|
//!
|
2020-07-29 16:43:50 +02:00
|
|
|
//! # Documentation
|
2020-04-03 13:42:01 +02:00
|
|
|
//!
|
2021-01-30 00:19:54 +01:00
|
|
|
//! See [The Rhai Book](https://rhai.rs/book) for details on the Rhai scripting engine and language.
|
2016-03-03 16:55:28 +01:00
|
|
|
|
2020-03-18 05:04:26 +01:00
|
|
|
#![cfg_attr(feature = "no_std", no_std)]
|
2017-10-02 23:44:45 +02:00
|
|
|
|
2020-03-18 05:04:26 +01:00
|
|
|
#[cfg(feature = "no_std")]
|
2020-03-17 19:26:11 +01:00
|
|
|
extern crate alloc;
|
|
|
|
|
2021-04-17 09:15:54 +02:00
|
|
|
#[cfg(feature = "no_std")]
|
|
|
|
extern crate no_std_compat as std;
|
|
|
|
|
|
|
|
#[cfg(feature = "no_std")]
|
|
|
|
use std::prelude::v1::*;
|
|
|
|
|
2021-02-19 08:49:51 +01:00
|
|
|
// Internal modules
|
|
|
|
|
2021-11-13 15:36:23 +01:00
|
|
|
mod api;
|
2020-10-28 15:18:44 +01:00
|
|
|
mod ast;
|
2016-03-03 16:55:28 +01:00
|
|
|
mod engine;
|
2022-01-07 04:43:47 +01:00
|
|
|
mod eval;
|
2021-11-13 15:36:23 +01:00
|
|
|
mod func;
|
2020-05-05 06:24:13 +02:00
|
|
|
mod module;
|
2021-11-13 15:36:23 +01:00
|
|
|
mod optimizer;
|
2020-04-20 18:11:25 +02:00
|
|
|
pub mod packages;
|
2021-11-13 15:36:23 +01:00
|
|
|
mod parser;
|
2021-09-07 16:12:04 +02:00
|
|
|
mod tests;
|
2021-11-13 15:36:23 +01:00
|
|
|
mod tokenizer;
|
|
|
|
mod types;
|
2020-05-14 12:27:22 +02:00
|
|
|
mod r#unsafe;
|
2016-03-03 16:55:28 +01:00
|
|
|
|
2021-12-27 05:27:31 +01:00
|
|
|
/// Error encountered when parsing a script.
|
|
|
|
type PERR = ParseErrorType;
|
|
|
|
/// Evaluation result.
|
|
|
|
type ERR = EvalAltResult;
|
2021-12-25 16:49:14 +01:00
|
|
|
/// General evaluation error for Rhai scripts.
|
2021-12-27 05:27:31 +01:00
|
|
|
type RhaiError = Box<ERR>;
|
2021-12-25 16:49:14 +01:00
|
|
|
/// Generic [`Result`] type for Rhai functions.
|
|
|
|
type RhaiResultOf<T> = Result<T, RhaiError>;
|
|
|
|
/// General [`Result`] type for Rhai functions returning [`Dynamic`] values.
|
|
|
|
type RhaiResult = RhaiResultOf<Dynamic>;
|
2021-03-02 08:02:28 +01:00
|
|
|
|
2020-11-25 02:36:06 +01:00
|
|
|
/// The system integer type. It is defined as [`i64`].
|
2020-10-29 04:37:51 +01:00
|
|
|
///
|
2020-11-25 02:36:06 +01:00
|
|
|
/// If the `only_i32` feature is enabled, this will be [`i32`] instead.
|
2020-10-29 04:37:51 +01:00
|
|
|
#[cfg(not(feature = "only_i32"))]
|
|
|
|
pub type INT = i64;
|
|
|
|
|
|
|
|
/// The system integer type.
|
2020-11-25 02:36:06 +01:00
|
|
|
/// It is defined as [`i32`] since the `only_i32` feature is used.
|
2020-10-29 04:37:51 +01:00
|
|
|
///
|
2020-11-25 02:36:06 +01:00
|
|
|
/// If the `only_i32` feature is not used, this will be `i64` instead.
|
2020-10-29 04:37:51 +01:00
|
|
|
#[cfg(feature = "only_i32")]
|
|
|
|
pub type INT = i32;
|
|
|
|
|
2021-12-31 16:01:34 +01:00
|
|
|
/// The unsigned system base integer type. It is defined as [`u64`].
|
2021-12-18 10:07:30 +01:00
|
|
|
///
|
|
|
|
/// If the `only_i32` feature is enabled, this will be [`u32`] instead.
|
|
|
|
#[cfg(not(feature = "only_i32"))]
|
|
|
|
#[allow(non_camel_case_types)]
|
2022-01-13 15:51:56 +01:00
|
|
|
type UNSIGNED_INT = u64;
|
|
|
|
|
2021-12-31 16:01:34 +01:00
|
|
|
/// The unsigned system integer base type.
|
2021-12-18 10:07:30 +01:00
|
|
|
/// It is defined as [`u32`] since the `only_i32` feature is used.
|
|
|
|
///
|
|
|
|
/// If the `only_i32` feature is not used, this will be `u64` instead.
|
|
|
|
#[cfg(feature = "only_i32")]
|
|
|
|
#[allow(non_camel_case_types)]
|
2021-12-31 16:01:34 +01:00
|
|
|
type UNSIGNED_INT = u32;
|
2021-12-18 10:07:30 +01:00
|
|
|
|
2020-11-25 02:36:06 +01:00
|
|
|
/// The system floating-point type. It is defined as [`f64`].
|
2021-04-17 06:03:29 +02:00
|
|
|
/// Not available under `no_float`.
|
2020-11-25 02:36:06 +01:00
|
|
|
///
|
2021-10-22 04:43:30 +02:00
|
|
|
/// If the `f32_float` feature is enabled, this will be [`f32`] instead.
|
2020-10-29 04:37:51 +01:00
|
|
|
#[cfg(not(feature = "no_float"))]
|
2020-11-01 08:48:48 +01:00
|
|
|
#[cfg(not(feature = "f32_float"))]
|
2020-10-29 04:37:51 +01:00
|
|
|
pub type FLOAT = f64;
|
|
|
|
|
2020-11-01 08:48:48 +01:00
|
|
|
/// The system floating-point type.
|
2020-11-25 02:36:06 +01:00
|
|
|
/// It is defined as [`f32`] since the `f32_float` feature is used.
|
2021-04-17 06:03:29 +02:00
|
|
|
/// Not available under `no_float`.
|
2020-11-25 02:36:06 +01:00
|
|
|
///
|
|
|
|
/// If the `f32_float` feature is not used, this will be `f64` instead.
|
2020-11-01 08:48:48 +01:00
|
|
|
#[cfg(not(feature = "no_float"))]
|
|
|
|
#[cfg(feature = "f32_float")]
|
|
|
|
pub type FLOAT = f32;
|
|
|
|
|
2021-12-31 16:01:34 +01:00
|
|
|
/// An exclusive integer range.
|
|
|
|
type ExclusiveRange = std::ops::Range<INT>;
|
|
|
|
|
|
|
|
/// An inclusive integer range.
|
|
|
|
type InclusiveRange = std::ops::RangeInclusive<INT>;
|
2021-12-15 05:06:17 +01:00
|
|
|
|
2021-12-27 15:02:34 +01:00
|
|
|
pub use api::custom_syntax::Expression;
|
2021-03-07 15:10:54 +01:00
|
|
|
pub use ast::{FnAccess, AST};
|
2022-01-07 04:43:47 +01:00
|
|
|
pub use engine::{Engine, OP_CONTAINS, OP_EQUALS};
|
|
|
|
pub use eval::EvalContext;
|
2021-11-16 05:26:37 +01:00
|
|
|
pub use func::{NativeCallContext, RegisterNativeFunction};
|
2020-11-17 05:23:53 +01:00
|
|
|
pub use module::{FnNamespace, Module};
|
2021-11-13 15:36:23 +01:00
|
|
|
pub use tokenizer::Position;
|
|
|
|
pub use types::{
|
2021-11-16 05:26:37 +01:00
|
|
|
Dynamic, EvalAltResult, FnPtr, ImmutableString, LexError, ParseError, ParseErrorType, Scope,
|
2021-11-13 15:36:23 +01:00
|
|
|
};
|
2020-09-25 04:59:21 +02:00
|
|
|
|
2021-06-16 12:58:48 +02:00
|
|
|
/// An identifier in Rhai. [`SmartString`](https://crates.io/crates/smartstring) is used because most
|
|
|
|
/// identifiers are ASCII and short, fewer than 23 characters, so they can be stored inline.
|
|
|
|
#[cfg(not(feature = "internals"))]
|
|
|
|
pub(crate) type Identifier = SmartString;
|
|
|
|
|
|
|
|
/// An identifier in Rhai. [`SmartString`](https://crates.io/crates/smartstring) is used because most
|
|
|
|
/// identifiers are ASCII and short, fewer than 23 characters, so they can be stored inline.
|
|
|
|
#[cfg(feature = "internals")]
|
|
|
|
pub type Identifier = SmartString;
|
|
|
|
|
2021-03-04 07:08:11 +01:00
|
|
|
/// Alias to [`Rc`][std::rc::Rc] or [`Arc`][std::sync::Arc] depending on the `sync` feature flag.
|
2021-11-16 05:26:37 +01:00
|
|
|
pub use func::Shared;
|
2021-03-04 07:08:11 +01:00
|
|
|
|
2021-11-13 15:36:23 +01:00
|
|
|
/// Alias to [`RefCell`][std::cell::RefCell] or [`RwLock`][std::sync::RwLock] depending on the `sync` feature flag.
|
2021-11-16 05:26:37 +01:00
|
|
|
pub use func::Locked;
|
2020-11-16 09:28:04 +01:00
|
|
|
|
2021-11-16 05:26:37 +01:00
|
|
|
pub(crate) use func::{
|
2021-06-30 10:28:37 +02:00
|
|
|
calc_fn_hash, calc_fn_params_hash, calc_qualified_fn_hash, calc_qualified_var_hash,
|
|
|
|
combine_hashes,
|
2021-06-16 12:36:33 +02:00
|
|
|
};
|
2020-09-25 04:59:21 +02:00
|
|
|
|
2020-08-01 18:52:26 +02:00
|
|
|
pub use rhai_codegen::*;
|
|
|
|
|
2021-11-27 16:20:05 +01:00
|
|
|
pub use func::{plugin, FuncArgs};
|
2020-04-08 17:01:48 +02:00
|
|
|
|
2021-01-28 09:48:56 +01:00
|
|
|
#[cfg(not(feature = "no_function"))]
|
2021-11-27 16:20:05 +01:00
|
|
|
pub use func::Func;
|
2021-01-28 09:48:56 +01:00
|
|
|
|
2021-03-07 15:10:54 +01:00
|
|
|
#[cfg(not(feature = "no_function"))]
|
|
|
|
pub use ast::ScriptFnMetadata;
|
|
|
|
|
2020-11-25 02:36:06 +01:00
|
|
|
/// Variable-sized array of [`Dynamic`] values.
|
2021-01-02 16:30:10 +01:00
|
|
|
/// Not available under `no_index`.
|
2020-03-10 10:10:33 +01:00
|
|
|
#[cfg(not(feature = "no_index"))]
|
2021-04-17 09:15:54 +02:00
|
|
|
pub type Array = Vec<Dynamic>;
|
2020-03-14 13:06:40 +01:00
|
|
|
|
2021-11-23 07:58:54 +01:00
|
|
|
/// Variable-sized array of [`u8`] values (byte array).
|
|
|
|
/// Not available under `no_index`.
|
|
|
|
#[cfg(not(feature = "no_index"))]
|
|
|
|
pub type Blob = Vec<u8>;
|
|
|
|
|
2021-12-31 16:01:34 +01:00
|
|
|
/// A dictionary of [`Dynamic`] values with string keys.
|
2021-01-02 16:30:10 +01:00
|
|
|
/// Not available under `no_object`.
|
2021-12-31 16:01:34 +01:00
|
|
|
///
|
|
|
|
/// [`SmartString`](https://crates.io/crates/smartstring) is used as the key type because most
|
|
|
|
/// property names are ASCII and short, fewer than 23 characters, so they can be stored inline.
|
2020-03-29 17:53:35 +02:00
|
|
|
#[cfg(not(feature = "no_object"))]
|
2021-04-17 09:15:54 +02:00
|
|
|
pub type Map = std::collections::BTreeMap<Identifier, Dynamic>;
|
2020-03-29 17:53:35 +02:00
|
|
|
|
2020-05-05 09:00:10 +02:00
|
|
|
#[cfg(not(feature = "no_module"))]
|
2020-05-13 13:21:42 +02:00
|
|
|
pub use module::ModuleResolver;
|
2020-05-05 17:57:25 +02:00
|
|
|
|
2020-05-15 15:40:54 +02:00
|
|
|
/// Module containing all built-in _module resolvers_ available to Rhai.
|
2020-05-05 17:57:25 +02:00
|
|
|
#[cfg(not(feature = "no_module"))]
|
2021-01-28 09:48:56 +01:00
|
|
|
pub use module::resolvers as module_resolvers;
|
2020-05-05 09:00:10 +02:00
|
|
|
|
2020-07-03 11:19:55 +02:00
|
|
|
#[cfg(feature = "serde")]
|
2021-02-19 08:17:14 +01:00
|
|
|
pub mod serde;
|
2020-07-03 11:19:55 +02:00
|
|
|
|
2020-03-15 15:39:58 +01:00
|
|
|
#[cfg(not(feature = "no_optimize"))]
|
2021-11-13 15:36:23 +01:00
|
|
|
pub use optimizer::OptimizationLevel;
|
|
|
|
|
|
|
|
// Expose internal data structures.
|
2020-06-23 04:43:24 +02:00
|
|
|
|
2021-03-05 07:18:36 +01:00
|
|
|
#[cfg(feature = "internals")]
|
2021-11-13 15:36:23 +01:00
|
|
|
pub use types::dynamic::{AccessMode, DynamicReadLock, DynamicWriteLock, Variant};
|
2021-03-05 07:18:36 +01:00
|
|
|
|
2021-05-10 05:07:19 +02:00
|
|
|
#[cfg(feature = "internals")]
|
2021-11-13 15:36:23 +01:00
|
|
|
pub use tokenizer::{get_next_token, parse_string_literal};
|
2021-05-10 05:07:19 +02:00
|
|
|
|
2020-06-23 04:43:24 +02:00
|
|
|
#[cfg(feature = "internals")]
|
2021-11-13 15:36:23 +01:00
|
|
|
pub use tokenizer::{
|
2021-09-24 03:26:35 +02:00
|
|
|
InputStream, MultiInputsStream, Token, TokenIterator, TokenizeState, TokenizerControl,
|
|
|
|
TokenizerControlBlock,
|
|
|
|
};
|
|
|
|
|
|
|
|
#[cfg(feature = "internals")]
|
2021-12-27 14:56:50 +01:00
|
|
|
pub use types::StringsInterner;
|
|
|
|
|
|
|
|
#[cfg(feature = "internals")]
|
|
|
|
pub use parser::ParseState;
|
2020-06-23 04:43:24 +02:00
|
|
|
|
|
|
|
#[cfg(feature = "internals")]
|
2021-01-04 04:58:24 +01:00
|
|
|
pub use ast::{
|
2021-09-04 12:43:18 +02:00
|
|
|
ASTNode, BinaryExpr, CustomExpr, Expr, FnCallExpr, FnCallHashes, Ident, OpAssignment,
|
2021-09-19 16:44:27 +02:00
|
|
|
OptionFlags, ScriptFnDef, Stmt, StmtBlock, AST_OPTION_FLAGS::*,
|
2021-01-04 04:58:24 +01:00
|
|
|
};
|
2020-07-09 13:54:28 +02:00
|
|
|
|
2021-09-04 12:43:18 +02:00
|
|
|
#[cfg(feature = "internals")]
|
|
|
|
#[cfg(not(feature = "no_float"))]
|
|
|
|
pub use ast::FloatWrapper;
|
|
|
|
|
2020-07-09 13:54:28 +02:00
|
|
|
#[cfg(feature = "internals")]
|
2022-01-07 04:43:47 +01:00
|
|
|
pub use eval::{EvalState, GlobalRuntimeState};
|
2022-01-01 10:20:00 +01:00
|
|
|
|
|
|
|
#[cfg(feature = "internals")]
|
|
|
|
pub use func::call::{FnResolutionCache, FnResolutionCacheEntry};
|
2020-11-27 16:37:59 +01:00
|
|
|
|
2020-06-23 04:43:24 +02:00
|
|
|
#[cfg(feature = "internals")]
|
2021-12-25 16:49:14 +01:00
|
|
|
pub use module::Namespace;
|
2020-06-23 04:43:24 +02:00
|
|
|
|
2021-09-10 14:25:22 +02:00
|
|
|
/// Alias to [`smallvec::SmallVec<[T; 3]>`](https://crates.io/crates/smallvec), which is a
|
|
|
|
/// specialized [`Vec`] backed by a small, inline, fixed-size array when there are ≤ 3 items stored.
|
2021-03-17 06:30:47 +01:00
|
|
|
///
|
2021-03-28 11:04:16 +02:00
|
|
|
/// # History
|
2021-03-17 06:30:47 +01:00
|
|
|
///
|
|
|
|
/// And Saint Attila raised the `SmallVec` up on high, saying, "O Lord, bless this Thy `SmallVec`
|
|
|
|
/// that, with it, Thou mayest blow Thine allocation costs to tiny bits in Thy mercy."
|
|
|
|
///
|
|
|
|
/// And the Lord did grin, and the people did feast upon the lambs and sloths and carp and anchovies
|
|
|
|
/// and orangutans and breakfast cereals and fruit bats and large chu...
|
|
|
|
///
|
|
|
|
/// And the Lord spake, saying, "First shalt thou depend on the [`smallvec`](https://crates.io/crates/smallvec) crate.
|
2021-09-10 14:25:22 +02:00
|
|
|
/// Then, shalt thou keep three inline. No more. No less. Three shalt be the number thou shalt keep inline,
|
|
|
|
/// and the number to keep inline shalt be three. Four shalt thou not keep inline, nor either keep inline
|
|
|
|
/// thou two, excepting that thou then proceed to three. Five is right out. Once the number three,
|
|
|
|
/// being the third number, be reached, then, lobbest thou thy `SmallVec` towards thy heap, who,
|
2021-03-17 06:30:47 +01:00
|
|
|
/// being slow and cache-naughty in My sight, shall snuff it."
|
|
|
|
///
|
2021-09-11 13:40:40 +02:00
|
|
|
/// # Why Three
|
2021-03-17 06:30:47 +01:00
|
|
|
///
|
|
|
|
/// `StaticVec` is used frequently to keep small lists of items in inline (non-heap) storage in
|
|
|
|
/// order to improve cache friendliness and reduce indirections.
|
|
|
|
///
|
2021-09-10 14:25:22 +02:00
|
|
|
/// The number 3, other than being the holy number, is carefully chosen for a balance between
|
2021-03-17 06:30:47 +01:00
|
|
|
/// storage space and reduce allocations. That is because most function calls (and most functions,
|
2021-09-12 07:33:55 +02:00
|
|
|
/// for that matter) contain fewer than 4 arguments, the exception being closures that capture a
|
2021-03-17 06:30:47 +01:00
|
|
|
/// large number of external variables.
|
|
|
|
///
|
2021-09-11 13:40:40 +02:00
|
|
|
/// In addition, most script blocks either contain many statements, or just one or two lines;
|
2021-09-10 14:25:22 +02:00
|
|
|
/// most scripts load fewer than 4 external modules; most module paths contain fewer than 4 levels
|
2021-09-11 13:40:40 +02:00
|
|
|
/// (e.g. `std::collections::map::HashMap` is 4 levels and it is just about as long as they get).
|
2020-10-10 07:41:55 +02:00
|
|
|
#[cfg(not(feature = "internals"))]
|
2021-09-10 14:25:22 +02:00
|
|
|
type StaticVec<T> = smallvec::SmallVec<[T; 3]>;
|
2020-10-10 07:41:55 +02:00
|
|
|
|
2021-09-11 13:40:40 +02:00
|
|
|
/// _(internals)_ Alias to [`smallvec::SmallVec<[T; 3]>`](https://crates.io/crates/smallvec),
|
|
|
|
/// which is a [`Vec`] backed by a small, inline, fixed-size array when there are ≤ 3 items stored.
|
2020-10-10 07:41:55 +02:00
|
|
|
/// Exported under the `internals` feature only.
|
2021-03-17 06:30:47 +01:00
|
|
|
///
|
2021-03-28 11:04:16 +02:00
|
|
|
/// # History
|
2021-03-17 06:30:47 +01:00
|
|
|
///
|
|
|
|
/// And Saint Attila raised the `SmallVec` up on high, saying, "O Lord, bless this Thy `SmallVec`
|
|
|
|
/// that, with it, Thou mayest blow Thine allocation costs to tiny bits in Thy mercy."
|
|
|
|
///
|
|
|
|
/// And the Lord did grin, and the people did feast upon the lambs and sloths and carp and anchovies
|
|
|
|
/// and orangutans and breakfast cereals and fruit bats and large chu...
|
|
|
|
///
|
|
|
|
/// And the Lord spake, saying, "First shalt thou depend on the [`smallvec`](https://crates.io/crates/smallvec) crate.
|
2021-09-10 14:25:22 +02:00
|
|
|
/// Then, shalt thou keep three inline. No more. No less. Three shalt be the number thou shalt keep inline,
|
|
|
|
/// and the number to keep inline shalt be three. Four shalt thou not keep inline, nor either keep inline
|
|
|
|
/// thou two, excepting that thou then proceed to three. Five is right out. Once the number three,
|
|
|
|
/// being the third number, be reached, then, lobbest thou thy `SmallVec` towards thy heap, who,
|
2021-03-17 06:30:47 +01:00
|
|
|
/// being slow and cache-naughty in My sight, shall snuff it."
|
|
|
|
///
|
2021-09-11 13:40:40 +02:00
|
|
|
/// # Why Three
|
2021-03-17 06:30:47 +01:00
|
|
|
///
|
|
|
|
/// `StaticVec` is used frequently to keep small lists of items in inline (non-heap) storage in
|
|
|
|
/// order to improve cache friendliness and reduce indirections.
|
|
|
|
///
|
2021-09-10 14:25:22 +02:00
|
|
|
/// The number 3, other than being the holy number, is carefully chosen for a balance between
|
2021-03-17 06:30:47 +01:00
|
|
|
/// storage space and reduce allocations. That is because most function calls (and most functions,
|
2021-09-12 07:33:55 +02:00
|
|
|
/// for that matter) contain fewer than 4 arguments, the exception being closures that capture a
|
2021-03-17 06:30:47 +01:00
|
|
|
/// large number of external variables.
|
|
|
|
///
|
2021-09-11 13:40:40 +02:00
|
|
|
/// In addition, most script blocks either contain many statements, or just one or two lines;
|
2021-09-10 14:25:22 +02:00
|
|
|
/// most scripts load fewer than 4 external modules; most module paths contain fewer than 4 levels
|
2021-09-11 13:40:40 +02:00
|
|
|
/// (e.g. `std::collections::map::HashMap` is 4 levels and it is just about as long as they get).
|
2020-06-23 04:43:24 +02:00
|
|
|
#[cfg(feature = "internals")]
|
2021-09-10 14:25:22 +02:00
|
|
|
pub type StaticVec<T> = smallvec::SmallVec<[T; 3]>;
|
2021-02-19 08:49:51 +01:00
|
|
|
|
2021-12-27 05:27:44 +01:00
|
|
|
/// Inline arguments storage for function calls.
|
|
|
|
///
|
|
|
|
/// # Notes
|
|
|
|
///
|
|
|
|
/// Since most usage of this is during a function call to gather up arguments, this is mostly
|
|
|
|
/// allocated on the stack, so we can tolerate a larger number of values stored inline.
|
|
|
|
///
|
|
|
|
/// Most functions have few parameters, but closures with a lot of captured variables can
|
|
|
|
/// potentially have many. Having a larger inline storage for arguments reduces allocations in
|
|
|
|
/// scripts with heavy closure usage.
|
|
|
|
///
|
|
|
|
/// Under `no_closure`, this type aliases to [`StaticVec`][crate::StaticVec] instead.
|
|
|
|
#[cfg(not(feature = "no_closure"))]
|
|
|
|
type FnArgsVec<T> = smallvec::SmallVec<[T; 8]>;
|
|
|
|
|
|
|
|
/// Inline arguments storage for function calls.
|
2021-12-27 10:00:21 +01:00
|
|
|
/// This type aliases to [`StaticVec`][crate::StaticVec].
|
2021-12-27 05:27:44 +01:00
|
|
|
#[cfg(feature = "no_closure")]
|
|
|
|
type FnArgsVec<T> = crate::StaticVec<T>;
|
|
|
|
|
2021-09-20 05:34:01 +02:00
|
|
|
pub(crate) type SmartString = smartstring::SmartString<smartstring::LazyCompact>;
|
2021-04-23 13:10:10 +02:00
|
|
|
|
2021-02-19 08:49:51 +01:00
|
|
|
// Compiler guards against mutually-exclusive feature flags
|
|
|
|
|
|
|
|
#[cfg(feature = "no_float")]
|
|
|
|
#[cfg(feature = "f32_float")]
|
2021-09-12 15:06:13 +02:00
|
|
|
compile_error!("`f32_float` cannot be used with `no_float`");
|
|
|
|
|
|
|
|
#[cfg(feature = "only_i32")]
|
|
|
|
#[cfg(feature = "only_i64")]
|
|
|
|
compile_error!("`only_i32` and `only_i64` cannot be used together");
|
2021-02-19 08:49:51 +01:00
|
|
|
|
|
|
|
#[cfg(feature = "no_std")]
|
|
|
|
#[cfg(feature = "wasm-bindgen")]
|
2021-09-12 15:06:13 +02:00
|
|
|
compile_error!("`wasm-bindgen` cannot be used with `no-std`");
|
2021-02-19 08:49:51 +01:00
|
|
|
|
|
|
|
#[cfg(feature = "no_std")]
|
|
|
|
#[cfg(feature = "stdweb")]
|
2021-09-12 15:06:13 +02:00
|
|
|
compile_error!("`stdweb` cannot be used with `no-std`");
|
2021-02-19 08:49:51 +01:00
|
|
|
|
2022-01-12 01:12:28 +01:00
|
|
|
#[cfg(target_family = "wasm")]
|
2021-02-19 08:49:51 +01:00
|
|
|
#[cfg(feature = "no_std")]
|
2021-09-12 15:06:13 +02:00
|
|
|
compile_error!("`no_std` cannot be used for WASM target");
|
2021-02-19 08:49:51 +01:00
|
|
|
|
2022-01-12 01:12:28 +01:00
|
|
|
#[cfg(not(target_family = "wasm"))]
|
2021-02-19 08:49:51 +01:00
|
|
|
#[cfg(feature = "wasm-bindgen")]
|
2021-09-12 15:06:13 +02:00
|
|
|
compile_error!("`wasm-bindgen` cannot be used for non-WASM target");
|
2021-02-19 08:49:51 +01:00
|
|
|
|
2022-01-12 01:12:28 +01:00
|
|
|
#[cfg(not(target_family = "wasm"))]
|
2021-02-19 08:49:51 +01:00
|
|
|
#[cfg(feature = "stdweb")]
|
2021-09-12 15:06:13 +02:00
|
|
|
compile_error!("`stdweb` cannot be used non-WASM target");
|
|
|
|
|
|
|
|
#[cfg(feature = "wasm-bindgen")]
|
|
|
|
#[cfg(feature = "stdweb")]
|
|
|
|
compile_error!("`wasm-bindgen` and `stdweb` cannot be used together");
|