Major refactoring of the API

Author: rreusser

README.md

@@ -5,25 +5,22 @@
 ## Example
 
 ```javascript
-var linspace = require('ndarray-linspace')
+var ndarray = require('ndarray');
+var linspace = require('ndarray-linspace');
 
-linspace(2, 3, 5)
+linspace(ndarray([], [5]), 2, 3);
 // => ndarray([2, 2.25, 2.5, 2.75, 3])
 
-linspace(2, 3, 4, {endpoint: false})
+linspace(ndarray([], [5]), 2, 3, {endpoint: false});
 // => ndarray([2, 2.25, 2.5, 2.75])
 
-linspace(2, 4, 10, {dtype: 'int8'})
-// => ndarray([2, 2, 2, 2, 2, 3, 3, 3, 3, 4])
-
-var y = pool.zeros([5])
-linspace(y, 1, 3, 5)
-// y => ndarray([1, 1.5, 2, 2.5, 3])
-
-var y = pool.zeros([2, 2])
-linspace(y, 0, 1, 2)
+linspace(ndarray([], [2, 2]), 0, 1)
 // y => [ 0, 0 ]
 //      [ 1, 1 ]
+
+linspace(ndarray([], [2, 2]), 0, 1, {axis: 1})
+// y => [ 0, 1 ]
+//      [ 0, 1 ]
 ```
 
 ## Installation
@@ -34,17 +31,16 @@ npm install ndarray-linspace
 
 ## API
 
-#### `require('ndarray-linspace')([output,] start, end, steps[, options])`
+#### `require('ndarray-linspace')(output, start, end[, options])`
 An array of equally spaced values.
 
 **Arguments**:
-- `output` (optional): if provided, the destination array to be filled with values. If the number of dimensions is greater than one, then the length of the first dimension must match the number of values and the entire ndarray will be filled with the linspace corresponding to the index of the first dimension.
+- `output` The destination array to be filled with values.
 - `start`: starting value of the interval
 - `end`: ending value of the interval
-- `steps`: number of divisions
 - `options` (optional): A hash of options. Options are:
-  - `dtype`: dtype of output array (only used if output array not specified)
-  - `endpoint` (boolean): whether the output contains the endpoint of the interval
+  - `endpoint` (default: `true`): whether the output contains the endpoint of the interval
+  - `axis` (default: `0`): the dimension along which to fill the array. Must be an integer less than or equal to the dimension of the input.
 
 **Returns**: A reference to the output
 

examples/index.js

@@ -1,7 +1,7 @@
-'use strict'
+'use strict';
 
-var linspace = require('../')
+var linspace = require('../');
 
-console.log(linspace(2, 3, 10, {endpoint: false}))
+console.log(linspace(2, 3, 10, {endpoint: false}));
 
-console.log(linspace(2, 4, 10, {dtype: 'int8'}))
+console.log(linspace(2, 4, 10, {dtype: 'int8'}));

index.js

@@ -1,44 +1,46 @@
-'use strict'
+'use strict';
 
-var pool = require('ndarray-scratch')
-var fill = require('ndarray-fill')
-var extend = require('util-extend')
+var fill = require('ndarray-fill');
+var isndarray = require('isndarray');
+var isnonneg = require('validate.io-nonnegative-integer');
+var isbool = require('validate.io-boolean');
 
-module.exports = linspace
+module.exports = linspace;
 
