Added String.substr() @deprecated but available

Author: fadrian06

Tasks.todo

@@ -43,6 +43,7 @@ JSPHP:
       ☐ String.slice()
       ☐ String.split()
       ☐ String.startsWith()
+      ✔ String.substr() @done (01/07/2024 20:53:17)
       ✔ String.substring() @done (06/01/2024 16:00:51)
       ☐ String.toLocaleLowerCase()
       ☐ String.toLocaleUpperCase()

src/Globals/JSString.php

@@ -273,6 +273,31 @@ function padEnd(int $maxLength, string $fillString = ' '): self {
   function split($separator, ?int $limit = null): JSArray {
     return JSArray(...explode($separator, $this->value));
   }
+
+  /**
+   * Gets a substring beginning at the specified location and having the specified length.
+   * @deprecated A legacy feature for browser compatibility
+   * @param int $from The starting position of the desired substring. The index of the first character in the string is zero.
+   * @param ?int $length The number of characters to include in the returned substring.
+   */
+  function substr($from = 0, $length = null): self {
+    $params = [$this->value, $from];
+
+    if ($length !== null) {
+      $params[] = $length;
+    }
+
+    if (
+      $length < 0
+      || Number::isNaN($from)
+      || Number::isNaN($length)
+      || $from + ($length ?? 0) >= $this->length
+    ) {
+      return new self;
+    }
+
+    return new self(substr(...$params));
+  }
 }
 
 /**

tests/PHP/JSString/substrTest.php

@@ -0,0 +1,54 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\PHP\JSString;
+
+use PHPUnit\Framework\TestCase;
+
+final class substrTest extends TestCase {
+  function test_Demo_String_substr(): void {
+    $str = String('Mozilla');
+
+    self::assertEquals('oz', $str->substr(1, 2));
+    self::assertEquals('zilla', $str->substr(2));
+  }
+
+  function test_Description(): void {
+    $str = String('Mozilla');
+
+    // If start >= str.length, an empty string is returned.
+    self::assertEquals('', $str->substr(7));
+
+    // If start < 0, the index starts counting from the end of the string. More formally, in this case the substring starts at max(start + str.length, 0).
+    self::assertEquals('a', $str->substr(-1));
+    self::assertEquals($str, $str->substr(-7));
+    self::assertEquals($str, $str->substr(-8));
+
+    // If start is omitted or undefined, it's treated as 0.
+    self::assertEquals($str, $str->substr());
+
+    // TODO: If length is omitted or undefined, or if start + length >= str.length, substr() extracts characters to the end of the string.
+
+    // If length < 0, an empty string is returned.
+    self::assertEquals('', $str->substr(0, -1));
+
+    // For both start and length, NaN is treated as 0.
+    self::assertEquals('', $str->substr(0, NaN));
+    self::assertEquals('', $str->substr(NaN));
+    self::assertEquals('', $str->substr(NaN, NaN));
+  }
+
+  function test_Using_substr(): void {
+    $aString = String('Mozilla');
+
+    self::assertEquals('M', $aString->substr(0, 1));
+    self::assertEquals('', $aString->substr(1, 0));
+    self::assertEquals('a', $aString->substr(-1, 1));
+    self::assertEquals('', $aString->substr(1, -1));
+    self::assertEquals('lla', $aString->substr(-3));
+    self::assertEquals('ozilla', $aString->substr(1));
+    self::assertEquals('Mo', $aString->substr(-20, 2));
+    self::assertEquals('', $aString->substr(20, 2));
+  }
+}

tests/PHP/JSString/substringTest.php

@@ -39,7 +39,7 @@ function test_The_difference_between_substring_and_substr(): void {
     $text = String('Mozilla');
 
     self::assertEquals('zil', $text->substring(2, 5));
-    // self::assertEquals('zil', $text->substr(2, 3)); // TODO
+    self::assertEquals('zil', $text->substr(2, 3));
   }
 
   function test_Differences_between_substring_and_slice(): void {