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

Remove content on avoiding &mut ImmutableString which is invalid.

Browse Source
This commit is contained in:
Stephen Chung 2020-08-15 00:10:14 +08:00
parent 489b1ca00e
commit f9807a3c1e
2 changed files with 2 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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
otherwise have happened if the signature were `Fn(Array) -> INT`.
For primary types that are cheap to clone (e.g. those that implement `Copy`),
including `ImmutableString`, 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.
For primary types that are cheap to clone (e.g. those that implement `Copy`), including `ImmutableString`,
this is not necessary.

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.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.