All now using SafeRange to cut down on duplicated code

Author: photonstorm

src/utils/array/CountAllMatching.js

@@ -4,6 +4,8 @@
  * @license      {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
  */
 
+var SafeRange = require('./SafeRange');
+
 /**
  * Returns the total number of elements in the array which have a property matching the given value.
  *
@@ -13,20 +15,28 @@
  * @param {array} array - The array to search.
  * @param {string} property - The property to test on each array element.
  * @param {*} value - The value to test the property against. Must pass a strict (`===`) comparison check.
+ * @param {integer} [startIndex] - An optional start index to search from.
+ * @param {integer} [endIndex] - An optional end index to search to.
  *
  * @return {integer} The total number of elements with properties matching the given value.
  */
-var CountAllMatching = function (array, property, value)
+var CountAllMatching = function (array, property, value, startIndex, endIndex)
 {
+    if (startIndex === undefined) { startIndex = 0; }
+    if (endIndex === undefined) { endIndex = array.length; }
+
     var total = 0;
 
-    for (var i = 0; i < array.length; i++)
+    if (SafeRange(array, startIndex, endIndex))
     {
-        var child = array[i];
-
-        if (child[property] === value)
+        for (var i = startIndex; i < endIndex; i++)
         {
-            total++;
+            var child = array[i];
+
+            if (child[property] === value)
+            {
+                total++;
+            }
         }
     }
 

src/utils/array/EachInRange.js

@@ -4,6 +4,8 @@
  * @license      {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
  */
 
+var SafeRange = require('./SafeRange');
+
 /**
  * Passes each element in the array, between the start and end indexes, to the given callback.
  *
@@ -21,34 +23,25 @@
  */
 var EachInRange = function (array, callback, context, startIndex, endIndex)
 {
-    var len = array.length;
-
     if (startIndex === undefined) { startIndex = 0; }
-    if (endIndex === undefined) { endIndex = len; }
-
-    if (endIndex > len)
-    {
-        endIndex = len;
-    }
+    if (endIndex === undefined) { endIndex = array.length; }
 
-    if (startIndex < 0 || startIndex > len || startIndex >= endIndex)
+    if (SafeRange(array, startIndex, endIndex))
     {
-        throw new Error('Range Error: Values outside acceptable range');
-    }
+        var i;
+        var args = [ null ];
 
-    var i;
-    var args = [ null ];
+        for (i = 5; i < arguments.length; i++)
+        {
+            args.push(arguments[i]);
+        }
 
-    for (i = 5; i < arguments.length; i++)
-    {
-        args.push(arguments[i]);
-    }
-
-    for (i = startIndex; i < endIndex; i++)
-    {
-        args[0] = array[i];
+        for (i = startIndex; i < endIndex; i++)
+        {
+            args[0] = array[i];
 
-        callback.apply(context, args);
+            callback.apply(context, args);
+        }
     }
 
     return array;

src/utils/array/GetAll.js

@@ -4,16 +4,18 @@
  * @license      {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
  */
 
+var SafeRange = require('./SafeRange');
+
 /**
  * Returns all elements in the array.
  *
  * You can optionally specify a matching criteria using the `property` and `value` arguments.
  *
- * For example: `getAll('visible', true)` would return only children that have their visible property set.
+ * For example: `getAll('visible', true)` would return only elements that have their visible property set.
  *
- * Optionally you can specify a start and end index. For example if this List had 100 children,
+ * Optionally you can specify a start and end index. For example if the array had 100 elements,
  * and you set `startIndex` to 0 and `endIndex` to 50, it would return matches from only
- * the first 50 children in the List.
+ * the first 50 elements.
  *
  * @function Phaser.Utils.Array.GetAll
  * @since 3.4.0
@@ -33,15 +35,18 @@ var GetAll = function (array, property, value, startIndex, endIndex)
 
     var output = [];
 
-    for (var i = startIndex; i < endIndex; i++)
+    if (SafeRange(array, startIndex, endIndex))
     {
-        var child = array[i];
-
-        if (!property ||
-            (property && value === undefined && child.hasOwnProperty(property)) ||
-            (property && value !== undefined && child[property] === value))
+        for (var i = startIndex; i < endIndex; i++)
         {
-            output.push(child);
+            var child = array[i];
+
+            if (!property ||
+                (property && value === undefined && child.hasOwnProperty(property)) ||
+                (property && value !== undefined && child[property] === value))
+            {
+                output.push(child);
+            }
         }
     }
 

src/utils/array/GetFirst.js

@@ -4,36 +4,50 @@
  * @license      {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
  */
 
+var SafeRange = require('./SafeRange');
+
 /**
- * Returns the first element from the array which optionally has a property matching the given value.
+ * Returns the first element in the array.
+ *
+ * You can optionally specify a matching criteria using the `property` and `value` arguments.
+ *
+ * For example: `getAll('visible', true)` would return the first element that had its `visible` property set.
  *
- * @function Phaser.Utils.Array.GetFirstElement
+ * Optionally you can specify a start and end index. For example if the array had 100 elements,
+ * and you set `startIndex` to 0 and `endIndex` to 50, it would search only the first 50 elements.
+ *
+ * @function Phaser.Utils.Array.GetFirst
  * @since 3.4.0
  *
  * @param {array} array - The array to search.
- * @param {string} property - The property to test on each array element.
- * @param {*} value - The value to test the property against. Must pass a strict (`===`) comparison check.
+ * @param {string} [property] - The property to test on each array element.
+ * @param {*} [value] - The value to test the property against. Must pass a strict (`===`) comparison check.
  * @param {integer} [startIndex=0] - An optional start index to search from.
  * @param {integer} [endIndex=array.length] - An optional end index to search up to (but not included)
  *
  * @return {object} The first matching element from the array, or `null` if no element could be found in the range given.
  */
-var GetFirstElement = function (array, property, value, startIndex, endIndex)
+var GetFirst = function (array, property, value, startIndex, endIndex)
 {
     if (startIndex === undefined) { startIndex = 0; }
     if (endIndex === undefined) { endIndex = array.length; }
 
-    for (var i = startIndex; i < endIndex; i++)
+    if (SafeRange(array, startIndex, endIndex))
     {
-        var child = array[i];
-
-        if (!property || child[property] === value)
+        for (var i = startIndex; i < endIndex; i++)
         {
-            return child;
+            var child = array[i];
+
+            if (!property ||
+                (property && value === undefined && child.hasOwnProperty(property)) ||
+                (property && value !== undefined && child[property] === value))
+            {
+                return child;
+            }
         }
     }
 
     return null;
 };
 
-module.exports = GetFirstElement;
+module.exports = GetFirst;

src/utils/array/GetRandom.js

@@ -7,7 +7,7 @@
 /**
  * Returns a Random element from the array.
  *
- * @function Phaser.Utils.Array.GetRandomElement
+ * @function Phaser.Utils.Array.GetRandom
  * @since 3.0.0
  *
  * @param {array} array - The array to select the random entry from.
@@ -16,7 +16,7 @@
  *
  * @return {object} A random element from the array, or `null` if no element could be found in the range given.
  */
-var GetRandomElement = function (array, startIndex, length)
+var GetRandom = function (array, startIndex, length)
 {
     if (startIndex === undefined) { startIndex = 0; }
     if (length === undefined) { length = array.length; }
@@ -26,4 +26,4 @@ var GetRandomElement = function (array, startIndex, length)
     return (array[randomIndex] === undefined) ? null : array[randomIndex];
 };
 
-module.exports = GetRandomElement;
+module.exports = GetRandom;

src/utils/array/RemoveBetween.js

@@ -4,6 +4,8 @@
  * @license      {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
  */
 
+var SafeRange = require('./SafeRange');
+
 /**
  * Removes the item within the given range in the array.
  * 
@@ -24,38 +26,32 @@
  */
 var RemoveBetween = function (array, startIndex, endIndex, callback, context)
 {
-    if (context === undefined) { context = array; }
-
-    var len = array.length;
-
     if (startIndex === undefined) { startIndex = 0; }
-    if (endIndex === undefined) { endIndex = len; }
+    if (endIndex === undefined) { endIndex = array.length; }
+    if (context === undefined) { context = array; }
 
-    if (endIndex > len)
+    if (SafeRange(array, startIndex, endIndex))
     {
-        endIndex = len;
-    }
+        var size = endIndex - startIndex;
 
-    if (startIndex < 0 || startIndex > len || startIndex >= endIndex)
-    {
-        throw new Error('Range Error: Values outside acceptable range');
-    }
+        var removed = array.splice(startIndex, size);
 
-    var size = endIndex - startIndex;
-
-    var removed = array.splice(startIndex, size);
-
-    if (callback)
-    {
-        for (var i = 0; i < removed.length; i++)
+        if (callback)
         {
-            var entry = removed[i];
+            for (var i = 0; i < removed.length; i++)
+            {
+                var entry = removed[i];
 
-            callback.call(context, entry);
+                callback.call(context, entry);
+            }
         }
-    }
 
-    return removed;
+        return removed;
+    }
+    else
+    {
+        return [];
+    }
 };
 
 module.exports = RemoveBetween;

src/utils/array/Replace.js

@@ -15,7 +15,7 @@
  * @param {*} oldChild - The element in the array that will be replaced.
  * @param {*} newChild - The element to be inserted into the array at the position of `oldChild`.
  *
- * @return {*} Returns the oldChild that was replaced.
+ * @return {boolean} Returns true if the oldChild was successfully replaced, otherwise returns false.
  */
 var Replace = function (array, oldChild, newChild)
 {
@@ -25,9 +25,13 @@ var Replace = function (array, oldChild, newChild)
     if (index1 !== -1 && index2 === -1)
     {
         array[index1] = newChild;
-    }
 
-    return oldChild;
+        return true;
+    }
+    else
+    {
+        return false;
+    }
 };
 
 module.exports = Replace;

src/utils/array/SafeRange.js

@@ -0,0 +1,43 @@
+/**
+ * @author       Richard Davey <rich@photonstorm.com>
+ * @copyright    2018 Photon Storm Ltd.
+ * @license      {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
+ */
+
+/**
+ * Tests if the start and end indexes are a safe range for the given array.
+ * 
+ * @function Phaser.Utils.Array.SafeRange
+ * @since 3.4.0
+ *
+ * @param {array} array - The array to check.
+ * @param {integer} startIndex - The start index.
+ * @param {integer} endIndex - The end index.
+ * @param {boolean} [throwError=true] - Throw an error if the range is out of bounds.
+ *
+ * @return {boolean} True if the range is safe, otherwise false.
+ */
+var SafeRange = function (array, startIndex, endIndex, throwError)
+{
+    var len = array.length;
+
+    if (startIndex < 0 ||
+        startIndex > len ||
+        startIndex >= endIndex ||
+        endIndex > len ||
+        startIndex + endIndex > len)
+    {
+        if (throwError)
+        {
+            throw new Error('Range Error: Values outside acceptable range');
+        }
+
+        return false;
+    }
+    else
+    {
+        return true;
+    }
+};
+
+module.exports = SafeRange;