kjuulh/rhai
1
0
Fork 0
Code Issues 1 Pull Requests 1 Packages Projects Releases Wiki Activity

Merge branch 'master' into plugins

Browse Source
This commit is contained in:
Stephen Chung 2020-08-15 12:10:07 +08:00
commit 73f35f9518
3 changed files with 3 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
RELEASES.md
View File

@ -8,6 +8,7 @@ New features
------------ ------------
* Adds `Engine::register_get_result`, `Engine::register_set_result`, `Engine::register_indexer_get_result`, `Engine::register_indexer_set_result` API. * Adds `Engine::register_get_result`, `Engine::register_set_result`, `Engine::register_indexer_get_result`, `Engine::register_indexer_set_result` API.
* Adds `Module::combine` to combine two modules.
Version 0.18.1 Version 0.18.1

15
doc/src/language/method.md
View File

@ -63,16 +63,5 @@ For example, the `len` method of an [array] has the signature: `Fn(&mut Array) -
The array itself is not modified in any way, but using a `&mut` parameter avoids a cloning that would The array itself is not modified in any way, but using a `&mut` parameter avoids a cloning that would
otherwise have happened if the signature were `Fn(Array) -> INT`. otherwise have happened if the signature were `Fn(Array) -> INT`.
For primary types that are cheap to clone (e.g. those that implement `Copy`), For primary types that are cheap to clone (e.g. those that implement `Copy`), including `ImmutableString`,
including `ImmutableString`, this is not necessary. this is not necessary.
Avoid `&mut ImmutableString`
---------------------------
`ImmutableString`, Rhai's internal [string] type, is an exception.
`ImmutableString` is cheap to clone, but expensive to take a mutable reference (because the underlying
string must be cloned to make a private copy).
Therefore, avoid using `&mut ImmutableString` unless the intention is to mutate it.

22
doc/src/rust/strings.md
View File

@ -41,25 +41,3 @@ let len = engine.eval::<i64>("x.len1()")?; // 'x' is cloned, ve
let len = engine.eval::<i64>("x.len2()")?; // 'x' is shared let len = engine.eval::<i64>("x.len2()")?; // 'x' is shared
let len = engine.eval::<i64>("x.len3()")?; // 'x' is shared let len = engine.eval::<i64>("x.len3()")?; // 'x' is shared
``` ```
Avoid `&mut ImmutableString`
---------------------------
Rhai functions can take a first `&mut` parameter. Usually this is a good idea because it avoids
cloning of the argument (except for primary types where cloning is cheap), so its use is encouraged
even though there is no intention to ever mutate that argument.
[`ImmutableString`][string] is an exception to this rule.
While `ImmutableString` is cheap to clone (only incrementing a reference count), taking a mutable
reference to it involves making a private clone of the underlying string because Rhai has no way
to find out whether that parameter will be mutated.
If the `ImmutableString` is not shared by any other variables, then Rhai just returns a mutable
reference to it since nobody else is watching! Otherwise a private copy is made first,
because other reference holders will not expect the `ImmutableString` to ever change
(it is supposed to be _immutable_).
Therefore, avoid using `&mut ImmutableString` as the first parameter of a function unless you really
intend to mutate that string. Use `ImmutableString` instead.