Flatten Array

    Flatten an array.

    Usage

    var flattenArray = require( '@stdlib/utils/flatten-array' );
    

    flattenArray( arr[, options] )

    Flattens an array.

    var arr = [ 1, [2, [3, [4, [ 5 ], 6], 7], 8], 9 ];
    
    var out = flattenArray( arr );
    // returns [ 1, 2, 3, 4, 5, 6, 7, 8, 9 ]
    

    The function accepts the following options:

    • depth: maximum depth to flatten.
    • copy: boolean indicating whether to deep copy array elements. Default: false.

    To flatten to a specified depth, set the depth option.

    var arr = [ 1, [2, [3, [4, [ 5 ], 6], 7], 8], 9 ];
    
    var out = flattenArray( arr, {
        'depth': 2
    });
    // returns [ 1, 2, 3, [4, [5], 6], 7, 8, 9 ]
    
    var bool = ( arr[1][1][1] === out[3] );
    // returns true
    

    To deep copy array elements, set the copy option to true.

    var arr = [ 1, [2, [3, [4, [ 5 ], 6], 7], 8], 9 ];
    
    var out = flattenArray( arr, {
        'depth': 2,
        'copy': true
    });
    // returns [ 1, 2, 3, [4, [5], 6], 7, 8, 9 ]
    
    var bool = ( arr[1][1][1] === out[3] );
    // returns false
    

    flattenArray.factory( dims[, options] )

    Returns a function optimized for flattening arrays having specified dimensions.

    var flatten = flattenArray.factory( [ 3, 3 ] );
    
    var arr = [
        [ 1, 2, 3 ],
        [ 4, 5, 6 ],
        [ 7, 8, 9 ]
    ];
    
    var out = flatten( arr );
    // returns [ 1, 2, 3, 4, 5, 6, 7, 8, 9 ]
    
    arr = [
        [ 11, 12, 13 ],
        [ 14, 15, 16 ],
        [ 17, 18, 19 ]
    ];
    
    out = flatten( arr );
    // returns [ 11, 12, 13, 14, 15, 16, 17, 18, 19 ]
    

    The function accepts the following options:

    • copy: boolean indicating whether to deep copy array elements. Default: false.

    To deep copy array elements, set the copy option to true.

    var flatten = flattenArray.factory( [ 3, 3 ], {
        'copy': true
    });
    
    var arr = [
        [ 1, 2, 3 ],
        [ 4, { 'x': 5 }, 6 ],
        [ 7, 8, 9 ]
    ];
    
    var out = flatten( arr );
    // returns [ 1, 2, 3, 4, {'x':5}, 6, 7, 8, 9 ]
    
    var bool = ( arr[1][1] === out[4] );
    // returns false
    

    Notes

    • A flatten function returned by the factory method does not validate that input arrays actually have the specified dimensions.

    Examples

    var flattenArray = require( '@stdlib/utils/flatten-array' );
    
    var xStride;
    var yStride;
    var zStride;
    var bool;
    var tmp1;
    var tmp2;
    var arr;
    var val;
    var out;
    var N;
    var M;
    var L;
    var i;
    var j;
    var k;
    
    N = 1000;
    M = 100;
    L = 10;
    
    // Create an NxMxL (3D) array...
    arr = new Array( N );
    for ( i = 0; i < N; i++ ) {
        tmp1 = new Array( M );
        for ( j = 0; j < M; j++ ) {
            tmp2 = new Array( L );
            for ( k = 0; k < L; k++ ) {
                tmp2[ k ] = (M*L*i) + (j*L) + k + 1;
            }
            tmp1[ j ] = tmp2;
        }
        arr[ i ] = tmp1;
    }
    // Create a flattened (strided) array:
    out = flattenArray( arr );
    
    // To access the arr[4][20][2] element...
    xStride = M * L;
    yStride = L;
    zStride = 1;
    val = out[ (4*xStride) + (20*yStride) + (2*zStride) ];
    // returns 4203
    
    bool = ( arr[4][20][2] === val );
    // returns true