feat: adds substring method for Text with tests

src/Text.mo

@@ -363,7 +363,7 @@ module {
   };
 
   /// Splits the input `Text` with the specified `Pattern`.
-  /// 
+  ///
   /// Two fields are separated by exactly one match.
   ///
   /// ```motoko include=import
@@ -425,6 +425,54 @@ module {
     }
   };
 
+  /// Returns a substring of the input `Text` delimited by the specified `Pattern`, provided with a starting position and a length.
+  /// If no length is passed, returns empty string.
+  ///
+  /// ```motoko include=import
+  /// Text.substring("This is a sentence.", 0, 4) // "This"
+  /// Text.substring("This is a sentence.", 5, 4) // "is a"
+  /// Text.substring("This is a sentence.", 0, 0) // ""
+  /// ```
+  public func substring(t : Text, start : Int, len : Int) : Text {
+    var output = "";
+    var count = 0;
+    //handle negative length
+    if (len < 0) {
+      for (char in t.chars()) {
+        // handle negative start
+        if (start < 0) {
+          if (count >= t.size() + start) {
+            output := output # fromChar(char)
+          };
+          count := count + 1
+        };
+        // handle positive start
+        if (count >= start) {
+          output := output # fromChar(char);
+          count := count + 1
+        }
+      };
+      return output
+    };
+
+    // handle positive length
+    for (char in t.chars()) {
+      // handle negative start
+      if (start < 0) {
+        if (count >= t.size() + start and count < t.size() + start + len) {
+          output := output # fromChar(char)
+        };
+        count := count + 1
+      };
+      // handle positive start
+      if (count >= start and count < start + len) {
+        output := output # fromChar(char);
+        count := count + 1
+      }
+    };
+    output
+  };
+
   /// Returns a sequence of tokens from the input `Text` delimited by the specified `Pattern`, derived from start to end.
   /// A "token" is a non-empty maximal subsequence of `t` not containing a match for pattern `p`.
   /// Two tokens may be separated by one or more matches of `p`.

test/textTest.mo

@@ -325,6 +325,74 @@ run(
   )
 );
 
+run(
+  suite(
+    "substring",
+    [
+      test(
+        "zero length",
+        Text.substring("abc", 0, 0),
+        M.equals(T.text "")
+      ),
+      test(
+        "length of 1 from start",
+        Text.substring("abc", 0, 1),
+        M.equals(T.text "a")
+      ),
+      test(
+        "length of 2 from start",
+        Text.substring("abc", 0, 2),
+        M.equals(T.text "ab")
+      ),
+      test(
+        "length of 3 from start",
+        Text.substring("abc", 0, 3),
+        M.equals(T.text "abc")
+      ),
+      test(
+        "length of 1 from middle",
+        Text.substring("abc", 1, 1),
+        M.equals(T.text "b")
+      ),
+      test(
+        "length of 2 from middle",
+        Text.substring("abc", 1, 2),
+        M.equals(T.text "bc")
+      ),
+      test(
+        "length of 1 from end",
+        Text.substring("abc", 2, 1),
+        M.equals(T.text "c")
+      ),
+      test(
+        "length of 2 from end",
+        Text.substring("abc", 2, 2),
+        M.equals(T.text "c")
+      ),
+      test(
+        "should handle negative start",
+        Text.substring("abc", -1, 1),
+        M.equals(T.text "c")
+      ),
+      test(
+        "should handle negative length",
+        Text.substring("abc", 0, -1),
+        M.equals(T.text "")
+      ),
+      test(
+        "should handle negative start and length",
+        Text.substring("abc", -1, -1),
+        M.equals(T.text "")
+      ),
+      test(
+        "should handle start past end",
+        Text.substring("abc", 3, 1),
+        M.equals(T.text "")
+      )
+    ]
+  )
+);
+
 do {
   let pat : Text.Pattern = #predicate(func(c : Char) : Bool { c == ';' or c == '!' });
   run(