Add Text.substring to allow for an easy short hand of Text.take (star…

…t.up_to end) (#7913)

* Add Text.substring function and get_position helper function

For #7876 adds a Text.substring function which supports negative indexes and returns a part of a string from 0-based index 'start' and continuing for 'length'

* added substring and simplified get function

For #7876 adds a Text.substring function which supports negative indexes and returns a part of a string from 0-based index 'start' and continuing for 'length'.

Also simplified get function as it looped unnecessarily.

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

punctuation corrections

Co-authored-by: GregoryTravis <greg.m.travis@gmail.com>

* Update Text_Spec.enso

Added test for start index larger than string

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

updated Arguments: section to use consistent style

Co-authored-by: Radosław Waśko <radoslaw.wasko@enso.org>

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

updated Index_Out_Of_Bounds error to reference cached length

Co-authored-by: Radosław Waśko <radoslaw.wasko@enso.org>

* Removed Slice label and added changelog entry

* Re-added slice tag to substring

Per conversation with James, added slice back to substring

* Update CHANGELOG.md add link

---------

Co-authored-by: GregoryTravis <greg.m.travis@gmail.com>
Co-authored-by: Radosław Waśko <radoslaw.wasko@enso.org>

CHANGELOG.md

@@ -579,6 +579,7 @@
 - [Implemented `Date_Time_Formatter` for more user-friendly date/time format
   parsing.][7826]
 - [Implemented `Table.auto_value_types` for in-memory tables.][7908]
+- [Implemented Text.substring to easily select part of a Text field][7913]
 
 [debug-shortcuts]:
   https://github.com/enso-org/enso/blob/develop/app/gui/docs/product/shortcuts.md#debug
@@ -822,6 +823,7 @@
 [7807]: https://github.com/enso-org/enso/pull/7807
 [7826]: https://github.com/enso-org/enso/pull/7826
 [7908]: https://github.com/enso-org/enso/pull/7908
+[7913]: https://github.com/enso-org/enso/pull/7913
 
 #### Enso Compiler
 

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

@@ -141,19 +141,14 @@ Text.at self index =
          "건반(Korean)".get 1 == "반"
 Text.get : Integer -> Any -> Any
 Text.get self index ~if_missing=Nothing =
-    case index < 0 of
-        True ->
-            length = self.length
-            new_index = index + length
-            if new_index < 0 then if_missing else
-                self.at new_index
-        False ->
-            iterator = BreakIterator.getCharacterInstance
-            iterator.setText self
-            first = iterator.next index
-            next = if first == -1 then -1 else iterator.next
-            if (next == -1) then if_missing else
-                Text_Utils.substring self first next
+    new_index = if index < 0 then index + self.length else index
+    if new_index < 0 then if_missing else
+        iterator = BreakIterator.getCharacterInstance
+        iterator.setText self
+        first = iterator.next new_index
+        next = if first == -1 then -1 else iterator.next
+        if (next == -1) then if_missing else
+            Text_Utils.substring self first next
 
 ## GROUP Selections
    Returns the first character from the text.
@@ -1791,6 +1786,35 @@ Text.parse_time_of_day self format:Date_Time_Formatter=Date_Time_Formatter.iso_t
 Text.parse_time_zone : Time_Zone ! Time_Error
 Text.parse_time_zone self = Time_Zone.parse self
 
+## ALIAS mid, slice, substring
+   GROUP Selections
+   Creates a new Text by selecting the specified range of the input.
+
+   Arguments:
+   - start: the character position to start the substring at. 0-based index. Has support for negative values.
+   - length: the number of characters to include from start.
+
+   Returns:
+   Part of the selected Text starting at start and stopping after length.
+
+   > Examples
+     Various different ways to take part of "Hello World!"
+
+         "Hello World!".substring 3 2 == "lo"
+         "Hello World!".substring 5 Nothing == " World!"
+         "Hello World!".substring 5 7 == " World!"
+         "Hello World!".substring -7 3 == " Wo"
+
+Text.substring : Integer -> Integer -> Range ! Index_Out_Of_Bounds
+Text.substring self start:Integer length:Integer=self.length =
+    if length < 0 then Error.throw (Illegal_Argument.Error "length must be greater than or equal to 0") else
+        if length == 0 then "" else
+            self_length = self.length
+            fixed_start = if start < 0 then start + self_length else start
+            if fixed_start < 0 then (Error.throw (Index_Out_Of_Bounds.Error start self_length)) else
+                range = fixed_start.up_to fixed_start+length
+                self.take range
+
 ## PRIVATE
    Returns a new Text constructed by slicing the input according to the provided
    ranges. The ranges are assumed to have step equal to 1 and bounds within the

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

@@ -766,7 +766,7 @@ type Vector a
             if self.length == 1 then prefix + self.at 0 + suffix else
                 prefix + self.at 0 + (1.up_to self.length . fold "" acc-> i-> acc + separator + self.at i) + suffix
 
-    ## GROUP Selections
+    ## PRIVATE
        Creates a new vector with the skipping elements until `start` and then
        continuing until `end` index.
 

test/Tests/src/Data/Text_Spec.enso

@@ -1647,5 +1647,19 @@ spec =
             "Aaa".replace r_ci "b" case_sensitivity=Case_Sensitivity.Sensitive . should_equal "Ab"
             "aaa".replace r_ci "b" case_sensitivity=Case_Sensitivity.Insensitive . should_equal "ba"
             "Aaa".replace r_ci "b" case_sensitivity=Case_Sensitivity.Insensitive . should_equal "ba"
+    Test.group "Text.substring" <|
+        Test.specify "should work with all examples" <|
+            "Hello World!".substring 3 2 . should_equal "lo"
+            "Hello World!".substring 5 . should_equal " World!"
+            "Hello World!".substring 5 7 . should_equal " World!"
+            "Hello World!".substring -7 3 . should_equal " Wo"
+
+        Test.specify "should error on length less than 0" <|
+            "Hello World!".substring 5 -2 . should_fail_with Illegal_Argument
+
+        Test.specify "should error if negative start index is too large"
+            "Hello World!".substring -20 5 . should_fail_with Index_Out_Of_Bounds
+        Test.specify "should error if start index is larger than string"
+            "Hello World!".substring 20 5 . should_fail_with Index_Out_Of_Bounds
 
 main = Test_Suite.run_main spec