array-kit 0.2.8 → 0.2.9

package/lib/array-kit.js

@@ -36,11 +36,12 @@ const arrayKit = {
 	deleteValue: require( './deleteValue.js' )
 } ;
 
-module.exports = arrayKit ;
+Object.assign( arrayKit , require( './sum.js' ) ) ;
 
 arrayKit.randomInteger = ( min , max ) => min + Math.floor( ( max - min + 1 ) * Math.random() ) ;
-
 arrayKit.random = arrayKit.randomElement = array => array[ Math.floor( array.length * Math.random() ) ] ;
 arrayKit.shuffle = array => arrayKit.sample( array , array.length , true ) ;
 arrayKit.randomSampleSize = ( array , min , max , inPlace ) => arrayKit.sample( array , arrayKit.randomInteger( min , max ) , inPlace ) ;
 
+module.exports = arrayKit ;
+

package/lib/range.js

@@ -41,38 +41,35 @@
 	* end `number` the values end at this number (excluded)
 	* step `number` (default: 1) the value of the increment
 */
-module.exports = function( start , end , step ) {
+function range( start , end , step , inclusive = false ) {
+	if ( ! start === undefined ) { return [] ; }
+
 	// Fast exit / common path first
-	if ( arguments.length === 1 ) {
-		const length = start ;
+	if ( end === undefined ) {
+		// .range( length ) syntax
+		let length = start ;
+		if ( inclusive ) { length ++ ; }
 		const output = new Array( length ) ;
 		for ( let i = 0 ; i < length ; i ++ ) { output[ i ] = i ; }
 		return output ;
 	}
 
-	if ( ! arguments.length ) { return [] ; }
-
-	if ( ! step ) {
-		step = start <= end ? 1 : - 1 ;
-	}
-
-	const length = Math.ceil( ( end - start ) / step ) ;
-
-	if ( length <= 0 ) { return [] ; }
+	if ( ! step ) { step = start <= end ? 1 : - 1 ; }
 
+	let length = Math.ceil( ( end - start ) / step ) ;
+	if ( inclusive && start + step * length === end ) { length ++ ; }
 	const output = new Array( length ) ;
 
-	if ( step > 0 ) {
-		for ( let i = 0 , v = start ; v < end ; i ++ , v += step ) {
-			output[ i ] = v ;
-		}
-	}
-	else {
-		for ( let i = 0 , v = start ; v > end ; i ++ , v += step ) {
-			output[ i ] = v ;
-		}
+	// This is better than incrementing the value with the step.
+	// Arguments start, end and step could be float, so it avoids (some) float precision loss.
+	for ( let i = 0 ; i < length ; i ++ ) {
+		output[ i ] = start + i * step ;
 	}
 
 	return output ;
-} ;
+}
+
+module.exports = range ;
+
+range.inclusive = ( start , end , step ) => range( start , end , step , true ) ;
 

package/lib/sum.js

@@ -0,0 +1,109 @@
+/*
+	Array Kit
+
+	Copyright (c) 2014 - 2020 Cédric Ronvel
+
+	The MIT License (MIT)
+
+	Permission is hereby granted, free of charge, to any person obtaining a copy
+	of this software and associated documentation files (the "Software"), to deal
+	in the Software without restriction, including without limitation the rights
+	to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+	copies of the Software, and to permit persons to whom the Software is
+	furnished to do so, subject to the following conditions:
+
+	The above copyright notice and this permission notice shall be included in all
+	copies or substantial portions of the Software.
+
+	THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+	IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+	FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+	AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+	LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+	OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+	SOFTWARE.
+*/
+
+"use strict" ;
+
+
+
+/*
+	The naive sum, works for arrays of limited size, or array of integers.
+*/
+exports.sum = ( array , start = 0 , end = array.length ) => {
+	let sum = 0 ;
+	for ( let i = start ; i < end ; i ++ ) { sum += array[ i ] ; }
+	return sum ;
+} ;
+
+
+
+/*
+	This is the Neumaier algorithm, which compensate lost of precision of summing a lot of floats.
+*/
+exports.floatSum = ( array , start = 0 , end = array.length ) => {
+	let sum = 0 ;
+	let errorSum = 0 ;
+
+	for ( let i = start ; i < end ; i ++ ) {
+		const value = array[ i ] ;
+		const nextSum = sum + value ;
+
+		// This is the tricky and sensible part, do not alter it, the order / priority of operation matters.
+		// It reverses the summation to get the error.
+		// Since errors are tiny, and we sum only tiny numbers here, we ensure good precision for the error sum.
+		if ( Math.abs( sum ) >= Math.abs( value ) ) {
+			errorSum += ( sum - nextSum ) + value ;
+		}
+		else {
+			errorSum += ( value - nextSum ) + sum ;
+		}
+
+		sum = nextSum ;
+	}
+
+	// The cumulated errors are added at the end
+	return sum + errorSum ;
+} ;
+
+
+
+/*
+	This compute the sum chunk by chunk, avoiding summing numbers that are too big with numbers that are too small.
+	The sum of sums itself can be computed recursively (but coded by iteration) if the sub-sums count is also greater
+	than the chunkSize.
+
+	It should be theorically better then floatSum() for very large arrays, but it's hard to test it.
+*/
+exports.chunkedFloatSum = ( array , maxChunkSize = 1024 , start = 0 , end = array.length ) => {
+	let currentArray = array ;
+	let currentStart = start ;
+	let currentEnd = end ;
+
+	while ( currentEnd - currentStart >= maxChunkSize ) {
+		const chunkCount = Math.ceil( ( currentEnd - currentStart ) / maxChunkSize ) ;
+		const chunkSize = Math.ceil( ( currentEnd - currentStart ) / chunkCount ) ;
+		const sumArray = new Array( chunkCount ) ;
+
+		for ( let chunkIndex = 0 ; chunkIndex < chunkCount ; chunkIndex ++ ) {
+			sumArray[ chunkIndex ] = exports.floatSum(
+				currentArray ,
+				currentStart + chunkIndex * chunkSize ,
+				Math.min( currentStart + ( chunkIndex + 1 ) * chunkSize , currentEnd )
+			) ;
+		}
+
+		currentArray = sumArray ;
+		currentStart = 0 ;
+		currentEnd = currentArray.length ;
+	}
+
+	return exports.floatSum( currentArray , currentStart , currentEnd ) ;
+} ;
+
+
+
+exports.mean = ( array , start = 0 , end = array.length ) => exports.sum( array , start , end ) / ( end - start ) ;
+exports.floatMean = ( array , start = 0 , end = array.length ) => exports.floatSum( array , start , end ) / ( end - start ) ;
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "array-kit",
-  "version": "0.2.8",
+  "version": "0.2.9",
   "description": "An array manipulation toolbox.",
   "main": "lib/array-kit.js",
   "directories": {