@stdlib/array
Version:
Arrays.
58 lines (43 loc) • 1.9 kB
Plain Text
{{alias}}( x, indices, values[, options] )
Replaces specified elements of an array with provided values.
The function supports broadcasting a `values` array containing a single
element against an `indices` array containing one or more elements.
The function mutates the input array.
Because each index is only validated at the time of replacing a particular
element, mutation may occur even when one or more indices are out-of-bounds,
including when the index mode indicates to raise an exception.
If `indices` is an empty array, the function returns the input array
unchanged.
Parameters
----------
x: ArrayLikeObject
Input array.
indices: ArrayLikeObject<integer>
List of element indices.
values: ArrayLikeObject
Values to set. When `indices` contains one or more elements, `values`
must be broadcast compatible with `indices` (i.e., must have either one
element or the same number of elements as `indices`).
options: Object (optional)
Function options.
options.mode: string (optional)
Specifies how to handle an index outside the interval [0, max], where
`max` is the maximum possible array index. If equal to 'throw', the
function throws an error. If equal to 'normalize', the function throws
an error if provided an out-of-bounds normalized index. If equal to
'wrap', the function wraps around an index using modulo arithmetic. If
equal to 'clamp', the function sets an index to either 0 (minimum index)
or the maximum index. Default: 'normalize'.
Returns
-------
out: ArrayLikeObject
Input array.
Examples
--------
> var x = [ 1, 2, 3, 4 ];
> var out = {{alias}}( x, [ 1, 3 ], [ 20, 40 ] )
[ 1, 20, 3, 40 ]
> var bool = ( out === x )
true
See Also
--------