Skip to content

Commit

Permalink
Merge c555f34 into db56d15
Browse files Browse the repository at this point in the history
  • Loading branch information
@Planeshifter
Planeshifter committed Jun 25, 2015
2 parents db56d15 + c555f34 commit aa41252
Show file tree
Hide file tree
Showing 16 changed files with 1,931 additions and 240 deletions.
2 changes: 1 addition & 1 deletion Makefile
View file
Expand Up @@ -38,7 +38,7 @@ ISTANBUL_HTML_REPORT_PATH ?= $(ISTANBUL_OUT)/lcov-report/index.html
# JSHINT #

JSHINT ?= ./node_modules/.bin/jshint
JSHINT_REPORTER ?= ./node_modules/jshint-stylish/stylish.js
JSHINT_REPORTER ?= ./node_modules/jshint-stylish



Expand Down
308 changes: 276 additions & 32 deletions README.md
View file
Expand Up @@ -20,41 +20,73 @@ For use in the browser, use [browserify](https://github.com/substack/node-browse
var divide = require( 'compute-divide' );
```

#### divide( arr, x[, opts] )
#### divide( x, y[, opts] )

Computes an element-wise division. `x` may be either an `array` of equal length or a `numeric` value.
Computes an element-wise division. `x` can be a [`number`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number), [`array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array), [`typed array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Typed_arrays) or [`matrix`](https://github.com/dstructs/matrix). `y` has to be either an `array` or `matrix` of equal dimensions as `x` or a single number. The function returns either an `array` with length equal to that of the input `array`, a `matrix` with equal dimensions as input `x` or a single number.

``` javascript
var arr = [ 2, 1, 4, 2 ],
out;
var matrix = require( 'dstructs-matrix' ),
data,
mat,
out,
i;

out = divide( arr, 2 );
// returns [ 1, 0.5, 2, 1 ]
out = divide( 6, 3 );
// returns 2

out = divide( arr, [ 1, 2, 8, 8 ] );
// returns [ 2, 1, 0.5, 0.25 ]
```
out = divide( 8, 2 );
// returns 4

The function accepts the following `options`:
data = [ 2, 4, 6 ];
out = divide( data, 2 );
// returns [ 1, 2, 3 ]

* __copy__: `boolean` indicating whether to return a new `array`. Default: `true`.
* __accessor__: accessor `function` for accessing values in object `arrays`.
data = [ 1, 2, 3 ];
out = divide( 6, data );
// returns [ 6, 3, 2 ]

To mutate the input `array` (e.g., when input values can be discarded or when optimizing memory usage), set the `copy` option to `false`.
data = [ 12, 6, 4 ];
out = divide( data, [ 6, 3, 2 ] )
// returns [ 2, 2, 2 ]

``` javascript
var arr = [ 5, 3, 8, 3, 2 ];

var out = divide( arr, 4, {
'copy': false
});
// returns [ 1.25, 0.75, 0.5, 0.75, 0.5 ]
data = new Int8Array( [2,4,6] );
out = divide( data, 2 );
// returns Float64Array( [1,2,3] )

console.log( arr === out );
// returns true
data = new Int16Array( 6 );
for ( i = 0; i < 6; i++ ) {
data[ i ] = i;
}
mat = matrix( data, [3,2], 'int16' );
/*
[ 0 1
2 3
4 5 ]
*/

out = divide( mat, 2 );
/*
[ 0 0.5
1 1.5
2 2.5 ]
*/

out = divide( mat, mat );
/*
[ NaN 1
1 1
1 1 ]
*/
```

__Note__: mutation is the `array` equivalent of a __slash-equal__ (`/=`).
The function accepts the following `options`:

* __accessor__: accessor `function` for accessing `array` values.
* __dtype__: output [`typed array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Typed_arrays) or [`matrix`](https://github.com/dstructs/matrix) data type. Default: `float64`.
* __copy__: `boolean` indicating if the `function` should return a new data structure. Default: `true`.
* __path__: [deepget](https://github.com/kgryte/utils-deep-get)/[deepset](https://github.com/kgryte/utils-deep-set) key path.
* __sep__: [deepget](https://github.com/kgryte/utils-deep-get)/[deepset](https://github.com/kgryte/utils-deep-set) key path separator. Default: `'.'`.

For object `arrays`, provide an accessor `function` for accessing `array` values.

Expand All @@ -71,10 +103,10 @@ function getValue( d, i ) {
return d[ 1 ];
}

var out = divide( data, 4, {
var out = divide( data, 2, {
'accessor': getValue
});
// returns [ 1.25, 0.75, 2, 0.75, 0.5 ]
// returns [ 2.5, 1.5, 4, 1.5, 1 ]
```

When dividing values between two object `arrays`, provide an accessor `function` which accepts `3` arguments.
Expand Down Expand Up @@ -112,21 +144,233 @@ var out = divide( data, arr, {
__Note__: `j` corresponds to the input `array` index, where `j=0` is the index for the first input `array` and `j=1` is the index for the second input `array`.


To [deepset](https://github.com/kgryte/utils-deep-set) an object `array`, provide a key path and, optionally, a key path separator.

``` javascript
var data = [
{'x':[0,2]},
{'x':[1,3]},
{'x':[2,5]},
{'x':[3,7]},
{'x':[4,11]}
];

## Examples
var out = divide( data, 2, 'x|1', '|' );
/*
[
{'x':[0,1]},
{'x':[1,1.5]},
{'x':[2,2.5]},
{'x':[3,3.5},
{'x':[4,5.5]}
]
*/

var bool = ( data === out );
// returns true
```

By default, when provided a [`typed array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Typed_arrays) or [`matrix`](https://github.com/dstructs/matrix), the output data structure is `float64` in order to preserve precision. To specify a different data type, set the `dtype` option (see [`matrix`](https://github.com/dstructs/matrix) for a list of acceptable data types).

``` javascript
var divide = require( 'compute-divide' );
var data, out;

var data = new Array( 100 );
for ( var i = 0; i < data.length; i++ ) {
data = new Int8Array( [ 4, 8, 12 ] );

out = divide( data, 2, {
'dtype': 'int32'
});
// returns Int32Array( [2,4,6] )

// Works for plain arrays, as well...
out = divide( [ 4, 8, 12 ], 2, {
'dtype': 'uint8'
});
// returns Uint8Array( [2,4,6] )
```

By default, the function returns a new data structure. To mutate the input data structure, set the `copy` option to `false`.

``` javascript
var data,
bool,
mat,
out,
i;

data = [ 4, 8, 12 ];

out = divide( data, 2, {
'copy': false
});
// returns [ 2, 4, 6 ]

bool = ( data === out );
// returns true

data = new Int16Array( 6 );
for ( i = 0; i < 6; i++ ) {
data[ i ] = i;
}
mat = matrix( data, [3,2], 'int16' );
/*
[ 0 1
2 3
4 5 ]
*/

out = divide( mat, 2, {
'copy': false
});
/*
[ 0 0.5
1 1.5
2 2.5 ]
*/

bool = ( mat === out );
// returns true
```

__Note__: mutation is the `array` or `matrix` equivalent of a __slash-equal__ (`/=`).


## Notes

* If an element is __not__ a numeric value, the result of the division is `NaN`.

``` javascript
var data, out;

out = divide( null, 1 );
// returns NaN

out = divide( true, 1 );
// returns NaN

out = divide( {'a':'b'}, 1 );
// returns NaN

out = divide( [ true, null, [] ], 1 );
// returns [ NaN, NaN, NaN ]

function getValue( d, i ) {
return d.x;
}
data = [
{'x':true},
{'x':[]},
{'x':{}},
{'x':null}
];

out = divide( data, 1, {
'accessor': getValue
});
// returns [ NaN, NaN, NaN, NaN ]

out = divide( data, 1, {
'path': 'x'
});
/*
[
{'x':NaN},
{'x':NaN},
{'x':NaN,
{'x':NaN}
]
*/
```

* Be careful when providing a data structure which contains non-numeric elements and specifying an `integer` output data type, as `NaN` values are cast to `0`.

``` javascript
var out = divide( [ true, null, [] ], 1, {
'dtype': 'int8'
});
// returns Int8Array( [0,0,0] )
```
* When calling the function with a numeric value as the first argument and a `matrix` or `array` as the second argument, only the `dtype` option is applicable.

``` javascript
// Valid:
var out = divide( 4, [ 1, 2, 3 ], {
'dtype': 'int8'
});
// returns Int8Array( [4,2,1] )

// Not valid:
var out = divide( 4, [ 1, 2, 3 ], {
'copy': false
});
// throws an error
```

## Examples

``` javascript
var matrix = require( 'dstructs-matrix' ),
divide = require( 'compute-divide' );

var data,
mat,
out,
tmp,
i;

// Plain arrays...
data = new Array( 10 );
for ( i = 0; i < data.length; i++ ) {
data[ i ] = Math.round( Math.random()*100 );
}
out = divide( data, 10 );

// Object arrays (accessors)...
function getValue( d ) {
return d.x;
}
for ( i = 0; i < data.length; i++ ) {
data[ i ] = {
'x': data[ i ]
};
}
out = divide( data, 10, {
'accessor': getValue
});

// Deep set arrays...
for ( i = 0; i < data.length; i++ ) {
data[ i ] = {
'x': [ i, data[ i ].x ]
};
}
out = divide( data, 10, {
'path': 'x/1',
'sep': '/'
});

// Typed arrays...
data = new Int32Array( 10 );
for ( i = 0; i < data.length; i++ ) {
data[ i ] = Math.random() * 100;
}
tmp = divide( data, 10 );
out = '';
for ( i = 0; i < data.length; i++ ) {
out += tmp[ i ];
if ( i < data.length-1 ) {
out += ',';
}
}

var out = divide( data, 10 );
// Matrices...
mat = matrix( data, [5,2], 'int32' );
out = divide( mat, 10 );

console.log( out.join( '\n' ) );
// Matrices (custom output data type)...
out = divide( mat, 10, {
'dtype': 'uint8'
});
```

To run the example code from the top-level application directory,
Expand Down Expand Up @@ -167,12 +411,12 @@ $ make view-cov
---
## License

[MIT license](http://opensource.org/licenses/MIT).
[MIT license](http://opensource.org/licenses/MIT).


## Copyright

Copyright &copy; 2015. The Compute.io Authors.
Copyright &copy; 2014-2015. The [Compute.io](https://github.com/compute-io) Authors.


[npm-image]: http://img.shields.io/npm/v/compute-divide.svg
Expand Down

0 comments on commit aa41252

Please sign in to comment.