linspace: document & add a descending test

Author: Fil

README.md

@@ -505,7 +505,7 @@ Returns the difference between adjacent tick values if the same arguments were p
 
 <a name="range" href="#range">#</a> d3.<b>range</b>([<i>start</i>, ]<i>stop</i>[, <i>step</i>]) · [Source](https://github.com/d3/d3-array/blob/master/src/range.js), [Examples](https://observablehq.com/@d3/d3-range)
 
-Returns an array containing an arithmetic progression, similar to the Python built-in [range](http://docs.python.org/library/functions.html#range). This method is often used to iterate over a sequence of uniformly-spaced numeric values, such as the indexes of an array or the ticks of a linear scale. (See also [d3.ticks](#ticks) for nicely-rounded values.)
+Returns an array containing an arithmetic progression, similar to the Python built-in [range](http://docs.python.org/library/functions.html#range). This method is often used to iterate over a sequence of uniformly-spaced numeric values, such as the indexes of an array or the ticks of a linear scale. (See also [d3.ticks](#ticks) for nicely-rounded values, and [d3.linspace](#linspace) if you prefer to specify the number of values rather than the step.)
 
 If *step* is omitted, it defaults to 1. If *start* is omitted, it defaults to 0. The *stop* value is exclusive; it is not included in the result. If *step* is positive, the last element is the largest *start* + *i* \* *step* less than *stop*; if *step* is negative, the last element is the smallest *start* + *i* \* *step* greater than *stop*. If the returned array would contain an infinite number of values, an empty range is returned.
 
@@ -524,6 +524,15 @@ d3.range(0, 1, 1 / 49); // BAD: returns 50 elements!
 d3.range(49).map(function(d) { return d / 49; }); // GOOD: returns 49 elements.
 ```
 
+<a name="linspace" href="#range">#</a> d3.<b>linspace</b>(<i>start</i>, <i>stop</i>[, <i>n</i>][, <i>endpoint</i>]) · [Source](https://github.com/d3/d3-array/blob/master/src/linspace.js)<!-- , [Examples](https://observablehq.com/@d3/d3-linspace) -->
+
+Returns an array containing an arithmetic progression of *n* values ranging from *start* to *end*, including *end* if *endpoint* is requested. Similar to numpy’s [linspace](https://numpy.org/doc/stable/reference/generated/numpy.linspace.html). Defaults to *n* = 50 and *endpoint* = true.
+
+```js
+d3.linspace(0, 1, 101); // [0, 0.01, 0.02, …, 0.99, 1]
+d3.linspace(1, 0, 10, false); // [1, 0.9, 0.8, …, 0.1]
+```
+
 <a name="transpose" href="#transpose">#</a> d3.<b>transpose</b>(<i>matrix</i>) · [Source](https://github.com/d3/d3-array/blob/master/src/transpose.js), [Examples](https://observablehq.com/@d3/d3-transpose)
 
 Uses the [zip](#zip) operator as a two-dimensional [matrix transpose](http://en.wikipedia.org/wiki/Transpose).

test/linspace-test.js

@@ -1,7 +1,7 @@
 var tape = require("tape"),
     arrays = require("../");
 
-tape.only("linspace(start, stop)", function(test) {
+tape("linspace(start, stop)", function(test) {
   test.deepEqual(arrays.linspace(0, 49), [
      0,  1,  2,  3,  4,  5,  6,  7,  8,  9,
     10, 11, 12, 13, 14, 15, 16, 17, 18, 19,
@@ -21,3 +21,9 @@ tape("linspace(start, stop, n, false)", function(test) {
   test.deepEqual(arrays.linspace(2, 3, 5, false), [2, 2.2, 2.4, 2.6, 2.8]);
   test.end();
 });
+
+tape("linspace(start, stop, n) descending", function(test) {
+  test.deepEqual(arrays.linspace(5, 1, 5), [5, 4, 3, 2, 1]);
+  test.deepEqual(arrays.linspace(5, 0, 5, false), [5, 4, 3, 2, 1]);
+  test.end();
+});