Add one or more elements to the beginning of a collection.
APACHE-2.0 License
Add one or more elements to the beginning of a collection.
npm install @stdlib/utils-unshift
Alternatively,
script
tag without installation and bundlers, use the ES Module available on the esm
branch (see README).deno
branch (see README for usage intructions).umd
branch (see README).The branches.md file summarizes the available branches and displays a diagram illustrating their relationships.
To view installation and usage instructions specific to each branch build, be sure to explicitly navigate to the respective README files on each branch, as linked to above.
var unshift = require( '@stdlib/utils-unshift' );
Adds one or more elements to the beginning of a collection
. A collection
may be either an Array
, Typed Array
, or an array-like Object
(i.e., an Object
having a valid writable length
property).
var arr = [ 1.0, 2.0, 3.0, 4.0, 5.0 ];
var out = unshift( arr, 6.0, 7.0 );
// returns [ 6.0, 7.0, 1.0, 2.0, 3.0, 4.0, 5.0 ]
var bool = ( out === arr );
// returns true
In contrast to Array.prototype.unshift
, the function returns the extended collection, rather than the collection length. For typed arrays, the returned value is a new typed array view whose underlying ArrayBuffer
may not equal the underlying ArrayBuffer
for the input collection
.
var ArrayBuffer = require( '@stdlib/array-buffer' );
var Float64Array = require( '@stdlib/array-float64' );
var buf = new ArrayBuffer( 3*8 ); // 8 bytes per double
var arr = new Float64Array( buf, 8, 2 );
arr[ 0 ] = 1.0;
arr[ 1 ] = 2.0;
var out = unshift( arr, 3.0 );
// returns <Float64Array>[ 3.0, 1.0, 2.0 ]
var bool = ( out === arr );
// returns false
bool = ( out.buffer === arr.buffer );
// returns true
out = unshift( out, 4.0 );
// returns <Float64Array>[ 4.0, 3.0, 1.0, 2.0 ]
bool = ( out.buffer === arr.buffer );
// returns false
ArrayBuffer
. If an ArrayBuffer
does not have enough bytes in which to store all elements, the function allocates a new ArrayBuffer
capable of holding 2^n
elements, where n
is the next power of 2
. This procedure is similar to how environments internally handle dynamic memory allocation for Arrays
.ArrayBuffer
. Because the function sets ArrayBuffer
bytes outside of a provided view, the function may overwrite bytes belonging to one or more external views. This could be a potential security vulnerability. Prefer providing typed arrays which have an exclusive ArrayBuffer
; otherwise, be sure to plan for and guard against mutated state.var Float64Array = require( '@stdlib/array-float64' );
var unshift = require( '@stdlib/utils-unshift' );
var arr;
var i;
arr = new Float64Array();
for ( i = 0; i < 100; i++ ) {
arr = unshift( arr, i );
}
console.log( arr );
@stdlib/utils-pop
: remove and return the last element of a collection.
@stdlib/utils-push
: add one or more elements to the end of a collection.
@stdlib/utils-shift
: remove and return the first element of a collection.
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.
See LICENSE.
Copyright © 2016-2024. The Stdlib Authors.