@stdlib/assert-contains
v0.2.2
Published
Test if an array-like value contains a search value.
Downloads
14,507
Readme
Contains
Test if an array-like value contains a search value.
Installation
npm install @stdlib/assert-contains
Usage
var contains = require( '@stdlib/assert-contains' );
contains( val, 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.
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.
var arr = [ null, NaN, 2, 'abc', {} ];
var v = contains( arr, NaN ); // NaNs are considered equal
// returns true
v = contains( arr, {} );
// returns false
v = contains( arr, 'ab' );
// returns false
Search is case-sensitive.
var v = contains( 'Hello World', 'world' );
// returns false
To start searching at a specified index, provide a position
argument.
var v = contains( 'Hello World', 'Hello', 6 );
// returns false
v = contains( [ true, NaN, false ], true, 1 );
// returns false
If not provided an array-like
object, the function throws an error.
var v = contains( false, 'abc' );
// throws <TypeError>
If not provided an integer-valued position
argument, the function throws an error.
var v = contains( 'hello', 'e', 2.5 );
// throws <TypeError>
Notes
- For
strings
, the function is modeled after String.prototype.includes, part of the ECMAScript 6 specification. This function is different from a call toString.prototype.includes.call
insofar as type-checking is performed for all arguments. - The function does not distinguish between positive and negative zero.
- If
position < 0
, the search is performed for the entire input array or string.
Examples
var contains = require( '@stdlib/assert-contains' );
var bool = contains( 'last man standing', 'stand' );
// returns true
bool = contains( [ 1, 2, 3, 4 ], 2 );
// returns true
bool = contains( 'presidential election', 'president' );
// returns true
bool = contains( [ NaN, 2, 3, 4 ], NaN );
// returns true
bool = contains( 'javaScript', 'js' );
// returns false
bool = contains( 'Hidden Treasures', '' );
// returns true
Notice
This package is part of stdlib, a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more.
For more information on the project, filing bug reports and feature requests, and guidance on how to develop stdlib, see the main project repository.
Community
License
See LICENSE.
Copyright
Copyright © 2016-2024. The Stdlib Authors.