From f9807a3c1e70dcb2362da99a2eb439569ba4ef99 Mon Sep 17 00:00:00 2001 From: Stephen Chung Date: Sat, 15 Aug 2020 00:10:14 +0800 Subject: [PATCH] Remove content on avoiding &mut ImmutableString which is invalid. --- doc/src/language/method.md | 15 ++------------- doc/src/rust/strings.md | 22 ---------------------- 2 files changed, 2 insertions(+), 35 deletions(-) diff --git a/doc/src/language/method.md b/doc/src/language/method.md index 3b8a82d4..d2b4281d 100644 --- a/doc/src/language/method.md +++ b/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. diff --git a/doc/src/rust/strings.md b/doc/src/rust/strings.md index f1d421ea..197501e4 100644 --- a/doc/src/rust/strings.md +++ b/doc/src/rust/strings.md @@ -41,25 +41,3 @@ let len = engine.eval::("x.len1()")?; // 'x' is cloned, ve let len = engine.eval::("x.len2()")?; // 'x' is shared let len = engine.eval::("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.