indexspace
Generates a linearly spaced index array from a subsequence string.
Installation
$ npm install compute-indexspace
For use in the browser, use browserify.
Usage
var indexspace = ;
indexspace( str, len )
Generates a linearly spaced index array
from a subsequence string
. len
specifies the reference array
length, which is needed to properly interpret the subsequence string
. If len = 0
, the function returns an empty array
.
var arr = ;// returns [ 0, 1, 2, 3, 4 ]arr = ;// returns []
The subsequence string
syntax is similar to Python's slice notation.
var str = '<start>:<stop>:<increment>';
Notes about the notation:
- If an
increment
is not specified, the default increment is1
. Anincrement
of zero is not allowed. - The
start
index is inclusive, while thestop
index is exclusive. - Both
start
andstop
indices are optional. If not provided,start
andstop
default to index extremes. - Both
start
andstop
can be negative, in which case the index is subtracted fromlen
.
var arr = ;// returns [ 2, 3, 4 ];arr = ;// returns [ 0, 1, 2 ]
The function also recognizes the end
keyword, which refers to the last index; i.e., len-1
. If specified as the stop
index, end
is inclusive and equivalent to <start>::<increment>
.
var arr = ;// returns [ 4, 3, 2, 1, 0 ]arr = ;// returns [ 0, 1, 2, 3, 4 ]
Basic arithmetic (subtraction and division) may be performed on the end
keyword. The result from division is rounded up to the next integer.
var arr = ;// returns [ 2, 1, 0 ];arr = ;// returns [ 0, 1 ]arr = ;// returns [ 2, 3, 4 ]arr = ;// returns [ 2, 1, 0 ];arr = ;// returns [ 1, 3 ];
Note: unlike Matlab, but like Python, the subsequence string
is upper-bound exclusive. For example, in Python, 0:2
corresponds to the index array [0,1]
. In Matlab, 1:3
corresponds to [1,2,3]
.
This implementation chooses to follow the Python convention such that :n
combined with n:
is equivalent to :
. Using the Matlab convention, the two subsequences would overlap by one element.
Examples
var indexspace = ;var arr = ;// returns [ 0, 1, 2, 3, 4 ]arr = ;// returns [ 2, 3, 4 ]arr = ;// returns [ 0, 1, 2 ]arr = ;// returns [ 2, 3 ]arr = ;// returns [ 1, 3 ]arr = ;// returns [ 2, 4 ]arr = ;// returns [ 0, 3, 6, 9 ]arr = ;// returns [ 0, 1, 2 ]arr = ;// returns [ 0, 2 ]arr = ;// returns [ 1, 3 ]arr = ;// returns [ 0, 1, 2, 3 ]arr = ;// returns [ 4, 3, 2, 1, 0 ]arr = ;// returns [ 4, 3, 2, 1 ]arr = ;// returns [ 3, 2, 1 ]arr = ;// returns [ 4, 2 ]arr = ;// returns [ 0, 1, 2, 3, 4 ]arr = ;// returns [ 0, 1, 2, 3 ]arr = ;// returns [ 0, 1 ]arr = ;// returns [ 2, 1, 0 ]arr = ;// returns [ 2, 3, 4 ]
To run the example code from the top-level application directory,
$ node ./examples/index.js
Notes
The motivation for this module stems from wanting to create an API for arrays
similar to Python and Matlab; e.g., A = B[1:6:2];
. JavaScript only supports basic indexing; e.g., A = B[3];
.
The workaround provided by this module is to express the subsequence syntax as a string
, which, when provided with a reference array
length, is parsed and then converted into an index array
. A consumer can then iterate through the index array
to extract the desired elements.
var indexspace = ;// Create an array...var len = 10arr;arr = len ;for var i = 0; i < len; i++arr i = i;// Create an index array...var idx = ;// From the original array, create a reversed array...var rev = len ;for var j = 0; j < len; j++rev j = arr idxj ;console;console;
Tests
Unit
Unit tests use the Mocha test framework with Chai assertions. To run the tests, execute the following command in the top-level application directory:
$ make test
All new feature development should have corresponding unit tests to validate correct functionality.
Test Coverage
This repository uses Istanbul as its code coverage tool. To generate a test coverage report, execute the following command in the top-level application directory:
$ make test-cov
Istanbul creates a ./reports/coverage
directory. To access an HTML version of the report,
$ make view-cov
License
Copyright
Copyright © 2015. Athan Reines.