Update docs.

doc/src/language/dynamic.md

@@ -66,7 +66,7 @@ item.is::<i64>() == true;                       // 'is' returns whether a 'Dynam
 let value = item.cast::<i64>();                 // if the element is 'i64', this succeeds; otherwise it panics
 let value: i64 = item.cast();                   // type can also be inferred
 
-let value = item.try_cast::<i64>().unwrap();    // 'try_cast' does not panic when the cast fails, but returns 'None'
+let value = item.try_cast::<i64>()?;            // 'try_cast' does not panic when the cast fails, but returns 'None'
 ```
 
 Type Name

doc/src/language/method.md

@@ -3,6 +3,10 @@ Call Method as Function
 
 {{#include ../links.md}}
 
+
+First `&mut` Reference Parameter
+-------------------------------
+
 Property [getters/setters] and [methods][custom types] in a Rust custom type registered with the [`Engine`] can be called
 just like a regular function.  In fact, like Rust, property getters/setters and object methods
 are registered as regular [functions] in Rhai that take a first `&mut` parameter.
@@ -31,3 +35,23 @@ update(array[0]);   // <- 'array[0]' is an expression returning a calculated val
 
 array[0].update();  // <- call in method-call style will update 'a'
 ```
+
+
+Encouraged Usage
+----------------
+
+Using a `&mut` first parameter is highly encouraged when using types that are expensive to clone,
+even when the intention is not to mutate that argument, because it avoids cloning that argument value.
+
+For primary types that are cheap to clone, including `ImmutableString`, this is not necessary.
+
+
+Avoid `&mut ImmutableString`
+---------------------------
+
+`ImmutableString`, Rhai 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.

doc/src/language/strings-chars.md

@@ -6,20 +6,25 @@ Strings and Characters
 String in Rhai contain any text sequence of valid Unicode characters.
 Internally strings are stored in UTF-8 encoding.
 
-Strings can be built up from other strings and types via the `+` operator (provided by the [`MoreStringPackage`][packages]
-but excluded if using a [raw `Engine`]). This is particularly useful when printing output.
+Strings can be built up from other strings and types via the `+` operator
+(provided by the [`MoreStringPackage`][packages] but excluded if using a [raw `Engine`]).
+This is particularly useful when printing output.
 
 [`type_of()`] a string returns `"string"`.
 
 The maximum allowed length of a string can be controlled via `Engine::set_max_string_size`
 (see [maximum length of strings]).
 
+
 The `ImmutableString` Type
 -------------------------
 
 All strings in Rhai are implemented as `ImmutableString` (see [standard types]).
 
-`ImmutableString` should be used in place of the standard Rust type `String` when registering functions.
+`ImmutableString` should be used in place of the standard Rust type `String` when registering functions
+because using `String` is very inefficient (the `String` must always be cloned).
+
+A alternative is to use `&str` which maps straight to `ImmutableString`.
 
 
 String and Character Literals
@@ -59,13 +64,13 @@ Unicode characters.
 
 Individual characters within a Rhai string can also be replaced just as if the string is an array of Unicode characters.
 
-In Rhai, there is also no separate concepts of `String` and `&str` as in Rust.
+In Rhai, there are also no separate concepts of `String` and `&str` as in Rust.
 
 
 Immutable Strings
 ----------------
 
-Rhai strings are _immutable_ and can be shared.
+Rhai use _immutable_ strings (type `ImmutableString`) and can be shared.
 
 Modifying a Rhai string actually causes it first to be cloned, and then the modification made to the copy.