Merge pull request #1 from Planeshifter/dev

Return null for empty array & accessor function support

README.md

@@ -22,17 +22,38 @@ To use the module,
 var range = require( 'compute-range' );
 ```
 
-#### range( arr )
+#### range( arr[, accessor] )
 
-Returns the range of an `array` of values.
+Computes the arithmetic range of an `array`. For primitive `arrays`,
 
 ``` javascript
-var r = range( [2,3,4,1] );
+var arr = [ 2, 3, 4, 1 ];
+
+var r = range( arr );
+// returns [1,4]
+```
+
+For object `arrays`, provide an accessor `function` for accessing `array` values
+
+``` javascript
+var arr = [
+	[1,2],
+	[3,3],
+	[4,4],
+	[6,1]
+];
+
+function getValue( d ) {
+	return d[ 1 ];
+}
+
+var r = range( arr, getValue );
 // returns [1,4]
 ```
 
-Note: the first value of the returned `array` is always the minimum value and the second value is always the maximum value.
+__Note__: if an input `array` does not contain any `numeric` values, the function returns `null`.
 
+__Note__: the first value of the returned `array` is always the minimum value and the second value is always the maximum value.
 
 ## Examples
 
@@ -84,7 +105,7 @@ $ open reports/coverage/lcov-report/index.html
 
 ## License
 
-[MIT license](http://opensource.org/licenses/MIT). 
+[MIT license](http://opensource.org/licenses/MIT).
 
 
 ---
@@ -109,4 +130,4 @@ Copyright © 2014. Athan Reines.
 [dev-dependencies-url]: https://david-dm.org/dev/compute-io/range
 
 [github-issues-image]: http://img.shields.io/github/issues/compute-io/range.svg
-[github-issues-url]: https://github.com/compute-io/range/issues
+[github-issues-url]: https://github.com/compute-io/range/issues

lib/index.js

@@ -8,11 +8,11 @@
 *
 *
 *	NOTES:
-*		[1] 
+*		[1]
 *
 *
 *	TODO:
-*		[1] 
+*		[1]
 *
 *
 *	LICENSE:
@@ -26,36 +26,46 @@
 *
 */
 
-(function() {
-	'use strict';
+'use strict';
 
-	/**
-	* FUNCTION: range( arr )
-	*	Returns the arithmetic range of an array of values.
-	*/
-	function range( arr ) {
-		if ( !Array.isArray( arr ) ) {
-			throw new TypeError( 'range()::invalid input argument. Must provide an array.' );
-		}
-		var len = arr.length,
-			min = arr[ 0 ],
-			max = min,
-			x;
-
-		for ( var i = 1; i < len; i++ ) {
-			x = arr[ i ];
-			if ( x < min ) {
-				min = x;
-			} else if ( x > max ) {
-				max = x;
-			}
-		}
-		return [ min, max ];
-	} // end FUNCTION range()
+/**
+* FUNCTION: range( arr[, accessor] )
+*	Returns the arithmetic range of an array of values.
+*
+* @param {Array} arr - input array
+* @param {Function} [accessor] - accessor function for accessing array values
+* @returns {Array|null} arithmetic range or null
+*/
+function range( arr, clbk ) {
+	if ( !Array.isArray( arr ) ) {
+		throw new TypeError( 'range()::invalid input argument. Must provide an array.' );
+	}
 
+	if ( arguments.length > 1 && typeof clbk !== 'function' ) {
+		throw new TypeError( 'range()::invalid input argument. Accessor must be a function. Value: `' + clbk + '`.' );
+	}
+
+	var len = arr.length,
+		min = ( clbk ) ? clbk( arr[0] ) : arr[ 0 ],
+		max = min,
+		x;
+
+	if ( len === 0 ) {
+		return null;
+	}
+
+	for ( var i = 1; i < len; i++ ) {
+		x = ( clbk ) ? clbk( arr[i] ) : arr[ i ];
+		if ( x < min ) {
+			min = x;
+		} else if ( x > max ) {
+			max = x;
+		}
+	}
+	return [ min, max ];
+} // end FUNCTION range()
 
-	// EXPORTS //
 
-	module.exports = range;
+// EXPORTS //
 
-})();
+module.exports = range;

test/test.js

@@ -45,11 +45,60 @@ describe( 'compute-range', function tests() {
 		}
 	});
 
+	it( 'should throw an error if provided an accessor which is not a function', function test() {
+		var values = [
+			'5',
+			5,
+			null,
+			undefined,
+			NaN,
+			true,
+			[],
+			{}
+		];
+		for ( var i = 0; i < values.length; i++ ) {
+			expect( badValue( values[i] ) ).to.throw( TypeError );
+		}
+		function badValue( value ) {
+			return function() {
+				range( [], value );
+			};
+		}
+	});
+
+	it( 'should return null if provided an empty array', function test() {
+		var expected = null;
+
+		assert.strictEqual( range( [] ), expected );
+	});
+
 	it( 'should return the arithmetic range', function test() {
 		var data = [ 3,4,2,1,4 ],
 			expected = [1,4];
 
 		assert.deepEqual( range( data ), expected );
 	});
 
-});
+	it( 'should return the arithmetic range using an accessor function', function test() {
+		var data, expected, actual;
+
+		data = [
+			[1,3],
+			[3,4],
+			[4,2],
+			[5,1],
+			[7,4],
+			[8,6]
+		];
+
+		expected = [ 1, 6 ];
+		actual = range( data, getValue );
+
+		assert.deepEqual( actual, expected );
+
+		function getValue( d ) {
+			return d[ 1 ];
+		}
+	});
+
+});