feat!: resolve negative index arguments relative to last index

BREAKING CHANGE: resolve negative index arguments relative to last index

Previously, a negative `fromIndex` argument would resolve to `0`.
The current behavior resolves relative to the last character index.
To preserve the previous behavior, users should clamp index arguments
to index bounds before calling `replaceAfterLast`.

Ref: #1365
Ref: 58bdac8

Author: kgryte

lib/node_modules/@stdlib/string/base/replace-after-last/README.md

@@ -53,6 +53,20 @@ out = replaceAfterLast( str, 'o', 'bar', str.length );
 // returns 'beep boobar'
 ```
 
+To begin searching from a specific index, provide a corresponding `fromIndex` argument.
+
+```javascript
+var out = replaceAfterLast( 'beep boop beep', ' ', 'loop', 6 );
+// returns 'beep loop'
+```
+
+If `fromIndex` is less than zero, the starting index is resolved relative to the last string character, with the last string character corresponding to `fromIndex = -1`.
+
+```javascript
+var out = replaceAfterLast( 'beep boop beep', ' ', 'loop', -1 );
+// returns 'beep boop loop'
+```
+
 </section>
 
 <!-- /.usage -->
@@ -65,7 +79,7 @@ out = replaceAfterLast( str, 'o', 'bar', str.length );
 
 -   If a search string is not present in a provided string, the function returns the provided string unchanged.
 -   If a search string is an empty string, the function returns the provided string unchanged.
--   If `fromIndex` is less than `0`, the function returns the provided string unchanged.
+-   If `fromIndex` resolves to an index which is less than `0`, the function returns the provided string unchanged.
 
 </section>
 

lib/node_modules/@stdlib/string/base/replace-after-last/docs/repl.txt

@@ -3,6 +3,12 @@
     Replaces the substring after the last occurrence of a specified search
     string.
 
+    If unable to find a search string, the function returns the input string
+    unchanged.
+
+    The function scans an input string from the starting index to the beginning
+    of the string (i.e., backward).
+
     Parameters
     ----------
     str: string
@@ -15,7 +21,9 @@
         Replacement string.
 
     fromIndex: integer
-        Index from which to start searching.
+        Starting index (inclusive). If less than zero, the starting index is
+        resolved relative to the last string character, with the last string
+        character corresponding to `fromIndex = -1`.
 
     Returns
     -------

lib/node_modules/@stdlib/string/base/replace-after-last/docs/types/index.d.ts

@@ -21,6 +21,12 @@
 /**
 * Replaces the substring after the last occurrence of a specified search string.
 *
+* ## Notes
+*
+* -   The function scans a provided string from the starting index to the beginning of the string (i.e., backward).
+* -   If unable to find search string, the function returns the input string unchanged.
+* -   If `fromIndex` is less than zero, the starting index is resolved relative to the last string character, with the last string character corresponding to `fromIndex = -1`.
+*
 * @param str - input string
 * @param search - search string
 * @param replacement - replacement string

lib/node_modules/@stdlib/string/base/replace-after-last/lib/main.js

@@ -62,7 +62,10 @@
 function replaceAfterLast( str, search, replacement, fromIndex ) {
 	var idx;
 	if ( fromIndex < 0 ) {
-		return str;
+		fromIndex += str.length;
+		if ( fromIndex < 0 ) {
+			return str;
+		}
 	}
 	idx = str.lastIndexOf( search, fromIndex );
 	if ( str === '' || search === '' || replacement === '' || idx < 0 ) {

lib/node_modules/@stdlib/string/base/replace-after-last/test/test.js

@@ -94,7 +94,12 @@ tape( 'the function replaces the substring after a provided search string (custo
 	t.strictEqual( actual, expected, 'returns expected value' );
 
 	str = 'beep boop baz';
-	actual = replaceAfterLast( str, 'beep', 'foo', -2 );
+	actual = replaceAfterLast( str, 'beep', 'foo', -3 );
+	expected = 'beepfoo';
+	t.strictEqual( actual, expected, 'returns expected value' );
+
+	str = 'beep boop baz';
+	actual = replaceAfterLast( str, 'beep', 'foo', -100 );
 	expected = 'beep boop baz';
 	t.strictEqual( actual, expected, 'returns expected value' );