node package manager
Don’t reinvent the wheel. Reuse code within your team. Create a free org »

@mitchallen/grid-core

@mitchallen/grid-core

Grid core

Version Coverage Status Version


Installation

You must use npm 2.7.0 or higher because of the scoped package name.

$ npm init
$ npm install @mitchallen/grid-core --save 

Usage

Create a new folder and do the following at the command line:

$ npm init
$ npm install @mitchallen/grid-core --save

In the same folder create a file called index.js with the content below:

"use strict";

var gridFactory = require("@mitchallen/grid-core");

var rows = 5;

var grid = gridFactory.create( { rows: rows } );

if(!grid) {
    console.error("couldn't create grid");
}

var i = rows - 1,
    j = 3,
    value = 999;

if(! grid.set( i, j, value )) {
    console.error("couldn't set grid value");
}

grid.log();

if(! grid.isCell( i, j ) ) {
    console.error("parameters not within grid");
}

let result = grid.get( i, j );

if(! result) {
    console.error("couldn't get grid value");
} else {
    console.log("grid value: ", result );
}

At the command line, execute the following:

$ node index.js

Output:

size: 5: 
[ [], [], [], [], [ , , , 999 ] ]
grid value:  999

An example similar to this exists on the examples folder out on the repo.

Browser Usage

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <title>Grid Core Example</title>
    <meta name="description" content="Grid Core Example">
    <!-- either cdn should work -->
    <!--
    <script src="https://cdn.rawgit.com/mitchallen/grid-core/v0.1.5/dist/grid-core.min.js"></script>
    -->
    <script src="https://unpkg.com/@mitchallen/grid-core@0.1.5/dist/grid-core.min.js"></script>
    <script>
      var factory = window.MitchAllen.GridCore;
      console.log(factory);
      var rows = 5;
      var gc = factory.create( { rows: rows } );
      gc.set(rows-1,6,"alpha");
      console.log(gc);
      gc.log(); 
    </script>
  </head>
  <body>
    <h1>Grid Core Example</h1>
    <p>See JavaScript developer console for output.</p>
  </body>
</html>

Methods

create( spec )

Factory method that returns a sparse grid object.

It takes one spec parameter that must be an object with a rows value specifying the size of the number of rows in the grid.

You can call create multiple times to create multiple grids.

var gridFactory = require("@mitchallen/grid-core");

var grid1 = gridFactory.create( { rows: 5 } );
var grid2 = gridFactory.create( { rows: 10 } );

if(!grid1 || !grid2) ...

rows

Returns the number for rows in the grid.

grid.rows.should.eql(5);

rowsSize(rowId)

Returns the number of items in the array in row rowId.

grid.rowSize(3).should.eql(10);

A row size is determined by the highest zero-based position inserted into that row.

grid.isCell( row, pos )

The row and pos parameters should be zero-based coordinates ranging from zero (0) to axis size minus one.

The method is called internally by get.

if(! grid.isCell( i, j ) ) {
	console.error("parameters not within grid");
}

grid.set( row, pos, value )

The row and pos values must be greater than zero. If the parameters fail validation then a value of false is returned. Otherwise true is returned.

The value parameter can be a number, a string or even an object.

if(! grid.set( i, j, value )) {
	console.error("couldn't set grid value");
}

Only the row needs to exist. If the position in the row does not exist it will be created.

grid.get( row, pos )

The row and pos values are passed to the isCell method internally for validation. If the parameters fail validation then a null object is returned. Otherwise the value of the cell (grid location) is returned.

The returned value can be a number, a string or even an object.

let result = grid.get( i, j );

if(! result) {
	console.error("couldn't get grid value");
} else {
	console.log("grid value: ", result );
}

grid.fill(value)

Fills the grid with whatever is passed in as value. Value can be a number, a string or even an object. Any existing values in the grid will be replaced with the new fill value.

let fillValue = "foo";

var result = grid.fill(fillValue);

grid.cloneArray()

Returns a clone of the internal array. This is not a reference. So changes to the cloned array should not change the original.

let tX = 0;
let tY = 0;
let gridValue = 100;
let cloneValue = 500;

// Set a value in the original grid
grid.set(tX,tY,gridValue);

// Clone the grid	
let arr = grid.cloneArray();

// Verify value exists in clone
arr[tX][tY].should.eql(gridValue);

// Change value in clone
arr[tX][tY] = cloneValue;

// Verify new value is set in clone
arr[tX][tY].should.eql(cloneValue);

// Ensure that value does not alter original grid
grid.get(tX,tY).should.eql(gridValue);

grid.log()

Logs the size and contents of the internal array.

grid.log();

Example output:

size: 5: 
[ 
  [], 
  [], 
  [], 
  [], 
  [ , , , 999 ] ]

Testing

To test, go to the root folder and type (sans $):

$ npm test

Repo(s)


Contributing

In lieu of a formal style guide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code.


Version History

Version 0.1.9

  • updated .npmignore
  • updated client dist version

Version 0.1.8

  • added test cases for 100% code coverage

Version 0.1.7

  • updated badge links

Version 0.1.6

  • changed license to MIT
  • integrated travis-ci and codecov.io
  • added badges to readme

Version 0.1.5

  • removed unused dependency

Version 0.1.4

  • added examples

Version 0.1.3

  • Removed dist from .npmignore

Version 0.1.2

  • fixed browserify standalone setting
  • used window.MitchAllen.GridCore to access from the browser

Version 0.1.1

  • removed obsolete file

Version 0.1.0

  • initial release