# abs
> Compute the [absolute value][absolute-value].
The [absolute value][absolute-value] is defined as
## Usage
```javascript
var abs = require( '@stdlib/math/special/abs' );
```
#### abs( x\[, options] )
Computes the [absolute value][absolute-value].
```javascript
var y = abs( -1.0 );
// returns 1.0
```
The function accepts the following arguments:
- **x**: input [`ndarray`][@stdlib/ndarray/ctor], array-like object, or number. If provided an [`ndarray`][@stdlib/ndarray/ctor] or array-like object, the function performs element-wise computation.
- **options**: function options.
If provided an [`ndarray`][@stdlib/ndarray/ctor], the function returns an [`ndarray`][@stdlib/ndarray/ctor] having the same shape and data type as `x`.
```javascript
var array = require( '@stdlib/ndarray/array' );
var x = array( [ [ -1.0, -2.0 ], [ -3.0, -4.0 ] ] ); // 2x2
var y = abs( x );
// returns
var v = y.get( 0, 1 );
// returns 2.0
```
If provided an array-like object, the function returns an array-like object having the same length and data type as `x`.
```javascript
var Float64Array = require( '@stdlib/array/float64' );
var x = new Float64Array( [ -1.0, -2.0 ] );
var y = abs( x );
// returns [ 1.0, 2.0 ]
x = [ -1.0, -2.0 ];
y = abs( x );
// returns [ 1.0, 2.0 ]
```
The function accepts the following `options`:
- **dtype**: output array [data type][@stdlib/ndarray/dtypes]. Only applicable when `x` is either an [`ndarray`][@stdlib/ndarray/ctor] or array-like object. By default, the output array data type is inferred from the input array.
- **order**: output array [order][@stdlib/ndarray/orders]. Only applicable when `x` is an [`ndarray`][@stdlib/ndarray/ctor]. By default, the output array order is inferred from the input array.
By default, when provided either an [`ndarray`][@stdlib/ndarray/ctor] or an array-like object, the function returns an object of the same "kind" (either an [`ndarray`][@stdlib/ndarray/ctor] or array-like object, respectively) having the same underlying [data type][@stdlib/ndarray/dtypes]. To specify a different output array [data type][@stdlib/ndarray/dtypes], set the `dtype` option.
```javascript
var Float32Array = require( '@stdlib/array/float32' );
var x = new Float32Array( [ -1.0, -2.0 ] );
var y = abs( x );
// returns [ 1.0, 2.0 ]
x = new Float32Array( [ -1.0, -2.0 ] );
y = abs( x, {
'dtype': 'float64'
});
// returns [ 1.0, 2.0 ]
```
#### abs.assign( x, y )
Computes the [absolute value][absolute-value] and assigns results to a provided output array.
```javascript
var array = require( '@stdlib/ndarray/array' );
var x = array( [ [ -1.0, -2.0 ], [ -3.0, -4.0 ] ] ); // 2x2
var y = array( [ [ 0.0, 0.0 ], [ 0.0, 0.0 ] ] ); // 2x2
var out = abs.assign( x, y );
// returns
var bool = ( out === y );
// returns true
var v = y.get( 0, 1 );
// returns 2.0
```
The output array must be the same data "kind" (i.e., [`ndarray`][@stdlib/ndarray/ctor] or array-like object) as the input array. For example, if `x` is an [`ndarray`][@stdlib/ndarray/ctor], `y` must also be an [`ndarray`][@stdlib/ndarray/ctor]. Similarly, if `x` is an array-like object, `y` must also be an array-like object.
TODO: broadcasting discussion and example(s).
## Examples
```javascript
var Float64Array = require( '@stdlib/array/float64' );
var array = require( '@stdlib/ndarray/array' );
var ind2sub = require( '@stdlib/ndarray/ind2sub' );
var abs = require( '@stdlib/math/special/abs' );
// Provide a number...
var v = abs( -1.0 );
console.log( 'x = %d => abs(x) = %d', -1.0, v );
// Provide an array-like object...
var x = new Float64Array( [ -1.0, -2.0, -3.0 ] );
var y = abs( x );
var i;
for ( i = 0; i < x.length; i++ ) {
console.log( 'x_%d = %d => abs(x_%d) = %d', i, x[ i ], i, y[ i ] );
}
// Provide an ndarray...
x = array( [ [ -1.0, -2.0 ], [ -3.0, -4.0 ] ] );
y = abs( x );
var sh = x.shape;
var sub;
for ( i = 0; i < x.length; i++ ) {
sub = ind2sub( sh, i );
console.log( 'x_%d%d = %d => abs(x_%d%d) = %d', sub[ 0 ], sub[ 1 ], x.iget( i ), sub[ 0 ], sub[ 1 ], y.iget( i ) );
}
```
[absolute-value]: https://en.wikipedia.org/wiki/Absolute_value
[@stdlib/ndarray/ctor]: https://www.npmjs.com/package/@stdlib/ndarray-ctor
[@stdlib/ndarray/orders]: https://www.npmjs.com/package/@stdlib/ndarray-orders
[@stdlib/ndarray/dtypes]: https://www.npmjs.com/package/@stdlib/ndarray-dtypes
