Merge branch 'master' into plugins

RELEASES.md

@@ -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 `Module::combine` to combine two modules.
 
 
 Version 0.18.1

doc/src/language/method.md

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

doc/src/rust/strings.md

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