.hi() and .lo() documentation is confusing

[deoxxa]

@timoxley and I, being mere mortals, had trouble understanding the operation of .hi() and .lo().

Brain dump

• the way they're introduced in the documentation makes them a little confusing, in that they're introduced solely as a mechanism to get a "view" of a larger array, and then only later explained fully in their operation
• hi and lo seem to suggest a spatial relationship, which makes hi sound like the upper-left corner of the array, and lo the lower-right
• the names offset and limit might make the operation of the functions clearer

Code I used to understand how it works

var ndarray = require("ndarray");

var whole_array = ndarray(new Buffer(8 * 8), [8, 8]),
    view        = whole_array.hi(7, 6).lo(5, 4);

var x = 0, y = 0;

for (x=0;x<whole_array.shape[0];++x) {
  for (y=0;y<whole_array.shape[1];++y) {
    whole_array.set(x, y, 0);
  }
}

for (x=0;x<view.shape[0];++x) {
  for (y=0;y<view.shape[1];++y) {
    view.set(x, y, 1);
  }
}

for (x=0;x<whole_array.shape[0];++x) {
  for (y=0;y<whole_array.shape[1];++y) {
    process.stdout.write(whole_array.get(x, y) + " ");
  }

  process.stdout.write("\n");
}

0 0 0 0 0 0 0 0
0 0 0 0 0 0 0 0
0 0 0 0 0 0 0 0
0 0 0 0 0 0 0 0
0 0 0 0 0 0 0 0
0 0 0 0 1 1 0 0
0 0 0 0 1 1 0 0
0 0 0 0 0 0 0 0

[mikolalysenko]

Yeah, I agree this could use some better explanation. What helps is to draw a picture, where you can imagine that lo shifts the upper left corner inwards some amount, and that hi moves the lower right corner. So for example, if you want to cut out an interval [8,10) in a 1D array you could do,

x.lo(8).hi(2)

Or

x.hi(10).lo(8)

If I ever get around to presenting this stuff, I will go through and make all the necessary graphics to explain how this works.

[letmaik]

I was confused myself just now looking at the docs. I think it would be immensly useful to add a concrete example for lo() and hi(), and as it's so close to numpy ndarray, maybe add a relation to it. Like:
x.hi(10).lo(8) is equal to x[8:10]