feat!: distinguish between signed zeros

This commit refactors the implementation to rely on the same value
algorithm, rather than strict equality. Previously, we treated NaN
values as equal, which follows the same value algorithm; however,
we did not distinguish between signed zeros. This commit ensures
that we follow the same value algorithm fully.

BREAKING CHANGE: distinguish signed zeros

To migrate, users should normalize signed zeros before invoking
this function. Otherwise, users should use a different algorithm
which uses strict equality to determine "sameness" (e.g., a package
such as `@stdlib/array/base/includes`).

---
type: pre_commit_static_analysis_report
description: Results of running static analysis checks when committing changes.
report:
  - task: lint_filenames
    status: passed
  - task: lint_editorconfig
    status: passed
  - task: lint_markdown
    status: passed
  - task: lint_package_json
    status: na
  - task: lint_repl_help
    status: passed
  - task: lint_javascript_src
    status: passed
  - task: lint_javascript_cli
    status: na
  - task: lint_javascript_examples
    status: na
  - task: lint_javascript_tests
    status: passed
  - task: lint_javascript_benchmarks
    status: na
  - task: lint_python
    status: na
  - task: lint_r
    status: na
  - task: lint_c_src
    status: na
  - task: lint_c_examples
    status: na
  - task: lint_c_benchmarks
    status: na
  - task: lint_c_tests_fixtures
    status: na
  - task: lint_shell
    status: na
  - task: lint_typescript_declarations
    status: passed
  - task: lint_typescript_tests
    status: na
  - task: lint_license_headers
    status: passed
---

Author: kgryte

lib/node_modules/@stdlib/assert/contains/README.md

@@ -18,7 +18,7 @@ limitations under the License.
 
 -->
 
-# Contains
+# contains
 
 > Test if an array-like value contains a search value.
 
@@ -36,16 +36,23 @@ limitations under the License.
 var contains = require( '@stdlib/assert/contains' );
 ```
 
-#### contains( val, searchValue\[, position] )
+#### contains( value, searchValue\[, position] )
 
-Tests if `val` contains a search value. When `val` is a `string`, the function checks whether the characters of a search string are found in the input string.
+Tests if `value` contains a search value.
+
+```javascript
+var v = contains( [ 1, 2, 3 ], 2 );
+// returns true
+```
+
+When `value` is a string, the function checks whether the characters of a search string are found in the input string.
 
 ```javascript
 var v = contains( 'Hello World', 'World' );
 // returns true
 ```
 
-When `val` is an `array-like` object, but not a `string`, the function checks whether the input value contains an element strictly equal to the specified search value.
+When `value` is an array-like object, but not a string, the function checks whether the input value contains an element which is the [same value][@stdlib/assert/is-same-value] as the specified search value.
 
 ```javascript
 var arr = [ null, NaN, 2, 'abc', {} ];
