Clean-up docs, tests, and examples

Author: kgryte

lib/node_modules/@stdlib/string/replace/README.md

@@ -18,7 +18,7 @@ limitations under the License.
 
 -->
 
-# Replace
+# replace
 
 > Replace search occurrences with a replacement string.
 
@@ -32,14 +32,14 @@ var replace = require( '@stdlib/string/replace' );
 
 #### replace( str, search, newval )
 
-Replaces search occurrences with a replacement `string`.
+Replaces search occurrences with a replacement string.
 
 ```javascript
 var out = replace( 'beep', 'e', 'o' );
 // returns 'boop'
 ```
 
-If provided a `function` as the [third argument][replacer], the function is invoked for each match, and the function's return value is used as the replacement `string`.
+If provided a function as the [third argument][mdn-string-replace], the function is invoked for each match, and the function's return value is used as the replacement string.
 
 ```javascript
 function replacer( match, p1 ) {
@@ -58,7 +58,7 @@ var out = replace( str, /([^\s]+)/gi, replacer );
 
 ## Notes
 
--   The function has one notable difference from [`String.prototype.replace`][mdn]. When provided a `string` as the `search` value, the function replaces **all** occurrences. To remove only the first match, use a regular expression.
+-   The function has one notable difference from [`String.prototype.replace`][mdn-string-replace]. When provided a string as the `search` value, the function replaces **all** occurrences. To remove only the first match, use a regular expression.
 
     ```javascript
     var out = replace( 'beep', /e/, 'o' );
@@ -79,22 +79,18 @@ var out = replace( str, /([^\s]+)/gi, replacer );
 var capitalize = require( '@stdlib/string/capitalize' );
 var replace = require( '@stdlib/string/replace' );
 
-var out;
-var str;
-
-out = replace( 'beep', 'e', 'o' );
+var out = replace( 'beep', 'e', 'o' );
 // returns 'boop'
 
 out = replace( 'Hello World', /world/i, 'Mr. President' );
 // returns 'Hello Mr. President'
 
-str = 'Oranges and lemons say the bells of St. Clement\'s';
-out = replace( str, /([^\s]*)/gi, replacer );
-// returns 'Oranges And Lemons Say The Bells Of St. Clement\'s'
-
 function replacer( match, p1 ) {
     return capitalize( p1 );
 }
