Merge pull request #3 from possibly/master

forEach, getRow, getColumn, README updates!

Author: tillarnold

README.md

@@ -21,6 +21,12 @@ If the coordinates are *not* valid an `Error` is thrown.
 ### get(x, y)
 Returns the value of the given coordinate. The coordinate is checked using `validateCoords`.
 
+### getRow(rowNumber)
+Returns an array of the requested row.
+
+### getColumn(colNumber)
+Returns an array of the requested column.
+
 ### set(x, y, value)
 Sets the value of the given coordinate to `value`. The coordinate is checked using `validateCoords`.
 
@@ -30,5 +36,42 @@ Returns the height of the array.
 ### getWidth()
 Returns the width of the array.
 
-### getNeighbours(x, y)
+### getNeighbours(x, y, [, distance])
 Returns an array containing all values of the cells next to the given coordinate.
+
+For example, distance not set:
+```
+[ ][ ][ ][ ][ ]
+[ ][*][*][*][ ]
+[ ][*][X][*][ ]
+[ ][*][*][*][ ]
+[ ][ ][ ][ ][ ]
+```
+
+The given coordinate is marked with an `X`. The function will return an array containing the values for the fields marked with an `*`.
+
+Example, distance = 2:
+```
+[*][*][*][*][*]
+[*][*][*][*][*]
+[*][*][X][*][*]
+[*][*][*][*][*]
+[*][*][*][*][*]
+```
+
+The function will return an array containing the values for the fields marked with an '*'. Notice that distance will change what cells count as neighbors.
+
+### forEach(fn, [, thisArg])
+Executes a provided function once per array element.
+
+`fn` is the function to execute for each element, taking three arguments: 
+
+  currentValue
+    The current element being processed in the array.
+  index
+    The object index, {x: x, y: y}, of the current element being processed in the 2d array.
+  array
+    The Fixed2DArray that forEach is being applied to. 
+
+  thisArg 
+    Optional. Value to use as this when executing callback.

lib/fixed-2d-array.js

@@ -32,6 +32,65 @@ Fixed2DArray.prototype.getWidth = function getWidth() {
   return this._width;
 };
 
+/**
+ * Returns the requested row from the grid.
+ *
+ * @param rowNumber {number} number of the row where top left is (0,0).
+ */
+Fixed2DArray.prototype.getRow = function getRow(rowNumber){
+  try{
+    this.validateCoords(0,rowNumber);
+  } catch(err){
+    throw new Error('fixed-2d-array: row number '+rowNumber+' is not valid.' +
+                    ' The size of this array is ('+this._width+'/'+this._height+')');
+  }
+
+  return this._grid[rowNumber];
+};
+
+/**
+ * Returns the requested column from the grid.
+ *
+ * @param colNumber {number} number of the column where top left is (0,0).
+ */
+Fixed2DArray.prototype.getColumn = function getRow(colNumber){
+  try{
+    this.validateCoords(colNumber,0);
+  } catch(err){
+    throw new Error('fixed-2d-array: row number '+colNumber+' is not valid.' +
+                    ' The size of this array is ('+this._width+'/'+this._height+')');
+  }
+
+  var returnArray = [];
+
+  for (var i = 0; i < this._height; i++) {
+    returnArray.push(this._grid[i][colNumber]);
+  }
+  return returnArray;
+};
+
+/**
+ * Executes a provided function once per array element.
+ *
+ * @param fn {function} Function to execute for each element, taking three arguments: 
+ *
+ *  currentValue
+ *    The current element being processed in the array.
+ *  index
+ *    The object index, {x: x, y: y}, of the current element being processed in the 2d array.
+ *  array
+ *    The Fixed2DArray that forEach is being applied to. 
+ *
+ * @param thisArg Optional. Value to use as this when executing callback.
+ */
+Fixed2DArray.prototype.forEach = function forEach(fn, thisArg){
+  for (var i = 0; i < this._width; i++) {
+    for (var j = 0; j < this._height; j++) {
+      fn.call(thisArg, this._grid[i][j], {x: i, y: j}, this);
+    }
+  }
+};
+
 /**
  * Throws an Error if the given coordinate is invalid.
  *

test/test.js

@@ -23,6 +23,32 @@ test('get and set', function (t) {
   t.equal(fa.get(9,7),'This is a string!');
 });
 
+test('get correct row and column',function (t) {
+  t.plan(6);
+  var fa = new fixedArray(10,10);
+
+  t.equal(fa.getRow(0).length,10);
+  t.equal(fa.getColumn(1).length,10);
+
+  fa.set(0,1,'This is a string!');
+  t.equal(fa.getRow(0)[1],'This is a string!');
+  t.equal(fa.getColumn(1)[0],'This is a string!');
+  t.throws(function(){fa.getRow(-1);});
+  t.throws(function(){fa.getColumn(11);});
+});
+
+test('forEach',function (t) {
+  t.plan(1);
+  var fa = new fixedArray(10,10,0);
+
+  function fun(currentValue, index, array){
+    array.set(index.x, index.y, currentValue+1);
+  }
+
+  fa.forEach(fun);
+  t.equal(fa.get(0,0),1);
+});
+
 test('exception on index out of bounds', function (t) {
   t.plan(3);
   var fa = new fixedArray(10,10);