# Int32Array > [Typed array][mdn-typed-array] constructor which returns a [typed array][mdn-typed-array] representing an array of twos-complement 32-bit signed integers in the platform byte order.
## Usage ```javascript var Int32Array = require( '@stdlib/array/int32' ); ``` #### Int32Array() A [typed array][mdn-typed-array] constructor which returns a [typed array][mdn-typed-array] representing an array of twos-complement 32-bit signed integers in the platform byte order. ```javascript var arr = new Int32Array(); // returns ``` #### Int32Array( length ) Returns a [typed array][mdn-typed-array] having a specified length. ```javascript var arr = new Int32Array( 5 ); // returns [ 0, 0, 0, 0, 0 ] ``` #### Int32Array( typedarray ) Creates a [typed array][mdn-typed-array] from another [typed array][mdn-typed-array]. ```javascript var Float32Array = require( '@stdlib/array/float32' ); var arr1 = new Float32Array( [ 5.0, 5.0, 5.0 ] ); var arr2 = new Int32Array( arr1 ); // returns [ 5, 5, 5 ] ``` #### Int32Array( obj ) Creates a [typed array][mdn-typed-array] from an array-like `object` or iterable. ```javascript var arr = new Int32Array( [ 5.0, 5.0, 5.0 ] ); // returns [ 5, 5, 5 ] ``` #### Int32Array( buffer\[, byteOffset\[, length]] ) Returns a [typed array][mdn-typed-array] view of an [`ArrayBuffer`][@stdlib/array/buffer]. ```javascript var ArrayBuffer = require( '@stdlib/array/buffer' ); var buf = new ArrayBuffer( 16 ); var arr = new Int32Array( buf, 0, 4 ); // returns [ 0, 0, 0, 0 ] ``` * * * ### Properties #### Int32Array.BYTES_PER_ELEMENT Number of bytes per view element. ```javascript var nbytes = Int32Array.BYTES_PER_ELEMENT; // returns 4 ``` #### Int32Array.name [Typed array][mdn-typed-array] constructor name. ```javascript var str = Int32Array.name; // returns 'Int32Array' ``` #### Int32Array.prototype.buffer **Read-only** property which returns the [`ArrayBuffer`][@stdlib/array/buffer] referenced by the [typed array][mdn-typed-array]. ```javascript var arr = new Int32Array( 5 ); var buf = arr.buffer; // returns ``` #### Int32Array.prototype.byteLength **Read-only** property which returns the length (in bytes) of the [typed array][mdn-typed-array]. ```javascript var arr = new Int32Array( 5 ); var byteLength = arr.byteLength; // returns 20 ``` #### Int32Array.prototype.byteOffset **Read-only** property which returns the offset (in bytes) of the [typed array][mdn-typed-array] from the start of its [`ArrayBuffer`][@stdlib/array/buffer]. ```javascript var arr = new Int32Array( 5 ); var byteOffset = arr.byteOffset; // returns 0 ``` #### Int32Array.prototype.BYTES_PER_ELEMENT Number of bytes per view element. ```javascript var arr = new Int32Array( 5 ); var nbytes = arr.BYTES_PER_ELEMENT; // returns 4 ``` #### Int32Array.prototype.length **Read-only** property which returns the number of view elements. ```javascript var arr = new Int32Array( 5 ); var len = arr.length; // returns 5 ``` * * * ### Methods #### Int32Array.from( src\[, map\[, thisArg]] ) Creates a new typed array from an array-like `object` or an iterable. ```javascript var arr = Int32Array.from( [ 1, 2 ] ); // returns [ 1, 2 ] ``` To invoke a function for each `src` value, provide a callback function. ```javascript function mapFcn( v ) { return v * 2; } var arr = Int32Array.from( [ 1, 2 ], mapFcn ); // returns [ 2, 4 ] ``` A callback function is provided two arguments: - `value`: source value - `index`: source index To set the callback execution context, provide a `thisArg`. ```javascript function mapFcn( v ) { this.count += 1; return v * 2; } var ctx = { 'count': 0 }; var arr = Int32Array.from( [ 1, 2 ], mapFcn, ctx ); // returns [ 2, 4 ] var n = ctx.count; // returns 2 ``` #### Int32Array.of( element0\[, element1\[, ...elementN]] ) Creates a new typed array from a variable number of arguments. ```javascript var arr = Int32Array.of( 1, 2 ); // returns [ 1, 2 ] ``` #### Int32Array.prototype.copyWithin( target, start\[, end] ) Copies a sequence of elements within an array starting at `start` and ending at `end` (non-inclusive) to the position starting at `target`. ```javascript var arr = new Int32Array( [ 1, 2, 3, 4, 5 ] ); // Copy the last two elements to the first two elements: arr.copyWithin( 0, 3 ); var v = arr[ 0 ]; // returns 4 v = arr[ 1 ]; // returns 5 ``` By default, `end` equals the number of array elements (i.e., one more than the last array index). To limit the sequence length, provide an `end` argument. ```javascript var arr = new Int32Array( [ 1, 2, 3, 4, 5 ] ); // Copy the first two elements to the last two elements: arr.copyWithin( 3, 0, 2 ); var v = arr[ 3 ]; // returns 1 v = arr[ 4 ]; // returns 2 ``` When a `target`, `start`, and/or `end` index is negative, the respective index is determined relative to the last array element. The following example achieves the same behavior as the previous example: ```javascript var arr = new Int32Array( [ 1, 2, 3, 4, 5 ] ); // Copy the first two elements to the last two elements: arr.copyWithin( -2, -5, -3 ); var v = arr[ 3 ]; // returns 1 v = arr[ 4 ]; // returns 2 ``` #### Int32Array.prototype.entries() Returns an iterator for iterating over array key-value pairs. ```javascript var arr = new Int32Array( [ 1, 2 ] ); // Create an iterator: var it = arr.entries(); // Iterate over key-value pairs... var v = it.next().value; // returns [ 0, 1 ] v = it.next().value; // returns [ 1, 2 ] var bool = it.next().done; // returns true ``` #### Int32Array.prototype.every( predicate\[, thisArg] ) Tests whether all array elements pass a test implemented by a `predicate` function. ```javascript function predicate( v ) { return ( v <= 1 ); } var arr = new Int32Array( [ 1, 2 ] ); var bool = arr.every( predicate ); // returns false ``` A `predicate` function is provided three arguments: - `value`: array element - `index`: array index - `arr`: array on which the method is invoked To set the callback execution context, provide a `thisArg`. ```javascript function predicate( v ) { this.count += 1; return ( v >= 1 ); } var ctx = { 'count': 0 }; var arr = new Int32Array( [ 1, 2 ] ); var bool = arr.every( predicate, ctx ); // returns true var n = ctx.count; // returns 2 ``` #### Int32Array.prototype.fill( value\[, start\[, end]] ) Fills an array from a `start` index to an `end` index (non-inclusive) with a provided `value`. ```javascript var arr = new Int32Array( 2 ); // Set all array elements to the same value: arr.fill( 2 ); var v = arr[ 0 ]; // returns 2 v = arr[ 1 ]; // returns 2 // Set all array elements starting from the first index to the same value: arr.fill( 3, 1 ); v = arr[ 0 ]; // returns 2 v = arr[ 1 ]; // returns 3 // Set all array elements, except the last element, to the same value: arr.fill( 4, 0, arr.length-1 ); v = arr[ 0 ]; // returns 4 v = arr[ 1 ]; // returns 3 ``` When a `start` and/or `end` index is negative, the respective index is determined relative to the last array element. ```javascript var arr = new Int32Array( 2 ); // Set all array elements, except the last element, to the same value: arr.fill( 2, -arr.length, -1 ); var v = arr[ 0 ]; // returns 2 v = arr[ 1 ]; // returns 0 ``` #### Int32Array.prototype.filter( predicate\[, thisArg] ) Creates a new array (of the same data type as the host array) which includes those elements for which a `predicate` function returns a truthy value. ```javascript function predicate( v ) { return ( v >= 2 ); } var arr1 = new Int32Array( [ 1, 2, 3 ] ); var arr2 = arr1.filter( predicate ); // returns [ 2, 3 ] ``` If a `predicate` function does not return a truthy value for any array element, the method returns an empty array. ```javascript function predicate( v ) { return ( v >= 10 ); } var arr1 = new Int32Array( [ 1, 2, 3 ] ); var arr2 = arr1.filter( predicate ); // returns [] ``` A `predicate` function is provided three arguments: - `value`: array element - `index`: array index - `arr`: array on which the method is invoked To set the callback execution context, provide a `thisArg`. ```javascript function predicate( v ) { this.count += 1; return ( v >= 2 ); } var ctx = { 'count': 0 }; var arr1 = new Int32Array( [ 1, 2, 3 ] ); var arr2 = arr1.filter( predicate, ctx ); var n = ctx.count; // returns 3 ``` #### Int32Array.prototype.find( predicate\[, thisArg] ) Returns the first array element for which a provided `predicate` function returns a truthy value. ```javascript function predicate( v ) { return ( v > 2 ); } var arr = new Int32Array( [ 1, 2, 3 ] ); var v = arr.find( predicate ); // returns 3 ``` If a `predicate` function does not return a truthy value for any array element, the method returns `undefined`. ```javascript function predicate( v ) { return ( v < 1 ); } var arr = new Int32Array( [ 1, 2, 3 ] ); var v = arr.find( predicate ); // returns undefined ``` A `predicate` function is provided three arguments: - `value`: array element - `index`: array index - `arr`: array on which the method is invoked To set the callback execution context, provide a `thisArg`. ```javascript function predicate( v ) { this.count += 1; return ( v > 2 ); } var ctx = { 'count': 0 }; var arr = new Int32Array( [ 1, 2, 3 ] ); var v = arr.find( predicate, ctx ); // returns 3 var n = ctx.count; // returns 3 ``` #### Int32Array.prototype.findIndex( predicate\[, thisArg] ) Returns the index of the first array element for which a provided `predicate` function returns a truthy value. ```javascript function predicate( v ) { return ( v >= 3 ); } var arr = new Int32Array( [ 1, 2, 3 ] ); var idx = arr.findIndex( predicate ); // returns 2 ``` If a `predicate` function does not return a truthy value for any array element, the method returns `-1`. ```javascript function predicate( v ) { return ( v < 1 ); } var arr = new Int32Array( [ 1, 2, 3 ] ); var idx = arr.findIndex( predicate ); // returns -1 ``` A `predicate` function is provided three arguments: - `value`: array element - `index`: array index - `arr`: array on which the method is invoked To set the callback execution context, provide a `thisArg`. ```javascript function predicate( v ) { this.count += 1; return ( v >= 3 ); } var ctx = { 'count': 0 }; var arr = new Int32Array( [ 1, 2, 3 ] ); var idx = arr.findIndex( predicate, ctx ); // returns 2 var n = ctx.count; // returns 3 ``` #### Int32Array.prototype.forEach( fcn\[, thisArg] ) Invokes a callback for each array element. ```javascript var arr = new Int32Array( [ 1, 2, 3 ] ); var str = ''; function fcn( v, i ) { str += i + ':' + v; if ( i < arr.length-1 ) { str += ' '; } } arr.forEach( fcn ); console.log( str ); // => '0:1 1:2 2:3' ``` The callback is provided three arguments: - `value`: array element - `index`: array index - `arr`: array on which the method is invoked To set the callback execution context, provide a `thisArg`. ```javascript function fcn() { this.count += 1; } var ctx = { 'count': 0 }; var arr = new Int32Array( [ 1, 2, 3 ] ); arr.forEach( fcn, ctx ); var n = ctx.count; // returns 3 ``` #### Int32Array.prototype.includes( searchElement\[, fromIndex] ) Returns a `boolean` indicating whether an array includes a search element. ```javascript var arr = new Int32Array( [ 1, 2, 3 ] ); var bool = arr.includes( 3 ); // returns true bool = arr.includes( 0 ); // returns false ``` By default, the method searches the entire array (`fromIndex = 0`). To begin searching from a specific array index, provide a `fromIndex`. ```javascript var arr = new Int32Array( [ 1, 2, 3 ] ); var bool = arr.includes( 1, 1 ); // returns false ``` When a `fromIndex` is negative, the starting index is resolved relative to the last array element. ```javascript var arr = new Int32Array( [ 1, 2, 3 ] ); bool = arr.includes( 1, -2 ); // returns false ``` #### Int32Array.prototype.indexOf( searchElement\[, fromIndex] ) Returns the index of the first array element strictly equal to a search element. ```javascript var arr = new Int32Array( [ 1, 2, 3 ] ); var idx = arr.indexOf( 3 ); // returns 2 idx = arr.indexOf( 0 ); // returns -1 ``` By default, the method searches the entire array (`fromIndex = 0`). To begin searching from a specific array index, provide a `fromIndex`. ```javascript var arr = new Int32Array( [ 1, 2, 3 ] ); var idx = arr.indexOf( 1, 1 ); // returns -1 ``` When a `fromIndex` is negative, the starting index is resolved relative to the last array element. ```javascript var arr = new Int32Array( [ 1, 2, 3 ] ); var idx = arr.indexOf( 1, -2 ); // returns -1 ``` #### Int32Array.prototype.join( \[separator] ) Serializes an array by joining all array elements as a string. ```javascript var arr = new Int32Array( [ 1, 2, 3 ] ); var str = arr.join(); // returns '1,2,3' ``` By default, the method delineates array elements using a comma `,`. To specify a custom separator, provide a `separator` string. ```javascript var arr = new Int32Array( [ 1, 2, 3 ] ); var str = arr.join( '|' ); // returns '1|2|3' ``` #### Int32Array.prototype.keys() Returns an iterator for iterating over array keys. ```javascript var arr = new Int32Array( [ 1, 2 ] ); // Create an iterator: var it = arr.keys(); // Iterate over keys... var v = it.next().value; // returns 0 v = it.next().value; // returns 1 var bool = it.next().done; // returns true ``` #### Int32Array.prototype.lastIndexOf( searchElement\[, fromIndex] ) Returns the index of the last array element strictly equal to a search element, iterating from right to left. ```javascript var arr = new Int32Array( [ 1, 0, 2, 0, 1 ] ); var idx = arr.lastIndexOf( 0 ); // returns 3 idx = arr.lastIndexOf( 3 ); // returns -1 ``` By default, the method searches the entire array (`fromIndex = -1`). To begin searching from a specific array index, provide a `fromIndex`. ```javascript var arr = new Int32Array( [ 1, 0, 2, 0, 1 ] ); var idx = arr.lastIndexOf( 0, 2 ); // returns 1 ``` When a `fromIndex` is negative, the starting index is resolved relative to the last array element. ```javascript var arr = new Int32Array( [ 1, 0, 2, 0, 1 ] ); var idx = arr.lastIndexOf( 0, -3 ); // returns 1 ``` #### Int32Array.prototype.map( fcn\[, thisArg] ) Maps each array element to an element in a new array having the same data type as the host array. ```javascript function fcn( v ) { return v * 2; } var arr1 = new Int32Array( [ 1, 2, 3 ] ); var arr2 = arr1.map( fcn ); // returns [ 2, 4, 6 ] ``` A callback is provided three arguments: - `value`: array element - `index`: array index - `arr`: array on which the method is invoked To set the callback execution context, provide a `thisArg`. ```javascript function fcn( v ) { this.count += 1; return v * 2; } var ctx = { 'count': 0 }; var arr1 = new Int32Array( [ 1, 2, 3 ] ); var arr2 = arr1.map( fcn, ctx ); var n = ctx.count; // returns 3 ``` #### Int32Array.prototype.reduce( fcn\[, initialValue] ) Applies a function against an accumulator and each element in an array and returns the accumulated result. ```javascript function fcn( acc, v ) { return acc + ( v*v ); } var arr = new Int32Array( [ 2, 1, 3 ] ); var v = arr.reduce( fcn ); // returns 12 ``` If not provided an initial value, the method invokes a provided function with the first array element as the first argument and the second array element as the second argument. If provided an initial value, the method invokes a provided function with the initial value as the first argument and the first array element as the second argument. ```javascript function fcn( acc, v ) { return acc + ( v*v ); } var arr = new Int32Array( [ 2, 1, 3 ] ); var v = arr.reduce( fcn, 0 ); // returns 14 ``` A callback is provided four arguments: - `acc`: accumulated result - `value`: array element - `index`: array index - `arr`: array on which the method is invoked #### Int32Array.prototype.reduceRight( fcn\[, initialValue] ) Applies a function against an accumulator and each element in an array and returns the accumulated result, iterating from right to left. ```javascript function fcn( acc, v ) { return acc + ( v*v ); } var arr = new Int32Array( [ 2, 1, 3 ] ); var v = arr.reduceRight( fcn ); // returns 8 ``` If not provided an initial value, the method invokes a provided function with the last array element as the first argument and the second-to-last array element as the second argument. If provided an initial value, the method invokes a provided function with the initial value as the first argument and the last array element as the second argument. ```javascript function fcn( acc, v ) { return acc + ( v*v ); } var arr = new Int32Array( [ 2, 1, 3 ] ); var v = arr.reduce( fcn, 0 ); // returns 14 ``` A callback is provided four arguments: - `acc`: accumulated result - `value`: array element - `index`: array index - `arr`: array on which the method is invoked #### Int32Array.prototype.reverse() Reverses an array **in-place** (thus mutating the array on which the method is invoked). ```javascript var arr = new Int32Array( [ 2, 0, 3 ] ); // Reverse the array: arr.reverse(); var v = arr[ 0 ]; // returns 3 v = arr[ 1 ]; // returns 0 v = arr[ 2 ]; // returns 2 ``` #### Int32Array.prototype.set( arr\[, offset] ) Sets array elements. ```javascript var arr = new Int32Array( [ 1, 2, 3 ] ); // returns [ 1, 2, 3 ] // Set the first two array elements: arr.set( [ 4, 5 ] ); var v = arr[ 0 ]; // returns 4 v = arr[ 1 ]; // returns 5 ``` By default, the method starts writing values at the first array index. To specify an alternative index, provide an index `offset`. ```javascript var arr = new Int32Array( [ 1, 2, 3 ] ); // returns [ 1, 2, 3 ] // Set the last two array elements: arr.set( [ 4, 5 ], 1 ); var v = arr[ 1 ]; // returns 4 v = arr[ 2 ]; // returns 5 ``` #### Int32Array.prototype.slice( \[begin\[, end]] ) Copies array elements to a new array with the same underlying data type as the host array. ```javascript var arr1 = new Int32Array( [ 1, 2, 3 ] ); var arr2 = arr1.slice(); var bool = ( arr1 === arr2 ); // returns false bool = ( arr1.buffer === arr2.buffer ); // returns false var v = arr2[ 0 ]; // returns 1 v = arr2[ 1 ]; // returns 2 v = arr2[ 2 ]; // returns 3 ``` By default, the method copies elements beginning with the first array element. To specify an alternative array index at which to begin copying, provide a `begin` index (inclusive). ```javascript var arr1 = new Int32Array( [ 1, 2, 3 ] ); var arr2 = arr1.slice( 1 ); var len = arr2.length; // returns 2 var v = arr2[ 0 ]; // returns 2 v = arr2[ 1 ]; // returns 3 ``` By default, the method copies all array elements after `begin`. To specify an alternative array index at which to end copying, provide an `end` index (exclusive). ```javascript var arr1 = new Int32Array( [ 1, 2, 3 ] ); var arr2 = arr1.slice( 0, 2 ); var len = arr2.length; // returns 2 var v = arr2[ 0 ]; // returns 1 v = arr2[ 1 ]; // returns 2 ``` When a `begin` and/or `end` index is negative, the respective index is determined relative to the last array element. ```javascript var arr1 = new Int32Array( [ 1, 2, 3 ] ); var arr2 = arr1.slice( -arr1.length, -1 ); var len = arr2.length; // returns 2 var v = arr2[ 0 ]; // returns 1 v = arr2[ 1 ]; // returns 2 ``` #### Int32Array.prototype.some( predicate\[, thisArg] ) Tests whether at least one array element passes a test implemented by a `predicate` function. ```javascript function predicate( v ) { return ( v >= 2 ); } var arr = new Int32Array( [ 1, 2 ] ); var bool = arr.some( predicate ); // returns true ``` A `predicate` function is provided three arguments: - `value`: array element - `index`: array index - `arr`: array on which the method is invoked To set the callback execution context, provide a `thisArg`. ```javascript function predicate( v ) { this.count += 1; return ( v >= 2 ); } var ctx = { 'count': 0 }; var arr = new Int32Array( [ 1, 1 ] ); var bool = arr.some( predicate, ctx ); // returns false var n = ctx.count; // returns 2 ``` #### Int32Array.prototype.sort( \[compareFunction] ) Sorts an array **in-place** (thus mutating the array on which the method is invoked). ```javascript var arr = new Int32Array( [ 2, 3, 0 ] ); // Sort the array (in ascending order): arr.sort(); var v = arr[ 0 ]; // returns 0 v = arr[ 1 ]; // returns 2 v = arr[ 2 ]; // returns 3 ``` By default, the method sorts array elements in ascending order. To impose a custom order, provide a `compareFunction`. ```javascript function descending( a, b ) { return b - a; } var arr = new Int32Array( [ 2, 3, 0 ] ); // Sort the array (in descending order): arr.sort( descending ); var v = arr[ 0 ]; // returns 3 v = arr[ 1 ]; // returns 2 v = arr[ 2 ]; // returns 0 ``` The comparison function is provided two array elements, `a` and `b`, per invocation, and its return value determines the sort order as follows: - If the comparison function returns a value **less** than zero, then the method sorts `a` to an index lower than `b` (i.e., `a` should come **before** `b`). - If the comparison function returns a value **greater** than zero, then the method sorts `a` to an index higher than `b` (i.e., `b` should come **before** `a`). - If the comparison function returns **zero**, then the relative order of `a` and `b` _should_ remain unchanged. #### Int32Array.prototype.subarray( \[begin\[, end]] ) Creates a new typed array view over the same underlying [`ArrayBuffer`][@stdlib/array/buffer] and with the same underlying data type as the host array. ```javascript var arr1 = new Int32Array( [ 1, 2, 3 ] ); var arr2 = arr1.subarray(); // returns [ 1, 2, 3 ] var bool = ( arr1.buffer === arr2.buffer ); // returns true ``` By default, the method creates a typed array view beginning with the first array element. To specify an alternative array index at which to begin, provide a `begin` index (inclusive). ```javascript var arr1 = new Int32Array( [ 1, 2, 3 ] ); var arr2 = arr1.subarray( 1 ); // returns [ 2, 3 ] var bool = ( arr1.buffer === arr2.buffer ); // returns true ``` By default, the method creates a typed array view which includes all array elements after `begin`. To limit the number of array elements after `begin`, provide an `end` index (exclusive). ```javascript var arr1 = new Int32Array( [ 1, 2, 3 ] ); var arr2 = arr1.subarray( 0, 2 ); // returns [ 1, 2 ] var bool = ( arr1.buffer === arr2.buffer ); // returns true ``` When a `begin` and/or `end` index is negative, the respective index is determined relative to the last array element. ```javascript var arr1 = new Int32Array( [ 1, 2, 3 ] ); var arr2 = arr1.subarray( -arr1.length, -1 ); // returns [ 1, 2 ] var bool = ( arr1.buffer === arr2.buffer ); // returns true ``` If the method is unable to resolve indices to a non-empty array subsequence, the method returns an empty typed array. ```javascript var arr1 = new Int32Array( [ 1, 2, 3 ] ); var arr2 = arr1.subarray( 10, -1 ); // returns [] ``` #### Int32Array.prototype.toLocaleString( \[locales\[, options]] ) Serializes an array as a locale-specific `string`. ```javascript var arr = new Int32Array( [ 1, 2, 3 ] ); var str = arr.toLocaleString(); // returns '1,2,3' ``` #### Int32Array.prototype.toString() Serializes an array as a `string`. ```javascript var arr = new Int32Array( [ 1, 2, 3 ] ); var str = arr.toString(); // returns '1,2,3' ``` #### Int32Array.prototype.values() Returns an iterator for iterating over array elements. ```javascript var arr = new Int32Array( [ 1, 2 ] ); // Create an iterator: var it = arr.values(); // Iterate over array elements... var v = it.next().value; // returns 1 v = it.next().value; // returns 2 var bool = it.next().done; // returns true ```
* * *
## Examples ```javascript var randu = require( '@stdlib/random/base/randu' ); var round = require( '@stdlib/math/base/special/round' ); var ctor = require( '@stdlib/array/int32' ); var arr; var i; arr = new ctor( 10 ); for ( i = 0; i < arr.length; i++ ) { arr[ i ] = round( randu()*100.0 ); } console.log( arr ); ```