@@ -77,7 +84,7 @@ v = contains( [ true, NaN, false ], true, 1 );
 // returns false
 ```
 
-If not provided an `array-like` object, the function throws an error.
+If not provided an array-like object, the function throws an error.
 
 <!-- run throws: true -->
 
@@ -105,8 +112,8 @@ var v = contains( 'hello', 'e', 2.5 );
 
 ## Notes
 
--   For `strings`, the function is modeled after [String.prototype.includes][mdn-includes], part of the ECMAScript 6 specification. This function is different from a call to `String.prototype.includes.call` insofar as type-checking is performed for all arguments.
--   The function does **not** distinguish between positive and negative zero.
+-   For strings, the function is modeled after [String.prototype.includes][mdn-includes], part of the ECMAScript 6 specification. This function is different from a call to `String.prototype.includes.call` insofar as type-checking is performed for all arguments.
+-   The function **does** distinguish between positive and negative zero (see [`@stdlib/assert/is-same-value`][@stdlib/assert/is-same-value].
 -   If `position < 0`, the search is performed for the entire input array or string.
 
 </section>
@@ -159,6 +166,8 @@ bool = contains( 'Hidden Treasures', '' );
 
 [mdn-includes]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/includes
 
+[@stdlib/assert/is-same-value]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/assert/is-same-value
+
 </section>
 
 <!-- /.links -->

lib/node_modules/@stdlib/assert/contains/docs/repl.txt

@@ -1,27 +1,27 @@
 
-{{alias}}( val, searchValue[, position] )
+{{alias}}( value, searchValue[, position] )
     Tests if an array-like value contains a search value.
 
-    When `val` is a string, the function checks whether the characters of the
+    When `value` is a string, the function checks whether the characters of the
     search string are found in the input string. The search is case-sensitive.
 
-    When `val` is an array-like object, the function checks whether the input
+    When `value` is an array-like object, the function checks whether the input
     array contains an element strictly equal to the specified search value.
 
     For strings, this function is modeled after `String.prototype.includes`,
     part of the ECMAScript 6 specification. This function is different from a
     call to `String.prototype.includes.call` insofar as type-checking is
     performed for all arguments.
 
-    The function does not distinguish between positive and negative zero.
+    The function does distinguish between positive and negative zero.
 
     If `position < 0`, the search is performed for the entire input array or
     string.
 
 
     Parameters
     ----------
-    val: ArrayLike
+    value: ArrayLike
         Input value.
 
     searchValue: any

lib/node_modules/@stdlib/assert/contains/docs/types/index.d.ts

@@ -27,13 +27,13 @@ import { ArrayLike } from '@stdlib/types/array';
 *
 * ## Notes
 *
-* -   When `val` is a string, the function checks whether the characters of the search string are found in the input string. The search is case-sensitive.
-* -   When `val` is an array-like object, the function checks whether the input array contains an element strictly equal to the specified search value.
+* -   When `value` is a string, the function checks whether the characters of the search string are found in the input string. The search is case-sensitive.
+* -   When `value` is an array-like object, the function checks whether the input array contains an element which is the same as the specified search value.
 * -   For strings, this function is modeled after `String.prototype.includes`, part of the ECMAScript 6 specification. This function is different from a call to `String.prototype.includes.call` insofar as type-checking is performed for all arguments.
-* -   The function does not distinguish between positive and negative zero.
+* -   The function does distinguish between positive and negative zero.
 * -   If `position < 0`, the search is performed for the entire input array or string.
 *
-* @param val - input value
+* @param value - input value
 * @param searchValue - search value
 * @param position - position at which to start searching for `searchValue` (default: 0)
 * @throws second argument must be a primitive string primitive when the first argument is a string
@@ -67,7 +67,7 @@ import { ArrayLike } from '@stdlib/types/array';
 * var bool = contains( 'Hidden Treasures', '' );
 * // returns true
 */
-declare function contains( val: ArrayLike<any>, searchValue: any, position?: number ): boolean;
+declare function contains( value: ArrayLike<unknown>, searchValue: unknown, position?: number ): boolean;
 
 
 // EXPORTS //

lib/node_modules/@stdlib/assert/contains/lib/main.js

@@ -23,7 +23,7 @@
 var isCollection = require( '@stdlib/assert/is-collection' );
 var isInteger = require( '@stdlib/assert/is-integer' ).isPrimitive;
 var isString = require( '@stdlib/assert/is-string' ).isPrimitive;
-var isnan = require( '@stdlib/assert/is-nan' ).isPrimitive;
+var isSameValue = require( '@stdlib/assert/is-same-value' );
 var format = require( '@stdlib/string/format' );
 
 
@@ -32,7 +32,7 @@ var format = require( '@stdlib/string/format' );
 /**
 * Tests if an array-like value contains a search value.
 *
-* @param {(Collection|string)} val - input value
+* @param {(Collection|string)} value - input value
 * @param {*} searchValue - search value
 * @param {integer} [position=0] - position at which to start searching for `searchValue`
 * @throws {TypeError} first argument must be array-like
@@ -69,12 +69,15 @@ var format = require( '@stdlib/string/format' );
 * var bool = contains( 'Hidden Treasures', '' );
 * // returns true
 */
-function contains( val, searchValue, position ) {
+function contains( value, searchValue, position ) {
+	var isStr;
 	var len;
 	var pos;
 	var i;
-	if ( !isCollection( val ) && !isString( val ) ) {
-		throw new TypeError( format( 'invalid argument. First argument must be array-like. Value: `%s`.', val ) );
+
+	isStr = isString( value );
+	if ( !isCollection( value ) && !isStr ) {
+		throw new TypeError( format( 'invalid argument. First argument must be array-like. Value: `%s`.', value ) );
 	}
 	if ( arguments.length < 2 ) {
 		throw new Error( 'insufficient arguments. Must provide a search value.' );
@@ -90,23 +93,15 @@ function contains( val, searchValue, position ) {
 	} else {
 		pos = 0;
 	}
-	if ( isString( val ) ) {
+	if ( isStr ) {
 		if ( !isString( searchValue ) ) {
 			throw new TypeError( format( 'invalid argument. Second argument must be a string. Value: `%s`.', searchValue ) );
 		}
-		return val.indexOf( searchValue, pos ) !== -1;
-	}
-	len = val.length;
-	if ( isnan( searchValue ) ) {
-		for ( i = pos; i < len; i++ ) {
-			if ( isnan( val[ i ] ) ) {
-				return true;
-			}
-		}
-		return false;
+		return value.indexOf( searchValue, pos ) !== -1;
 	}
+	len = value.length;
 	for ( i = pos; i < len; i++ ) {
-		if ( val[ i ] === searchValue ) {
+		if ( isSameValue( value[ i ], searchValue ) ) {
 			return true;
 		}
 	}

lib/node_modules/@stdlib/assert/contains/test/test.js

@@ -129,13 +129,13 @@ tape( 'the function returns `true` when a search string is contained in input st
 	var out;
 
 	out = contains( 'Hello World', 'World' );
-	t.equal( out, true, 'returns true' );
+	t.equal( out, true, 'returns expected value' );
 
 	out = contains( 'Hello World', ' ' );
-	t.equal( out, true, 'returns true' );
+	t.equal( out, true, 'returns expected value' );
 
 	out = contains( 'Hello World', 'Hell' );
-	t.equal( out, true, 'returns true' );
+	t.equal( out, true, 'returns expected value' );
 
 	t.end();
 });
@@ -144,13 +144,13 @@ tape( 'the function returns `false` when a search string is not contained in inp
 	var out;
 
 	out = contains( 'Hello World', 'world' );
-	t.equal( out, false, 'returns false' );
+	t.equal( out, false, 'returns expected value' );
 
 	out = contains( 'Hello World', '\t' );
-	t.equal( out, false, 'returns false' );
+	t.equal( out, false, 'returns expected value' );
 
 	out = contains( 'Hello World', 'Word' );
-	t.equal( out, false, 'returns false' );
+	t.equal( out, false, 'returns expected value' );
 
 	t.end();
 });
@@ -159,13 +159,13 @@ tape( 'the function returns `true` when a search value is contained in input arr
 	var out;
 
 	out = contains( [ NaN, null, 3, 'abc' ], 'abc' );
-	t.equal( out, true, 'returns true' );
+	t.equal( out, true, 'returns expected value' );
 
 	out = contains( [ NaN, null, 3, 'abc' ], NaN );
-	t.equal( out, true, 'returns true' );
+	t.equal( out, true, 'returns expected value' );
 
 	out = contains( [ NaN, null, 3, 'abc' ], null );
-	t.equal( out, true, 'returns true' );
+	t.equal( out, true, 'returns expected value' );
 
 	t.end();
 });
@@ -174,13 +174,13 @@ tape( 'the function returns `false` when search value is not contained in input
 	var out;
 
 	out = contains( [ NaN, null, 3, 'abc' ], 'ac' );
-	t.equal( out, false, 'returns false' );
+	t.equal( out, false, 'returns expected value' );
 
 	out = contains( [ NaN, null, 3, 'abc' ], false );
-	t.equal( out, false, 'returns false' );
+	t.equal( out, false, 'returns expected value' );
 
 	out = contains( [ NaN, null, 3, 'abc' ], 3.5 );
-	t.equal( out, false, 'returns false' );
+	t.equal( out, false, 'returns expected value' );
 
 	t.end();
 });
@@ -189,48 +189,50 @@ tape( 'the function supports beginning a search at the specified position', func
 	var out;
 
 	out = contains( 'ABCDEFG', 'A', 1 );
-	t.equal( out, false, 'returns false' );
+	t.equal( out, false, 'returns expected value' );
 
 	out = contains( 'ABCDEFG', 'B', 1 );
-	t.equal( out, true, 'returns true' );
+	t.equal( out, true, 'returns expected value' );
 
 	out = contains( 'ABCDEFG', 'A', -3 );
-	t.equal( out, true, 'returns true' );
+	t.equal( out, true, 'returns expected value' );
 
 	out = contains( [ null, NaN, 2 ], 3, 1 );
-	t.equal( out, false, 'returns false' );
+	t.equal( out, false, 'returns expected value' );
 
 	out = contains( [ null, NaN, 2 ], NaN, 1 );
-	t.equal( out, true, 'returns true' );
+	t.equal( out, true, 'returns expected value' );
 
 	out = contains( [ null, NaN, 2 ], NaN, -3 );
-	t.equal( out, true, 'returns true' );
+	t.equal( out, true, 'returns expected value' );
 
 	out = contains( [ null, NaN, 2 ], NaN, 2 );
-	t.equal( out, false, 'returns false' );
+	t.equal( out, false, 'returns expected value' );
 
 	t.end();
 });
 
 tape( 'the function returns `true` if provided an input string and an empty string as the search value', function test( t ) {
-	t.equal( contains( 'abc', '' ), true, 'returns true' );
-	t.equal( contains( '', '' ), true, 'returns true' );
+	t.equal( contains( 'abc', '' ), true, 'returns expected value' );
+	t.equal( contains( '', '' ), true, 'returns expected value' );
 	t.end();
 });
 
 tape( 'the function returns `false` if provided an empty array-like value', function test( t ) {
-	t.equal( contains( [], '' ), false, 'returns false' );
+	t.equal( contains( [], '' ), false, 'returns expected value' );
 	t.end();
 });
 
-tape( 'the function does not distinguish between positive and negative zero', function test( t ) {
-	t.equal( contains( [ -0.0 ], +0.0 ), true, 'returns true' );
-	t.equal( contains( [ +0.0 ], -0.0 ), true, 'returns true' );
+tape( 'the function does distinguish between positive and negative zero', function test( t ) {
+	t.equal( contains( [ -0.0 ], +0.0 ), false, 'returns expected value' );
+	t.equal( contains( [ +0.0 ], -0.0 ), false, 'returns expected value' );
+	t.equal( contains( [ -0.0 ], -0.0 ), true, 'returns expected value' );
+	t.equal( contains( [ +0.0 ], +0.0 ), true, 'returns expected value' );
 	t.end();
 });
 
 tape( 'the function returns `false` if provided a position which exceeds the maximum index', function test( t ) {
-	t.equal( contains( [ 1 ], 1, 1e5 ), false, 'returns false' );
-	t.equal( contains( 'abc', 'a', 1e5 ), false, 'returns false' );
+	t.equal( contains( [ 1 ], 1, 1e5 ), false, 'returns expected value' );
+	t.equal( contains( 'abc', 'a', 1e5 ), false, 'returns expected value' );
 	t.end();
 });