@stdlib/array
Version:
Arrays.
1,267 lines (977 loc) • 30.1 kB
Plain Text
{{alias}}()
A Boolean array.
Returns
-------
out: BooleanArray
A typed array.
Examples
--------
> var arr = new {{alias}}()
<BooleanArray>
{{alias}}( length )
Creates a boolean array having a specified length.
Parameters
----------
length: integer
Typed array length.
Returns
-------
out: BooleanArray
A typed array.
Examples
--------
> var arr = new {{alias}}( 10 )
<BooleanArray>
> var len = arr.length
10
{{alias}}( booleanarray )
Creates a boolean array from another boolean array.
Parameters
----------
booleanarray: BooleanArray
Boolean array from which to generate another boolean array.
Returns
-------
out: BooleanArray
A typed array.
Examples
--------
> var arr1 = new {{alias}}( [ true, false, false, true ] )
<BooleanArray>
> var arr2 = new {{alias}}( arr1 )
<BooleanArray>
> var len = arr2.length
4
{{alias}}( typedarray )
Creates a boolean array from a typed array.
Parameters
----------
typedarray: TypedArray
Typed array from which to generate boolean array.
Returns
-------
out: BooleanArray
A typed array.
Examples
--------
> var buf = new {{alias:@stdlib/array/uint8}}( [ 1, 0, 0, 1 ] )
<Uint8Array>
> var arr = new {{alias}}( buf )
<BooleanArray>
> var len = arr.length
4
{{alias}}( obj )
Creates a boolean array from an array-like object or iterable.
Parameters
----------
obj: Object
Array-like object or iterable from which to generate a boolean array.
Returns
-------
out: BooleanArray
A typed array.
Examples
--------
> var arr1 = new {{alias}}( [ true, false, false, true ] )
<BooleanArray>
> var len = arr1.length
4
> var arr2 = new {{alias}}( [ {}, null, '', 4 ] );
> len = arr2.length
4
{{alias}}( buffer[, byteOffset[, length]] )
Returns a boolean array view of an ArrayBuffer.
Parameters
----------
buffer: ArrayBuffer
Underlying ArrayBuffer.
byteOffset: integer (optional)
Integer byte offset specifying the location of the first typed array
element. Default: 0.
length: integer (optional)
View length. If not provided, the view spans from the byteOffset to
the end of the underlying ArrayBuffer.
Returns
-------
out: BooleanArray
A typed array.
Examples
--------
> var buf = new {{alias:@stdlib/array/buffer}}( 240 );
> var arr1 = new {{alias}}( buf )
<BooleanArray>
> var len = arr1.length
240
> var arr2 = new {{alias}}( buf, 8 )
<BooleanArray>
> len = arr2.length
232
> var arr3 = new {{alias}}( buf, 8, 20 )
<BooleanArray>
> len = arr3.length
20
{{alias}}.from( src[, clbk[, thisArg]] )
Creates a new boolean array from an array-like object or an iterable.
A callback function is provided two arguments:
- value: source value.
- index: source index.
Parameters
----------
src: ArrayLike|Iterable
Source of array elements.
clbk: Function (optional)
Callback to invoke for each source element.
thisArg: Any (optional)
Callback execution context.
Returns
-------
out: BooleanArray
A typed array.
Examples
--------
> function map( v ) { return !v };
> var src = [ true, false ];
> var arr = {{alias}}.from( src, map )
<BooleanArray>
> var len = arr.length
2
> var v = arr.get( 0 )
false
> v = arr.get( 1 )
true
{{alias}}.of( element0[, element1[, ...elementN]] )
Creates a new boolean array from a variable number of arguments.
Parameters
----------
element0: bool
Array element.
element1: bool (optional)
Array element.
elementN: ...bool (optional)
Array elements.
Returns
-------
out: BooleanArray
A typed array.
Examples
--------
> var arr = {{alias}}.of( true, false, false, true )
<BooleanArray>
> var len = arr.length
4
{{alias}}.BYTES_PER_ELEMENT
The size of each array element in bytes.
Examples
--------
> var nbytes = {{alias}}.BYTES_PER_ELEMENT
1
{{alias}}.name
Typed array constructor name.
Examples
--------
> var str = {{alias}}.name
'BooleanArray'
{{alias}}.prototype.buffer
Pointer to the underlying data buffer.
Examples
--------
> var arr = new {{alias}}( 2 )
<BooleanArray>
> var buf = arr.buffer
<ArrayBuffer>
{{alias}}.prototype.byteLength
Size of the array in bytes.
Examples
--------
> var arr = new {{alias}}( 10 )
<BooleanArray>
> var nbytes = arr.byteLength
10
{{alias}}.prototype.byteOffset
Offset (in bytes) of the array from the start of its underlying
ArrayBuffer.
Examples
--------
> var arr = new {{alias}}( 10 )
<BooleanArray>
> var offset = arr.byteOffset
0
> var buf = new {{alias:@stdlib/array/buffer}}( 240 );
> arr = new {{alias}}( buf, 64 )
<BooleanArray>
> offset = arr.byteOffset
64
{{alias}}.prototype.BYTES_PER_ELEMENT
Size (in bytes) of each array element.
Examples
--------
> var arr = new {{alias}}( 10 )
<BooleanArray>
> arr.BYTES_PER_ELEMENT
1
{{alias}}.prototype.length
The number of array elements.
Examples
--------
> var arr = new {{alias}}( 10 )
<BooleanArray>
> var len = arr.length
10
{{alias}}.prototype.at( i )
Returns an array element located at integer position (index) `i`, with
support for noth nonnegative and negative integer positions.
If provided an index outside the array index range, the method returns
`undefined`.
Parameters
----------
i: integer
Element index.
Returns
-------
out: boolean|void
An array element.
Examples
--------
> var arr = new {{alias}}( [ true, false, false, true ] )
<BooleanArray>
> var v = arr.at( 1 )
false
> v = arr.at( -1 )
true
{{alias}}.prototype.copyWithin( target, start[, end] )
Copies a sequence of elements within the array starting at `start` and
ending at `end` (non-inclusive) to the position starting at `target`.
Parameters
----------
target: integer
Target start index position.
start: integer
Source start index position.
end: integer (optional)
Source end index position. Default: out.length.
Returns
-------
out: BooleanArray
Modified array.
Examples
--------
> var arr = new {{alias}}( [ true, false, false, true ] )
<BooleanArray>
> arr.copyWithin( 0, 2 )
<BooleanArray>
> var v = arr.get( 0 )
false
> v = arr.get( 1 )
true
{{alias}}.prototype.entries()
Returns an iterator for iterating over array key-value pairs.
Returns
-------
iterator: Iterator
Iterator for iterating over array key-value pairs.
Examples
--------
> var arr = new {{alias}}( [ true, false, true ] )
<BooleanArray>
> var it = arr.entries();
> var v = it.next().value
[ 0, true ]
> v = it.next().value
[ 1, false ]
> v = it.next().value
[ 2, true ]
> var bool = it.next().done
true
{{alias}}.prototype.every( predicate[, thisArg] )
Returns a boolean indicating whether all elements in the array pass a test.
A predicate function is provided the following arguments:
- value: current array element.
- index: current array element index.
- arr: the array on which the method was called.
Parameters
----------
predicate: Function
Predicate function which tests array elements. If a predicate function
returns a truthy value, an array element passes; otherwise, an array
element fails.
thisArg: Any (optional)
Execution context.
Returns
-------
bool: boolean
Boolean indicating whether all elements pass the test.
Examples
--------
> function predicate( v ) { return v === true; };
> var arr = new {{alias}}( [ true, true, true ] )
<BooleanArray>
> var bool = arr.every( predicate )
true
{{alias}}.prototype.fill( value[, start[, end]] )
Returns a modified typed array filled with a fill value.
Parameters
----------
value: boolean
Fill value.
start: integer (optional)
Start index. If less than zero, the start index is resolved relative to
the last array element. Default: 0.
end: integer (optional)
End index (non-inclusive). If less than zero, the end index is resolved
relative to the last array element. Default: out.length.
Returns
-------
out: BooleanArray
Modified array.
Examples
--------
> var arr = new {{alias}}( 3 )
<BooleanArray>
> arr.fill( true );
> var v = arr.get( 0 )
true
> v = arr.get( 1 )
true
> v = arr.get( 2 )
true
{{alias}}.prototype.filter( predicate[, thisArg] )
Returns a new array containing the elements of an array which pass a test
implemented by a predicate function.
A predicate function is provided the following arguments:
- value: current array element.
- index: current array element index.
- arr: the array on which the method was called.
The returned array has the same data type as the host array.
Parameters
----------
predicate: Function
Predicate function which filters array elements. If a predicate function
returns a truthy value, an array element is included in the output
array; otherwise, an array element is not included in the output array.
thisArg: Any (optional)
Execution context.
Returns
-------
out: BooleanArray
A new typed array.
Examples
--------
> function predicate( v ) { return ( v === true ); };
> var arr = new {{alias}}( [ true, false, true ] )
<BooleanArray>
> var out = arr.filter( predicate )
<BooleanArray>
> var len = out.length
2
> var v = out.get( 0 )
true
> v = out.get( 1 )
true
{{alias}}.prototype.find( predicate[, thisArg] )
Returns the first element in an array for which a predicate function returns
a truthy value.
A predicate function is provided the following arguments:
- value: current array element.
- index: current array element index.
- arr: the array on which the method was called.
If a predicate function never returns a truthy value, the method returns
`undefined`.
Parameters
----------
predicate: Function
Predicate function which tests array elements.
thisArg: Any (optional)
Execution context.
Returns
-------
out: boolean|void
Array element or `undefined`.
Examples
--------
> function predicate( v ) { return v === true; };
> var arr = new {{alias}}( [ true, false, true ] )
<BooleanArray>
> var v = arr.find( predicate )
true
{{alias}}.prototype.findIndex( predicate[, thisArg] )
Returns the index of the first element in an array for which a predicate
function returns a truthy value.
A predicate function is provided the following arguments:
- value: current array element.
- index: current array element index.
- arr: the array on which the method was called.
If a predicate function never returns a truthy value, the method returns
`-1`.
Parameters
----------
predicate: Function
Predicate function which tests array elements.
thisArg: Any (optional)
Execution context.
Returns
-------
out: integer
Array index or `-1`.
Examples
--------
> function predicate( v ) { return v === true; };
> var arr = new {{alias}}( [ true, false, true ] )
<BooleanArray>
> var idx = arr.findIndex( predicate )
0
{{alias}}.prototype.findLast( predicate[, thisArg] )
Returns the last element in an array for which a predicate function returns
a truthy value.
A predicate function is provided the following arguments:
- value: current array element.
- index: current array element index.
- arr: the array on which the method was called.
If a predicate function never returns a truthy value, the method returns
`undefined`.
Parameters
----------
predicate: Function
Predicate function which tests array elements.
thisArg: Any (optional)
Execution context.
Returns
-------
out: boolean|void
Array element or `undefined`.
Examples
--------
> function predicate( v ) { return v === true; };
> var arr = new {{alias}}( [ true, false, true ] )
<BooleanArray>
> var v = arr.findLast( predicate )
true
{{alias}}.prototype.findLastIndex( predicate[, thisArg] )
Returns the index of the last element in an array for which a predicate
function returns a truthy value.
A predicate function is provided the following arguments:
- value: current array element.
- index: current array element index.
- arr: the array on which the method was called.
If a predicate function never returns a truthy value, the method returns
`-1`.
Parameters
----------
predicate: Function
Predicate function which tests array elements.
thisArg: Any (optional)
Execution context.
Returns
-------
out: integer
Array index or `-1`.
Examples
--------
> function predicate( v ) { return v === true; };
> var arr = new {{alias}}( [ true, false, true ] )
<BooleanArray>
> var idx = arr.findLastIndex( predicate )
2
{{alias}}.prototype.forEach( clbk[, thisArg] )
Invokes a function once for each array element.
A callback function is provided the following arguments:
- value: current array element.
- index: current array element index.
- arr: the array on which the method was called.
Parameters
----------
clbk: Function
Function to invoke for each array element.
thisArg: Any (optional)
Execution context.
Examples
--------
> var str = '%';
> function clbk( v ) { str += v.toString() + '%'; };
> var arr = new {{alias}}( [ true, false, false, true ] )
<BooleanArray>
> arr.forEach( clbk );
> str
'%true%false%false%true%'
{{alias}}.prototype.get( i )
Returns an array element located at integer position (index) `i`.
If provided an index outside the array index range, the method returns
`undefined`.
Parameters
----------
i: integer
Element index.
Returns
-------
out: boolean|void
Array element or `undefined`.
Examples
--------
> var arr = new {{alias}}( 10 )
<BooleanArray>
> arr.set( true, 0 );
> var v = arr.get( 0 )
true
{{alias}}.prototype.includes( searchElement[, fromIndex] )
Returns a boolean indicating whether an array includes a provided value.
Parameters
----------
searchElement: boolean
Search element.
fromIndex: integer (optional)
Array index at which to start the search. If provided a negative value,
the method resolves the start index relative to the last array element.
Default: 0.
Returns
-------
bool: boolean
Boolean indicating whether an array includes a search element.
Examples
--------
> var arr = new {{alias}}( [ true, false, true, true, true ] )
<BooleanArray>
> var bool = arr.includes( true )
true
> bool = arr.includes( false, 3 )
false
{{alias}}.prototype.indexOf( searchElement[, fromIndex] )
Returns the first index at which a given element can be found.
If method does not find a search element, the method returns `-1`.
Parameters
----------
searchElement: boolean
Search element.
fromIndex: integer (optional)
Array index at which to start the search. If provided a negative value,
the method resolves the start index relative to the last array element.
Default: 0.
Returns
-------
out: integer
Array index or `-1`.
Examples
--------
> var arr = new {{alias}}( [ true, false, true, true, true ] )
<BooleanArray>
> var idx = arr.indexOf( true )
0
> idx = arr.indexOf( false, 3 )
-1
{{alias}}.prototype.join( [separator] )
Returns a new string by concatenating all array elements separated by a
separator string.
Parameters
----------
separator: string (optional)
Separator string. Default: ','.
Returns
-------
out: string
Array serialized as a string.
Examples
--------
> var arr = new {{alias}}( [ true, false, true ] )
<BooleanArray>
> var str = arr.join()
'true,false,true'
> str = arr.join( '|' )
'true|false|true'
{{alias}}.prototype.keys()
Returns an iterator for iterating over each index key in a typed array.
Returns
-------
iterator: Iterator
Iterator for iterating over array index keys.
Examples
--------
> var arr = new {{alias}}( [ true, false ] )
<BooleanArray>
> var it = arr.keys();
> var v = it.next().value
0
> v = it.next().value
1
> v = it.next().done
true
{{alias}}.prototype.lastIndexOf( searchElement[, fromIndex] )
Returns the last index at which a given element can be found.
If method does not find a search element, the method returns `-1`.
Parameters
----------
searchElement: boolean
Search element.
fromIndex: integer (optional)
Array index at which to start the search. If provided a negative value,
the method resolves the start index relative to the last array element.
Default: out.length-1.
Returns
-------
out: integer
Array index or `-1`.
Examples
--------
> var arr = new {{alias}}( [ true, true, true, false, true ] )
<BooleanArray>
> var idx = arr.lastIndexOf( false )
3
> idx = arr.lastIndexOf( false, 2 )
-1
{{alias}}.prototype.map( clbk[, thisArg] )
Returns a new array with each element being the result of a provided
callback function.
A callback function is provided the following arguments:
- value: current array element.
- index: current array element index.
- arr: the array on which the method was called.
The returned array has the same data type as the host array.
Parameters
----------
clbk: Function
Function which maps array elements to elements in the new array.
thisArg: Any (optional)
Execution context.
Returns
-------
out: BooleanArray
A new typed array.
Examples
--------
> function invert( v ) { return !v; };
> var arr = new {{alias}}( [ true, false, true ] )
<BooleanArray>
> var out = arr.map( invert )
<BooleanArray>
> var v = out.get( 0 )
false
> v = out.get( 1 )
true
> v = out.get( 2 )
false
{{alias}}.prototype.reduce( reducerFn[, initialValue] )
Applies a provided function to each element of the array, in order, passing
in the return value from the calculation on the preceding element and
returning the accumulated result upon completion.
A reducer function is provided the following arguments:
- acc: accumulated result.
- value: current array element.
- index: current array element index.
- arr: the array on which the method was called.
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.
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.
Parameters
----------
reducerFn: Function
Function to apply to each array element.
initialValue: any (optional)
Initial accumulation value.
Returns
-------
out: any
Accumulated result.
Examples
--------
> function reducer( acc, v ) { return ( acc && v ); };
> var arr = new {{alias}}( [ true, false, true ] )
<BooleanArray>
> var out = arr.reduce( reducer )
false
{{alias}}.prototype.reduceRight( reducerFn[, initialValue] )
Applies a provided function to each element of the array, in reverse order,
passing in the return value from the calculation on the preceding element
and returning the accumulated result upon completion.
A reducer function is provided the following arguments:
- acc: accumulated result.
- value: current array element.
- index: current array element index.
- arr: the array on which the method was called.
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.
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.
Parameters
----------
reducerFn: Function
Function to apply to each array element.
initialValue: any (optional)
Initial accumulation value.
Returns
-------
out: any
Accumulated result.
Examples
--------
> function reducer( acc, v ) { return ( acc && v ); };
> var arr = new {{alias}}( [ true, false, true ] )
<BooleanArray>
> var out = arr.reduceRight( reducer )
false
{{alias}}.prototype.reverse()
Reverses the array *in-place*.
This method mutates the array on which the method is invoked.
Returns
-------
out: BooleanArray
Modified array.
Examples
--------
> var arr = new {{alias}}( [ true, false, false ] )
<BooleanArray>
> arr.reverse();
> var v = arr.get( 0 )
false
> v = arr.get( 1 )
false
> v = arr.get( 2 )
true
{{alias}}.prototype.set( v[, i] )
Sets one or more array elements.
If provided a single argument, the method sets array elements starting at
position (index) `i = 0`. To set elements starting elsewhere in the array,
provide an index argument `i`.
To set one or more array elements, provide an array-like object containing
truthy and falsy values.
Parameters
----------
v: bool|BooleanArray|ArrayLikeObject
Boolean value or Boolean value array.
i: integer (optional)
Array index at which to start setting elements. Default: 0.
Examples
--------
> var arr = new {{alias}}( 2 )
<BooleanArray>
> arr.set( false );
> var v = arr.get( 0 )
false
> arr.set( true, 1 );
> v = arr.get( 1 )
true
{{alias}}.prototype.slice( [start[, end]] )
Copies a portion of a typed array to a new typed array.
Parameters
----------
start: integer (optional)
Start index. If less than zero, the start index is resolved relative to
the last array element. Default: 0.
end: integer (optional)
End index (non-inclusive). If less than zero, the end index is resolved
relative to the last array element. Default: out.length.
Returns
-------
out: BooleanArray
New typed array.
Examples
--------
> var arr = new {{alias}}( [ true, false, true, false, true ] )
<BooleanArray>
> var out = arr.slice( 1 )
<BooleanArray>
> var len = out.length
4
> var v = out.get( 0 )
false
> v = out.get( 1 )
true
{{alias}}.prototype.some( predicate[, thisArg] )
Returns a boolean indicating whether at least one element passes a test.
A predicate function is provided the following arguments:
- value: current array element.
- index: current array element index.
- arr: the array on which the method was called.
Parameters
----------
predicate: Function
Predicate function which tests array elements. If a predicate function
returns a truthy value, an array element passes; otherwise, an array
element fails.
thisArg: Any (optional)
Execution context.
Returns
-------
bool: boolean
Boolean indicating whether at least one element passes the test.
Examples
--------
> function predicate( v ) { return v === true; };
> var arr = new {{alias}}( [ false, true, false ] )
<BooleanArray>
> var bool = arr.some( predicate )
true
{{alias}}.prototype.sort( [compareFunction] )
Sorts an array in-place.
A comparison function determines the order of the array elements. The
function is provided two arguments:
- a: first boolean value for comparison.
- b: second boolean value for comparison.
The function should return a value less than zero if `a` comes before `b`,
a value greater than zero if `a` comes after `b`, and zero if `a` and `b`
are equivalent.
Parameters
----------
compareFunction: Function (optional)
Comparison function.
Returns
-------
out: BooleanArray
Modified array.
Examples
--------
> function compare( a, b ) { return a === true ? -1 : 1; };
> var arr = new {{alias}}( [ true, false, true ] )
<BooleanArray>
> arr.sort( compare );
> var v = arr.get( 0 )
true
> v = arr.get( 1 )
true
> v = arr.get( 2 )
false
{{alias}}.prototype.subarray( [begin[, end]] )
Creates a new typed array view over the same underlying `ArrayBuffer` and
with the same underlying data type as the host array.
Parameters
----------
begin: integer (optional)
Start index. If less than zero, the start index is resolved relative to
the last array element. Default: 0.
end: integer (optional)
End index (non-inclusive). If less than zero, the end index is resolved
relative to the last array element. Default: out.length.
Returns
-------
out: BooleanArray
New typed array view.
Examples
--------
> var arr = new {{alias}}( [ true, false, true, false, true ] )
<BooleanArray>
> var out = arr.subarray( 1, 3 )
<BooleanArray>
> var len = out.length
2
> var v = out.get( 0 )
false
> v = out.get( 1 )
true
{{alias}}.prototype.toLocaleString( [locales[, options]] )
Serializes an array as a locale-specific string.
Parameters
----------
locales: string|Array (optional)
Locale identifier(s).
options: Object (optional)
An object containing serialization options.
Returns
-------
str: string
Local-specific string.
Examples
--------
> var arr = new {{alias}}( [ true, false, true ] )
<BooleanArray>
> var str = arr.toLocaleString()
'true,false,true'
{{alias}}.prototype.toReversed()
Returns a new typed array containing the elements in reversed order.
Returns
-------
out: BooleanArray
New typed array.
Examples
--------
> var arr = new {{alias}}( [ true, false, false ] )
<BooleanArray>
> var out = arr.toReversed()
<BooleanArray>
> var v = out.get( 0 )
false
> v = out.get( 1 )
false
> v = out.get( 2 )
true
{{alias}}.prototype.toSorted( [compareFunction] )
Returns a new typed array containing the elements in sorted order.
A comparison function determines the order of the array elements. The
function is provided two arguments:
- a: first boolean value for comparison.
- b: second boolean value for comparison.
The function should return a value less than zero if `a` comes before `b`,
a value greater than zero if `a` comes after `b`, and zero if `a` and `b`
are equivalent.
Parameters
----------
compareFunction: Function (optional)
Comparison function.
Returns
-------
out: BooleanArray
New typed array.
Examples
--------
> function compare( a, b ) { return a === true ? -1 : 1; };
> var arr = new {{alias}}( [ true, false, true ] )
<BooleanArray>
> var out = arr.toSorted( compare );
> var v = out.get( 0 )
true
> v = out.get( 1 )
true
> v = out.get( 2 )
false
{{alias}}.prototype.toString()
Serializes an array as a string.
Returns
-------
out: string
String serialization of the array.
Examples
--------
> var arr = new {{alias}}( [ true, false, true ] )
<BooleanArray>
> var str = arr.toString()
'true,false,true'
{{alias}}.prototype.values()
Returns an iterator for iterating over each value in a typed array.
Returns
-------
iterator: Iterator
Iterator for iterating over array values.
Examples
--------
> var arr = new {{alias}}( [ true, false ] )
<BooleanArray>
> var it = arr.values();
> var v = it.next().value
true
> v = it.next().value
false
> var bool = it.next().done
true
{{alias}}.prototype.with( index, value )
Returns a new typed array with the element at a provided index replaced
with a provided value.
Parameters
----------
index: integer
Element index.
value: boolean
Element value.
Returns
-------
out: BooleanArray
New typed array.
Examples
--------
> var arr = new {{alias}}( [ true, false, true ] )
<BooleanArray>
> var out = arr.with( 0, false )
<BooleanArray>
> var v = out.get( 0 )
false
See Also
--------