Reusable Accessible Mapping Platform

API Docs for: 5.3.1
Show:

File: src/js/RAMP/Utils/array.js

  1. /*global define */
  2. /*jshint bitwise: false*/
  3.  
  4. /**
  5. * @module Utils
  6. */
  7.  
  8. /**
  9. * Set of functions that deal with arrays.
  10. *
  11. * ####Imports RAMP Modules:
  12. * {{#crossLink "Util"}}{{/crossLink}}  
  13. * 
  14. * @class Array
  15. * @static
  16. * @uses dojo/_base/array
  17. * @uses dojo/_base/lang
  18. */
  19. define(["dojo/_base/array", "dojo/_base/lang", "utils/util"],
  20.     function (dojoArray, dojoLang, Util) {
  21.         "use strict";
  22.         return {
  23.             /**
  24.             * Returns an array that has only unique values (only the first element is kept).
  25.             *
  26.             * @method unique
  27.             * @static
  28.             * @param {Array} array Array to be searched
  29.             * @return {Array} array that has only unique values
  30.             */
  31.             unique: function (array) {
  32.                 return array.reverse().filter(function (e, i, array) {
  33.                     return array.indexOf(e, i + 1) === -1;
  34.                 }).reverse();
  35.             },
  36.  
  37.             /**
  38.             * Returns the first element in the given array that satisfies the given
  39.             * predicate. Returns null if no element in the given array satisfies
  40.             * the given predicate.
  41.             *
  42.             * #####EXAMPLE
  43.             *     var array = [1, 2, 3, 4]
  44.             *     find(array, function(a_number) { return a_number === 2 }); -> 2
  45.             *     find(array, function(a_number) { return a_number === 5 }); -> null
  46.             *
  47.             *
  48.             * @method find
  49.             * @static
  50.             * @param {Array} arr Array to be searched
  51.             * @param {Function} predicate a function that takes two arguments (element and its index) and returns true if the
  52.             * argument satisfies some condition, and false otherwise.
  53.             * @param {Object} scope ???
  54.             * @return {Object} first element that satisfies the given predicate; `null` if no such element is found
  55.             */
  56.             find: function (arr, predicate, scope) {
  57.                 var index = this.indexOf(arr, predicate, scope);
  58.                 if (index === -1) {
  59.                     return null;
  60.                 } else {
  61.                     return arr[index];
  62.                 }
  63.             },
  64.  
  65.             /**
  66.             * Returns the index of the first element in the given array that satisfies the given
  67.             * predicate. Returns -1 if no element in the given array satisfies the predicate.
  68.             *
  69.             *
  70.             * @method indexOf
  71.             * @static
  72.             * @param {Array} arr Array to be searched
  73.             * @param {Function} predicate a function that takes two arguments (element and its index) and returns true if the
  74.             * argument satisfies some condition, and false otherwise.
  75.             * @param {Object} scope ???
  76.             * @return {Number} index of the first element that satisfied the predicate; `-1` if no such element is found
  77.             */
  78.             indexOf: function (arr, predicate, scope) {
  79.                 if (typeof scope !== 'undefined') {
  80.                     predicate = dojoLang.hitch(scope, predicate);
  81.                 }
  82.                 var i;
  83.                 for (i = 0; i < arr.length; i++) {
  84.                     if (predicate(arr[i], i)) {
  85.                         return i;
  86.                     }
  87.                 }
  88.                 return -1;
  89.             },
  90.  
  91.             /**
  92.             * Given a function which takes one argument and returns 1, 0, or -1, returns the first element
  93.             * which causes the given function to return 0.
  94.             *
  95.             * @method binaryIndexOf
  96.             * @static
  97.             * @param {Array} arr Array to be searched
  98.             * @param {Function} compareFcn ???
  99.             * @return {Number} the index of the element that causes the given function to return 0, returns -1 if no such element exists
  100.             */
  101.             binaryIndexOf: function (arr, compareFcn) {
  102.                 var minIndex = 0,
  103.                     maxIndex = arr.length - 1,
  104.                     currentIndex,
  105.                     currentElement;
  106.  
  107.                 while (minIndex <= maxIndex) {
  108.                     currentIndex = (minIndex + maxIndex) / 2 | 0;
  109.                     currentElement = arr[currentIndex];
  110.  
  111.                     if (compareFcn(currentElement) < 0) {
  112.                         minIndex = currentIndex + 1;
  113.                     } else if (compareFcn(currentElement) > 0) {
  114.                         maxIndex = currentIndex - 1;
  115.                     } else {
  116.                         return currentIndex;
  117.                     }
  118.                 }
  119.  
  120.                 return -1;
  121.             },
  122.  
  123.             /**
  124.             * Given a function which takes one argument and returns 1, 0, or -1, returns the first element
  125.             * which causes the given function to return 0.
  126.             *
  127.             * @method binaryFind
  128.             * @static
  129.             * @param {Array} arr Array to be searched
  130.             * @param {Function} compareFcn ???
  131.             * @return {Number} the index of the element that causes the given function to return 0, returns -1 if no such element exists</returns>
  132.             */
  133.             binaryFind: function (arr, compareFcn) {
  134.                 var index = this.binaryIndexOf(arr, compareFcn);
  135.                 return arr[index];
  136.             },
  137.  
  138.             /**
  139.             * Removes an item from the specified array.
  140.             *
  141.             * @method remove
  142.             * @static
  143.             * @param {Array} array Array to have the item removed from
  144.             * @param {Number|String|Object} obj can be either an index of the item to be removed, a String to be removed from the array of strings, or an actual Object to be removed; if obj is an Object, you need to provide a predicate function
  145.             * @param {Function} [predicate] a function that takes one argument and returns true if the argument satisfies some condition, and false otherwise.
  146.             */
  147.             remove: function (array, obj, predicate) {
  148.                 var index;
  149.  
  150.                 if (!Util.isNumber(obj)) {
  151.                     if (predicate) {
  152.                         index = this.indexOf(array, predicate);
  153.                     } else {
  154.                         index = array.indexOf(obj);
  155.                     }
  156.                 } else {
  157.                     index = obj;
  158.                 }
  159.  
  160.                 if (index !== -1) {
  161.                     array.splice(index, 1);
  162.                 }
  163.             }
  164.         };
  165.     });
  166.