New Text.insert function (#3311)

Implements https://www.pivotaltracker.com/n/projects/2539304

CHANGELOG.md

@@ -62,6 +62,7 @@
 - [Updated `Text.repeat` and added `*` operator shorthand][3310]
 - [General improved Vector performance and new `Vector.each_with_index`,
   `Vector.fold_with_index` and `Vector.take` methods.][3236]
+- [Implemented new `Text.insert` method][3311]
 
 [debug-shortcuts]:
   https://github.com/enso-org/enso/blob/develop/app/gui/docs/product/shortcuts.md#debug
@@ -96,7 +97,6 @@
 [3305]: https://github.com/enso-org/enso/pull/3305
 [3309]: https://github.com/enso-org/enso/pull/3309
 [3310]: https://github.com/enso-org/enso/pull/3310
-[3236]: https://github.com/enso-org/enso/pull/3236
 
 #### Enso Compiler
 

distribution/lib/Standard/Base/0.0.0-dev/src/Data/Text/Extensions.enso

@@ -601,12 +601,44 @@ Text.is_empty = this == ""
 Text.not_empty : Boolean
 Text.not_empty = this.is_empty.not
 
+## Inserts text value at the specified index.
+
+   Arguments:
+     - index: The position (0-based) in the text to inset text at.
+       When the index is non-negative the text is inserted before the
+       specified position.
+       When the index is negative, then the characters are counted from
+       the end of the text and the text is inserted after the specified
+       position, i.e. -1 will insert the text after the last character.
+
+   ! What is a Character?
+     A character is defined as an Extended Grapheme Cluster, see Unicode
+     Standard Annex 29. This is the smallest unit that still has semantic
+     meaning in most text-processing applications.
+
+   > Example
+    Insert text at a specified index
+
+         "Hello World!".insert 0 " Cruel" == " CruelHello World!"
+         "Hello World!".insert 5 " Cruel" == "Hello Cruel World!"
+         "Hello World!".insert -1 " Cruel" == "Hello World! Cruel"
+Text.insert : Integer -> Text -> Text ! Index_Out_Of_Bounds_Error
+Text.insert index that =
+    len = this.length
+    idx = if index < 0 then len + index + 1 else index
+    if (idx < 0) || (idx > len) then Error.throw (Index_Out_Of_Bounds_Error index len) else
+        if idx == 0 then that + this else
+            if idx == len then this + that else
+                pre = this.take (Range 0 idx)
+                post = this.take (Range idx len)
+                pre + that + post
+
 ## Returns if a character from the text at the specified index (0-based) is a
    digit (0-9).
 
    Arguments:
      - index: The location in the text to get the character from. The
-       index is also allowed be negative, then the characters are
+       index is also allowed to be negative, then the characters are
        counted from the end of the text, i.e. -1 will correspond to the
        last character.
 

test/Tests/src/Data/Text_Spec.enso

@@ -339,6 +339,35 @@ spec =
             kshi_chars = [2325, 2381, 2359, 2367]
             Text.from_utf_16 kshi_chars . should_equal kshi
 
+        Test.specify "should insert text at a non-negative index position" <|
+            "Hello World!".insert 0 " Cruel" . should_equal " CruelHello World!"
+            "Hello World!".insert 5 " Cruel" . should_equal "Hello Cruel World!"
+            "Hello World!".insert ("Hello World!".length - 1) " Cruel" . should_equal "Hello World Cruel!"
+            "Hello World!".insert "Hello World!".length " Cruel" . should_equal "Hello World! Cruel"
+            txt = kshi + facepalm + accent_1
+            txt.insert 0 " Cruel" . should_equal (" Cruel" + kshi + facepalm + accent_1)
+            txt.insert 1 " Cruel" . should_equal (kshi + " Cruel" + facepalm + accent_1)
+            txt.insert 2 " Cruel" . should_equal (kshi + facepalm + " Cruel" + accent_1)
+            txt.insert 3 " Cruel" . should_equal (kshi + facepalm + accent_1 + " Cruel")
+
+        Test.specify "should report Index_Out_Of_Bounds_Error when inserting text at an invalid non-negative index position" <|
+            "Hello World!".insert ("Hello World!".length + 1) "foo" . should_fail_with Index_Out_Of_Bounds_Error
+            (kshi + facepalm + accent_1).insert 4 "foo" . should_fail_with Index_Out_Of_Bounds_Error
+
+        Test.specify "should insert text at a negative index position" <|
+            "Hello World!".insert -1 " Cruel" . should_equal "Hello World! Cruel"
+            "Hello World!".insert -5 " Cruel" . should_equal "Hello Wo Cruelrld!"
+            "Hello World!".insert -("Hello World!".length) " Cruel" . should_equal "H Cruelello World!"
+            "Hello World!".insert -("Hello World!".length + 1) " Cruel" . should_equal " CruelHello World!"
+            txt = kshi + facepalm + accent_1
+            txt.insert -1 " Cruel" . should_equal (txt + " Cruel")
+            txt.insert -(txt.length) " Cruel" . should_equal (kshi + " Cruel" + facepalm + accent_1)
+
+        Test.specify "should report Index_Out_Of_Bounds_Error when inserting text at an invalid negative index position" <|
+            "Hello World!".insert -("Hello World!".length + 2) " Cruel" . should_fail_with Index_Out_Of_Bounds_Error
+            txt = kshi + facepalm + accent_1
+            txt.insert -(txt.length + 2) " Cruel" . should_fail_with Index_Out_Of_Bounds_Error
+
         Test.specify "should be able to check by index if is a digit" <|
             str = kshi + "A12" + accent_2
             str.is_digit . should_be_false