@mitchallen/grid
A 2D grid that uses zero-based indexing.
Installation
You must use npm 2.7.0 or higher because of the scoped package name.
$ npm init
$ npm install @mitchallen/grid --save
Usage
There are two forms of usage:
- Square Grid
- Circle Grid
Square Grid Usage
Create a new folder and do the following at the command line:
$ npm init
$ npm install @mitchallen/grid --save
In the same folder create a file called index.js with the content below:
"use strict";
var gridFactory = require("@mitchallen/grid");
var xSize = 5;
var ySize = 10;
var value = 100;
var i = xSize - 1;
var j = ySize - 1;
var grid = gridFactory.Square( { x: xSize, y: ySize } );
if(!grid) {
console.error("couldn't create grid");
}
if(! grid.isCell( i, j ) ) {
console.error("parameters not within grid");
}
if(! grid.set( i, j, value )) {
console.error("couldn't set grid value");
}
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
An example similar to this exists on the examples folder out on the repo.
Square Methods
create( spec )
The create method is deprecated. Use Square instead.
Square( spec )
Factory method that returns a square grid object.
It takes one spec parameter that must be an object with x and y values specifying the size of the grid.
The x and y values can not be less than one (1).
The method will set xSize and ySize to 0 if no parameters are set
You can call Square multiple times to create multiple grids.
var gridFactory = require("@mitchallen/grid");
var grid1 = gridFactory.Square( { x: 5, y: 10 } );
var grid2 = gridFactory.Square( { x: 7, y: 20 } );
if(!grid1 || !grid2) ...
squareGrid.xSize
Returns the size of the x dimension.
grid.xSize.should.eql(5);
squareGrid.ySize
Returns the size of the y dimension.
grid.ySize.should.eql(10);
Square grid.isCell( x, y )
The x and y 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");
}
Square grid.set( x, y, value )
The x and y 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");
}
Square grid.get( x, y )
The x and y 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 );
}
Square 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);
Square 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);
Square grid.rows
Number of rows in the grid.
var r = grid.rows;
Square grid.rowSize(rowIndex)
var r = grid.rowSize(1);
Size of row.
Square grid.log()
Logs the size and contents of the internal array.
grid.log();
Example output:
size: 4
[ [ 20, 10, 10, 10, 10 ],
[ 10, 10, 10, 10, 10 ],
[ 10, 10, 10, 10, 10 ],
[ 10, 10, 10, 10, 30 ] ]
Circle Grid Usage
Create a new folder and do the following at the command line:
$ npm init
$ npm install @mitchallen/grid-circle --save
In the same folder create a file called index.js with the content below:
"use strict";
var gridFactory = require("@mitchallen/grid");
var grid = gridFactory.Circle( { rings: 5 } );
var r = 2, // ring
p = 4 // position
if(! grid.isCell( r, p ) ) {
console.error("parameters not within grid");
}
var value = 4;
if(! grid.set( r, p, value )) {
console.error("couldn't set grid value");
}
let result = grid.get( r, p );
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
Methods
Circle( spec )
Factory method that returns a circle grid object.
It takes one spec parameter that must be an object with a rings value specifying the number of rings in the grid.
The method will normalize rings to 0 if for a missing or bad parameter.
You can call Circle multiple times to create multiple grids.
var gridFactory = require("@mitchallen/grid");
var grid1 = gridFactory.Circle( { rings: 6 } );
var grid2 = gridFactory.Circle( { rings: 5 } );
if(!grid1 || !grid2) ...
Circle grid.rings
Returns the ring count for the grid.
grid.rings.should.eql(5);
Circle grid.ringSize(ring)
Returns the number of cells in the ring.
let ring = 1;
var result = grid.ringSize(ring);
Circle grid.isCell( ring, position )
The ring and position parameters should be zero-based coordinates.
Values that will return true:
- ring: 0 to rings minus one
- position: 0 to ringSize(ring) minus one.
For example if the rings passed to the create method is 5, then valid values for ring are 0 through 4.
The method is called internally by get.
if(! grid.isCell( ring, position ) ) {
console.error("parameters not within grid");
}
Circle grid.set( ring, position, value )
The ring and position values are passed to the isCell method internally for validation. 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( ring, position, value )) {
console.error("couldn't set grid value");
}
Circle grid.get( ring, position )
The ring and position 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( ring, position );
if(! result) {
console.error("couldn't get grid value");
} else {
console.log("grid value: ", result );
}
Circle 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);
Circle 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 ring = 0;
let pos = 0;
let gridValue = 100;
let cloneValue = 500;
// Set a value in the original grid
grid.set(ring,pos,gridValue);
// Clone the grid
let arr = grid.cloneArray();
// Verify value exists in clone
arr[ring][pos].should.eql(gridValue);
// Change value in clone
arr[ring][pos] = cloneValue;
// Verify new value is set in clone
arr[ring][pos].should.eql(cloneValue);
// Ensure that value does not alter original grid
grid.get(ring,pos).should.eql(gridValue);
Circle grid.log()
Logs the size and contents of the internal array.
grid.log();
Example output:
size: 3
[ [ 8 ],
[ 8, 8, 8, 8, 8, 8 ],
[ 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8 ] ]
Examples
You can find examples in the repos listed below in the examples folder.
Browser Client Example
You can reference a minimized client version inside an HTML script tag using one of these URL's:
- https://cdn.rawgit.com/mitchallen/grid/v0.1.21/dist/grid.min.js
- https://unpkg.com/@mitchallen/grid@0.1.21/dist/grid.min.js
Adjust the URL's depending upon what version is available
The rawgit.com URL will pull based on the version from GitHub.
The unpkg.com URL will pull based on the version in npmjs.com.
See http://rawgit.com and https://unpkg.com for other ways to retrieve the file.
The factory function can be retrieved from window.MitchAllen.Grid:
var factory = window.MitchAllen.Grid;
var xSize = 10, ySize = 5;
var sg = factory.Square( { x: xSize, y: ySize } );
Example:
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Grid Example</title>
<meta name="description" content="Grid Example">
<!-- either cdn should work
<script src="https://cdn.rawgit.com/mitchallen/grid/v0.1.21/dist/grid.min.js"></script>
-->
<script src="https://unpkg.com/@mitchallen/grid@0.1.21/dist/grid.min.js"></script>
<script>
var factory = window.MitchAllen.Grid;
console.log(factory);
var xSize = 10, ySize = 5;
var sg = factory.Square( { x: xSize, y: ySize } );
sg.log();
</script>
</head>
<body>
<h1>Grid Example</h1>
</body>
</html>
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.23
- replaced internal square with @mitchallen/grid-square
Version 0.1.22
- square and cirlce modules now uses @mitchallen/git-core
- remove modules/base.js which is replaced by grid-core
Version 0.1.21
- Client must now use window.MitchAllen.Grid to reference factory function.
Version 0.1.20
- Updated CDN URL
Version 0.1.19
- Checked in dist modules
Version 0.1.18
- added sub-modules to distribution
Version 0.1.17
- main now points to dist/grid
Version 0.1.16
- Updated client example to use unpkg.com
Version 0.1.15
- Fixed version history
Version 0.1.14
- added uglify and babel es2015 tasks
- updated client example to use CDN
- Removed dist from .npmignore so dist files can be accessed via unpkg.com
Version 0.1.13
- added browserify task
- created client example
Version 0.1.12
- added rows method to base class
Version 0.1.11
- Refactored code
- added Triangle method for future expansion
Version 0.1.10
- added experiment Hexagon method
Version 0.1.9
- Square now replaces create
- added create deprecation warning
- Added Circle grid method
Version 0.1.8
- removed redundant negative check
Version 0.1.7
- create now sets defaults if parameters invalid instead of returning null
Version 0.1.6
- added the xSize and ySize properties
Version 0.1.5
- added log method
Version 0.1.4
- added cloneArray method
Version 0.1.3
- added fill method
Version 0.1.2
- updated readme
Version 0.1.1
- updated example to use published package
- updated description in package.json
Version 0.1.0
- initial release