add runnableExamples for prepareStrMutation (#17227)

* Update lib/system.nim

Co-authored-by: Timothee Cour <timothee.cour2@gmail.com>

2 files changed, 9 insertions, 2 deletions

diff --git a/lib/system.nim b/lib/system.nim
index 56746fb65..605670f44 100644
--- a/lib/system.nim
+++ b/lib/system.nim
@@ -3124,5 +3124,12 @@ when not defined(createNimHcr) and not defined(nimscript):
 when notJSnotNims and not defined(nimSeqsV2):
   proc prepareStrMutation*(s: var string) {.inline.} =
     ## String literals (e.g. "abc", etc) in the ARC/ORC mode are "copy on write",
-    ## therefore you should call `prepareStrMutation` before modifying the strings.
+    ## therefore you should call `prepareStrMutation` before modifying the strings
+    ## via `addr`.
+    runnableExamples("--gc:arc"):
+      var x = "abc"
+      var y = "defgh"
+      prepareStrMutation(y) # without this, you may get a `SIGBUS` or `SIGSEGV`
+      moveMem(addr y[0], addr x[0], x.len)
+      assert y == "abcgh"
     discard
diff --git a/lib/system/strs_v2.nim b/lib/system/strs_v2.nim
index b20457d51..2647f7dcc 100644
--- a/lib/system/strs_v2.nim
+++ b/lib/system/strs_v2.nim
@@ -171,7 +171,7 @@ proc nimPrepareStrMutationV2(s: var NimStringV2) {.compilerRtl, inline.} =
 
 proc prepareStrMutation*(s: var string) {.inline.} =
   # string literals are "copy on write", so you need to call
-  # `prepareStrMutation` before modifying the strings.
+  # `prepareStrMutation` before modifying the strings via `addr`.
   {.cast(noSideEffect).}:
     let s = unsafeAddr s
     nimPrepareStrMutationV2(cast[ptr NimStringV2](s)[])