feat: adds substring method for Text with tests

src/Text.mo

@@ -25,6 +25,7 @@ import Iter "Iter";
 import Hash "Hash";
 import Stack "Stack";
 import Prim "mo:⛔";
+import Debug "Debug";
 
 module {
 
@@ -363,7 +364,7 @@ module {
   };
 
   /// Splits the input `Text` with the specified `Pattern`.
-  /// 
+  ///
   /// Two fields are separated by exactly one match.
   ///
   /// ```motoko include=import
@@ -425,6 +426,38 @@ 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.
+  /// If a starting position is passed that is greater than the length of the input `Text`, returns empty string.
+  /// If a length is passed that is greater than the length of the input `Text`, returns the substring from the starting position to the end of the input `Text`.
+  ///
+  /// ```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 : Nat, len : Nat) : Text {
+    var output = "";
+
+    if (start >= t.size()) {
+      return output
+    };
+
+    var count = 0;
+    for (char in t.chars()) {
+      if (count >= start and count < start + len) {
+        output := output # fromChar(char)
+      };
+      count := count + 1;
+      // If we've reached the end of the substring, return the output
+      if (count >= start + len) {
+        return output
+      }
+    };
+    // If we've reached the end of the string, return the output
+    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,59 @@ 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 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(