-var defaults = {
-  endpoint: true,
-  dtype: 'double'
-}
+function linspace (output, start, end, options) {
+  var n, endpoint, axis, d;
+
+  if (!isndarray(output)) {
+    throw new Error('ndarray-linspace: First argument must be a ndarray');
+  }
 
-function linspace () {
-  var start, end, n, options, output
-
-  options = {}
-  extend(options, defaults)
-
-  if (isFinite(arguments[0])) {
-    start = arguments[0]
-    end = arguments[1]
-    n = arguments[2]
-    extend(options, arguments[3] || {})
-    output = pool.zeros([n], options.dtype)
-  } else {
-    output = arguments[0]
-    start = arguments[1]
-    end = arguments[2]
-    n = arguments[3]
-    extend(options, arguments[4] || {})
-
-    if (output.shape[0] !== n) {
-      throw new Error('number of values (' + n + ') must match the first dimension of the output (' + output.shape[0] + ')')
-    }
+  n = output.shape[0];
+
+  options = options || {};
+
+  if (options.endpoint !== undefined && !isbool(options.endpoint)) {
+    throw new Error('ndarray-linspace: Endpoint must be a boolean. Got ' + options.endpoint);
   }
+  endpoint = !!(options.endpoint || true);
+
+  if (options.axis !== undefined && !isnonneg(options.axis)) {
+    throw new Error('ndarray-linspace: Axis must be a nonegative integer. Got ' + options.axis);
+  }
+
+  // Default axis, after we've checked the input
+  axis = options.axis || 0;
+
+  if (axis > output.dimension) {
+    throw new Error('ndarray-linspace: Axis (' + axis + ') must be <= dimension (' + output.dimension + ')');
+  }
+
+  // Precompute the spacing:
+  d = (end - start) / Math.max(1, n - (endpoint ? 1 : 0));
 
-  var d = (end - start) / (n - (options.endpoint ? 1 : 0))
-  fill(output, function (i) {
-    return start + i * d
-  })
+  // Fill it!
+  fill(output, function () {
+    return start + arguments[axis] * d;
+  });
 
-  return output
+  return output;
 }

package.json

@@ -1,10 +1,12 @@
 {
   "name": "ndarray-linspace",
-  "version": "1.0.4",
+  "version": "2.0.0",
   "description": "Fill an ndarray with equally spaced values",
   "main": "index.js",
   "scripts": {
-    "test": "standard && mocha test/*"
+    "test": "semistandard && mocha test/*",
+    "lint": "semistandard",
+    "lint-fix": "semistandard --fix"
   },
   "keywords": [
     "ndarray",
@@ -20,12 +22,19 @@
     "chai": "^3.4.1",
     "mocha": "^2.3.4",
     "ndarray": "^1.0.18",
+    "ndarray-show": "^2.0.0",
     "ndarray-tests": "^1.3.0",
-    "standard": "^5.4.1"
+    "semistandard": "^9.1.0"
   },
   "dependencies": {
+    "is-positive-integer": "^1.1.1",
+    "isndarray": "^1.0.0",
+    "ndarray": "^1.0.18",
     "ndarray-fill": "^1.0.1",
     "ndarray-scratch": "^1.2.0",
-    "util-extend": "^1.0.1"
+    "util-extend": "^1.0.1",
+    "validate.io-boolean": "^1.0.4",
+    "validate.io-nonnegative-integer": "^1.0.0",
+    "validate.io-number": "^1.0.3"
   }
 }

test/index.js

@@ -1,50 +1,73 @@
 /* global describe, it */
-'use strict'
+'use strict';
 
-var ndarray = require('ndarray')
-var ndt = require('ndarray-tests')
-var linspace = require('../')
-var assert = require('chai').assert
-var pool = require('ndarray-scratch')
+var ndarray = require('ndarray');
+var ndt = require('ndarray-tests');
+var linspace = require('../');
+var assert = require('chai').assert;
+// var show = require('ndarray-show');
 
 describe('linspace', function () {
+  describe('failure modes', function () {
+    it('fails if the first argument is not a ndarray', function () {
+      assert.throws(function () {
+        linspace(0, 10);
+      }, Error, /must be a ndarray/);
+    });
+
+    it('throws an error if the axis not a number', function () {
+      assert.throws(function () {
+        linspace(ndarray([], [2, 2]), 0, 1, {axis: '4'});
+      }, Error, 'Axis must be a nonegative integer');
+    });
+
+    it('throws an error if the axis is greater than the dimension', function () {
+      assert.throws(function () {
+        linspace(ndarray([], [2, 2]), 0, 1, {axis: 4});
+      }, Error, 'must be <= dimension');
+    });
+
+    it('fails if the endpoint is not a boolean', function () {
+      assert.throws(function () {
+        linspace(ndarray([], [1]), 0, 10, {endpoint: 7});
+      }, Error, /must be a boolean/);
+    });
+  });
+
   it('create a new linspace with and endpoint', function () {
-    var x = linspace(0, 1, 11)
-    var y = ndarray([0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1])
-    assert(ndt.equal(x, y, 1e-8))
-  })
+    var x = linspace(ndarray([], [11]), 0, 10);
+    var y = ndarray([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
+    assert(ndt.equal(x, y, 1e-8));
+  });
 
   it('create a new linspace without and endpoint', function () {
-    var x = linspace(0, 1, 10, {endpoint: false})
-    var y = ndarray([0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9])
-    assert(ndt.equal(x, y, 1e-8))
-  })
-
-  it('allows a dtype', function () {
-    var x = linspace(0, 10, 5, {dtype: 'int8'})
-    var y = ndarray([0, 2, 5, 7, 10])
-    assert(ndt.equal(x, y, 1e-8))
-  })
-
-  it('writes in place if output array provided', function () {
-    var x = pool.zeros([10])
-    linspace(x, 0, 1, 10, {endpoint: false})
-    var y = ndarray([0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9])
-    assert(ndt.equal(x, y, 1e-8))
-  })
+    var x = linspace(ndarray([], [10]), 0, 9, {endpoint: false});
+    var y = ndarray([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]);
+    assert(ndt.equal(x, y, 1e-8));
+  });
 
   it('fills in more than one dimension', function () {
-    var x = pool.zeros([2, 2])
-    linspace(x, 0, 1, 2)
-    var y = ndarray([0, 0, 1, 1], [2, 2])
-    assert(ndt.equal(x, y, 1e-8))
-  })
-
-  it("throws an error if the size of the first dimension doesn't match the number of points", function () {
-    var x = pool.zeros([2, 2])
-    assert.throws(function () {
-      linspace(x, 0, 1, 10)
-    }, Error, 'must match')
-  })
-})
+    var x = linspace(ndarray([], [2, 2]), 0, 1);
+    var y = ndarray([0, 0, 1, 1], [2, 2]);
+    assert(ndt.equal(x, y, 1e-8));
+  });
+
+  it('accepts a different axis', function () {
+    var x = linspace(ndarray([], [2, 2]), 0, 1, {axis: 1});
+    var y = ndarray([0, 1, 0, 1], [2, 2]);
+    assert(ndt.equal(x, y, 1e-8));
+  });
+
+  it('uses the first point if only one point requested and endpoint = true', function () {
+    var x = linspace(ndarray([], [1]), 1, 2, {endpoint: true});
+    var y = ndarray([1], [1]);
+    assert(ndt.equal(x, y));
+  });
+
+  it('uses the first point if only one point requested and endpoint = false', function () {
+    var x = linspace(ndarray([], [1]), 1, 2, {endpoint: false});
+    var y = ndarray([1], [1]);
+    assert(ndt.equal(x, y));
+  });
+});