Change return type of String.add to String iso^

Fixes #3750 by implementing RFC 69.

.release-notes/3752.md

@@ -0,0 +1,55 @@
+## Change the return type of String.add to String iso^ (RFC 69)
+
+This release introduces a breaking change by changing the return type of `String.add` from `String val` to `String iso^`.
+
+Where you previously had code like:
+
+```pony
+let c = Circle
+let str = "Radius: " + c.get_radius().string() + "\n"
+env.out.print(str)
+```
+
+you now need:
+
+```pony
+let c = Circle
+let str = recover val "Radius: " + c.get_radius().string() + "\n" end
+env.out.print(str)
+```
+
+or you can also let the compiler do the work for you by using explicit type declarations:
+
+```pony
+let c = Circle
+let str: String = "Radius: " + c.get_radius().string() + "\n"
+env.out.print(str)
+```
+
+The above code works since `val` is the default reference capability of the `String` type.
+
+The new type makes it simpler to implement the `Stringable` interface by using `String.add`. Where before you had code like:
+
+```pony
+class MyClass is Stringable
+  let var1: String = "hello"
+  let var2: String = " world"
+
+  fun string(): String iso^ =>
+    recover
+      String.create(var1.size() + var1.size())
+        .>append(var1)
+        .>append(var2)
+    end
+```
+
+you can now implement the `string` method as such:
+
+```pony
+class MyClass is Stringable
+  let var1: String = "hello"
+  let var2: String = " world"
+
+  fun string(): String iso^ =>
+    var1 + var2
+```

examples/circle/main.pony

@@ -22,9 +22,11 @@ actor Main
       let c = Circle(i)
 
       var str =
-        "Radius: " + c.get_radius().string() + "\n" +
-        "Circumference: " + c.get_circumference().string() + "\n" +
-        "Area: " + c.get_area().string() + "\n"
+        recover val
+          "Radius: " + c.get_radius().string() + "\n" +
+          "Circumference: " + c.get_circumference().string() + "\n" +
+          "Area: " + c.get_area().string() + "\n"
+        end
 
       env.out.print(str)
     end

packages/builtin/string.pony

@@ -1301,7 +1301,7 @@ actor Main
     _size = len
     consume this
 
-  fun add(that: String box): String =>
+  fun add(that: String box): String iso^ =>
     """
     Return a string that is a concatenation of this and that.
     """

packages/encode/base64/_test.pony

@@ -74,19 +74,23 @@ class iso _TestBase64Quote is UnitTest
 
   fun apply(h: TestHelper) ? =>
     let src =
-      "Man is distinguished, not only by his reason, but by this singular " +
-      "passion from other animals, which is a lust of the mind, that by a " +
-      "perseverance of delight in the continued and indefatigable " +
-      "generation of knowledge, exceeds the short vehemence of any carnal " +
-      "pleasure."
+      recover val
+        "Man is distinguished, not only by his reason, but by this singular " +
+        "passion from other animals, which is a lust of the mind, that by a " +
+        "perseverance of delight in the continued and indefatigable " +
+        "generation of knowledge, exceeds the short vehemence of any carnal " +
+        "pleasure."
+      end
 
     let expect =
-      "TWFuIGlzIGRpc3Rpbmd1aXNoZWQsIG5vdCBvbmx5IGJ5IGhpcyByZWFzb24sIGJ1dCBie" +
-      "SB0aGlzIHNpbmd1bGFyIHBhc3Npb24gZnJvbSBvdGhlciBhbmltYWxzLCB3aGljaCBpcy" +
-      "BhIGx1c3Qgb2YgdGhlIG1pbmQsIHRoYXQgYnkgYSBwZXJzZXZlcmFuY2Ugb2YgZGVsaWd" +
-      "odCBpbiB0aGUgY29udGludWVkIGFuZCBpbmRlZmF0aWdhYmxlIGdlbmVyYXRpb24gb2Yg" +
-      "a25vd2xlZGdlLCBleGNlZWRzIHRoZSBzaG9ydCB2ZWhlbWVuY2Ugb2YgYW55IGNhcm5hb" +
-      "CBwbGVhc3VyZS4="
+      recover val
+        "TWFuIGlzIGRpc3Rpbmd1aXNoZWQsIG5vdCBvbmx5IGJ5IGhpcyByZWFzb24sIGJ1dCBie" +
+        "SB0aGlzIHNpbmd1bGFyIHBhc3Npb24gZnJvbSBvdGhlciBhbmltYWxzLCB3aGljaCBpcy" +
+        "BhIGx1c3Qgb2YgdGhlIG1pbmQsIHRoYXQgYnkgYSBwZXJzZXZlcmFuY2Ugb2YgZGVsaWd" +
+        "odCBpbiB0aGUgY29udGludWVkIGFuZCBpbmRlZmF0aWdhYmxlIGdlbmVyYXRpb24gb2Yg" +
+        "a25vd2xlZGdlLCBleGNlZWRzIHRoZSBzaG9ydCB2ZWhlbWVuY2Ugb2YgYW55IGNhcm5hb" +
+        "CBwbGVhc3VyZS4="
+      end
 
     let enc = recover val Base64.encode(src) end
     h.assert_eq[String](expect, enc)