feat!: support negative fromIndex arguments

BREAKING CHANGE: resolve negative indices relative to last index

In order to preserve prior behavior, users should insert a manual
check before calling this API.

Ref: #1364
Ref: 272f91b

Author: kgryte

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

@@ -53,14 +53,22 @@ out = replaceBeforeLast( str, 'o', 'bar', str.length );
 // returns 'barop'
 ```
 
-The search starts at the end of the string and proceeds backwards to the beginning. To start the search at a specified index, specify an integer for the `fromIndex` argument.
+To begin searching from a specific index, provide a corresponding `fromIndex` argument.
 
 ```javascript
 var str = 'beep boop beep';
 var out = replaceBeforeLast( str, ' ', 'loop', 5 );
 // returns 'loop boop beep'
 ```
 
+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 str = 'beep boop beep';
+var out = replaceBeforeLast( str, ' ', 'loop', -1 );
+// returns 'loop beep'
+```
+
 </section>
 
 <!-- /.usage -->
@@ -73,7 +81,7 @@ var out = replaceBeforeLast( str, ' ', 'loop', 5 );
 
 -   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-before-last/docs/repl.txt

@@ -3,6 +3,12 @@
     Replaces the substring before 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-before-last/docs/types/index.d.ts

@@ -21,6 +21,12 @@
 /**
 * Replaces the substring before 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 chraacter, with the last string chraacter corresponding to `fromIndex = -1`.
+*
 * @param str - input string
 * @param search - search string
 * @param replacement - replacement string

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

@@ -62,7 +62,10 @@
 function replaceBeforeLast( 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-before-last/test/test.js

@@ -95,6 +95,11 @@ tape( 'the function replaces the substring before a provided search string (cust
 
 	str = 'beep boop baz';
 	actual = replaceBeforeLast( str, 'beep', 'foo', -2 );
+	expected = 'foobeep boop baz';
+	t.strictEqual( actual, expected, 'returns expected value' );
+
+	str = 'beep boop baz';
+	actual = replaceBeforeLast( str, 'beep', 'foo', -20 );
 	expected = 'beep boop baz';
 	t.strictEqual( actual, expected, 'returns expected value' );