Contains

    Test if an array-like value contains a search value.

    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 to String.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