+var str = 'Oranges and lemons say the bells of St. Clement\'s';
+out = replace( str, /([^\s]*)/gi, replacer );
+// returns 'Oranges And Lemons Say The Bells Of St. Clement\'s'
 ```
 
 </section>
@@ -162,9 +158,7 @@ beep
 
 <section class="links">
 
-[mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace
-
-[replacer]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace#Specifying_a_function_as_a_parameter
+[mdn-string-replace]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace
 
 [standard-streams]: https://en.wikipedia.org/wiki/Standard_streams
 

lib/node_modules/@stdlib/string/replace/benchmark/benchmark.js

@@ -22,24 +22,29 @@
 
 var bench = require( '@stdlib/bench' );
 var isString = require( '@stdlib/assert/is-string' ).isPrimitive;
-var fromCodePoint = require( '@stdlib/string/from-code-point' );
 var pkg = require( './../package.json' ).name;
 var replace = require( './../lib' );
 
 
 // MAIN //
 
 bench( pkg+'::string', function benchmark( b ) {
+	var values;
 	var out;
 	var str;
 	var i;
 
+	values = [
+		'abc',
+		'def',
+		'hig'
+	];
 	str = 'To be, or not to be, that is the question.';
 
 	b.tic();
 	for ( i = 0; i < b.iterations; i++ ) {
-		out = replace( str, 'be', fromCodePoint( i%126 ) );
-		if ( !isString( out ) ) {
+		out = replace( str, 'be', values[ i%values.length ] );
+		if ( typeof out !== 'string' ) {
 			b.fail( 'should return a string' );
 		}
 	}
@@ -52,18 +57,24 @@ bench( pkg+'::string', function benchmark( b ) {
 });
 
 bench( pkg+'::regexp', function benchmark( b ) {
+	var values;
 	var out;
 	var str;
 	var re;
 	var i;
 
+	values = [
+		'abc',
+		'def',
+		'hig'
+	];
 	str = 'To be, or not to be, that is the question.';
 	re = /be/g;
 
 	b.tic();
 	for ( i = 0; i < b.iterations; i++ ) {
-		out = replace( str, re, fromCodePoint( i%126 ) );
-		if ( !isString( out ) ) {
+		out = replace( str, re, values[ i%values.length ] );
+		if ( typeof out !== 'string' ) {
 			b.fail( 'should return a string' );
 		}
 	}
@@ -85,7 +96,7 @@ bench( pkg+'::replacer', function benchmark( b ) {
 	b.tic();
 	for ( i = 0; i < b.iterations; i++ ) {
 		out = replace( str, 'be', replacer );
-		if ( !isString( out ) ) {
+		if ( typeof out !== 'string' ) {
 			b.fail( 'should return a string' );
 		}
 	}

lib/node_modules/@stdlib/string/replace/docs/repl.txt

@@ -1,8 +1,8 @@
 
 {{alias}}( str, search, newval )
-    Replaces `search` occurrences with a replacement `string`.
+    Replaces `search` occurrences with a replacement string.
 
-    When provided a `string` as the `search` value, the function replaces *all*
+    When provided a string as the search value, the function replaces *all*
     occurrences. To remove only the first match, use a regular expression.
 
     Parameters

lib/node_modules/@stdlib/string/replace/docs/types/index.d.ts

@@ -19,11 +19,11 @@
 // TypeScript Version: 2.0
 
 /**
-* Replace search occurrences with a replacement string.
+* Replaces search occurrences with a replacement string.
 *
 * ## Notes
 *
-* -   When provided a `string` as the `search` value, the function replaces *all* occurrences. To remove only the first match, use a regular expression.
+* -   When provided a `string` as the `search` value, the function replaces **all** occurrences. To remove only the first match, use a regular expression.
 *
 * @param str - input string
 * @param search - search expression
@@ -52,11 +52,7 @@
 * var out = replace( str, /([^\s]*)/gi, replacer);
 * // returns 'Oranges And Lemons Say The Bells Of St. Clement\'s'
 */
-declare function repeat(
-	str: string,
-	search: string | RegExp,
-	newval: string | Function
-): string;
+declare function repeat( str: string, search: string | RegExp, newval: string | Function ): string; // tslint:disable-line:max-line-length
 
 
 // EXPORTS //

lib/node_modules/@stdlib/string/replace/docs/types/test.ts

@@ -28,7 +28,7 @@ import replace = require( './index' );
 	replace( 'abd', /[a-z]/, (): string => 'z' ); // $ExpectType string
 }
 
-// The function does not compile if provided arguments of invalid types...
+// The compiler throws an error if the function is provided arguments having invalid types...
 {
 	replace( true, 'd', 'a' ); // $ExpectError
 	replace( false, 'd', 'a' ); // $ExpectError
@@ -52,7 +52,7 @@ import replace = require( './index' );
 	replace( 'abd', 'd', /[a-z]/ ); // $ExpectError
 }
 
-// The function does not compile if provided insufficient arguments...
+// The compiler throws an error if the function is provided insufficient arguments...
 {
 	replace(); // $ExpectError
 	replace( 'abc' ); // $ExpectError

lib/node_modules/@stdlib/string/replace/examples/index.js

@@ -21,20 +21,18 @@
 var capitalize = require( '@stdlib/string/capitalize' );
 var replace = require( './../lib' );
 
-var out;
-var str;
-
-console.log( replace( 'beep', 'e', 'o' ) );
+var out = replace( 'beep', 'e', 'o' );
+console.log( out );
 // => 'boop'
 
-console.log( replace( 'Hello World', /world/i, 'Mr. President' ) );
-// => 'Hello Mr. President'
-
-str = 'Oranges and lemons say the bells of St. Clement\'s';
-out = replace( str, /([^\s]*)/gi, replacer );
+out = replace( 'Hello World', /world/i, 'Mr. President' );
 console.log( out );
-// => 'Oranges And Lemons Say The Bells Of St. Clement\'s'
+// => 'Hello Mr. President'
 
 function replacer( match, p1 ) {
 	return capitalize( p1 );
 }
+var str = 'Oranges and lemons say the bells of St. Clement\'s';
+out = replace( str, /([^\s]*)/gi, replacer );
+console.log( out );
+// => 'Oranges And Lemons Say The Bells Of St. Clement\'s'

lib/node_modules/@stdlib/string/replace/lib/index.js

@@ -37,9 +37,9 @@
 
 // MODULES //
 
-var replace = require( './replace.js' );
+var main = require( './main.js' );
 
 
 // EXPORTS //
 
-module.exports = replace;
+module.exports = main;

lib/node_modules/@stdlib/string/replace/lib/replace.js renamed to lib/node_modules/@stdlib/string/replace/lib/main.js

@@ -30,7 +30,7 @@ var format = require( '@stdlib/string/format' );
 // MAIN //
 
 /**
-* Replace search occurrences with a replacement string.
+* Replaces search occurrences with a replacement string.
 *
 * @param {string} str - input string
 * @param {(string|RegExp)} search - search expression
@@ -67,10 +67,8 @@ function replace( str, search, newval ) {
 		throw new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) );
 	}
 	if ( isString( search ) ) {
-		search = rescape( search );
-		search = new RegExp( search, 'g' );
-	}
-	else if ( !isRegExp( search ) ) {
+		search = new RegExp( rescape( search ), 'g' );
+	} else if ( !isRegExp( search ) ) {
 		throw new TypeError( format( 'invalid argument. Second argument must be a string or regular expression. Value: `%s`.', search ) );
 	}
 	if ( !isString( newval ) && !isFunction( newval ) ) {

lib/node_modules/@stdlib/string/replace/test/test.js

@@ -40,6 +40,7 @@ tape( 'the function throws an error if the first argument is not a string', func
 		5,
 		null,
 		true,
+		false,
 		void 0,
 		NaN,
 		[],
@@ -68,6 +69,7 @@ tape( 'the function throws an error if the second argument is not a string or re
 		5,
 		null,
 		true,
+		false,
 		void 0,
 		NaN,
 		[],
@@ -87,14 +89,15 @@ tape( 'the function throws an error if the second argument is not a string or re
 	}
 });
 
-tape( 'the function throws an error if the third argument is not a function or string primitive', function test( t ) {
+tape( 'the function throws an error if the third argument is not a function or string', function test( t ) {
 	var values;
 	var i;
 
 	values = [
 		5,
 		null,
 		true,
+		false,
 		void 0,
 		NaN,
 		[],
@@ -117,13 +120,13 @@ tape( 'the function replaces all occurrences of a string search value', function
 	var out;
 
 	out = replace( 'abc abc abc', 'b', '' );
-	t.equal( out, 'ac ac ac', 'replaces all occurrences of letter `b`' );
+	t.equal( out, 'ac ac ac', 'returns expected value' );
 
 	out = replace( 'abc abc abc', 'b', 'cd' );
-	t.equal( out, 'acdc acdc acdc', 'replaces all occurrences of letter `b` by `cd`' );
+	t.equal( out, 'acdc acdc acdc', 'returns expected value' );
 
 	out = replace( 'Et tu, Brute?', 'Brute?', 'Caesar?' );
-	t.equal( out, 'Et tu, Caesar?', 'replaces `Brute?`' );
+	t.equal( out, 'Et tu, Caesar?', 'returns expected value' );
 
 	t.end();
 });
@@ -143,19 +146,20 @@ tape( 'the function replaces matches of a regular expression', function test( t
 	t.end();
 });
 
-tape( 'the function replaces found matches by values created from a replacer function', function test( t ) {
+tape( 'the function replaces matches with values returned by a replacer function', function test( t ) {
 	var expected;
 	var out;
 	var str;
 
-	function replacer( match, p1 ) {
-		return '/' + p1 + '/';
-	}
-
 	str = 'Oranges and lemons say the bells of St. Clement\'s';
 	out = replace( str, /([^\s]+)/gi, replacer );
+
 	expected = '/Oranges/ /and/ /lemons/ /say/ /the/ /bells/ /of/ /St./ /Clement\'s/';
 	t.equal( out, expected, 'replaces matches using replacer function' );
 
 	t.end();
+
+	function replacer( match, p1 ) {
+		return '/' + p1 + '/';
+	}
 });