lib/dojo/_base/array.js.uncompressed.js

   1 define("dojo/_base/array", ["./kernel", "../has", "./lang"], function(dojo, has, lang){
   2         // module:
   3         //              dojo/_base/array
   4         // summary:
   5         //              This module defines the Javascript v1.6 array extensions.
   6
   7         /*=====
   8         dojo.indexOf = function(arr, value, fromIndex, findLast){
   9                 // summary:
  10                 //              locates the first index of the provided value in the
  11                 //              passed array. If the value is not found, -1 is returned.
  12                 // description:
  13                 //              This method corresponds to the JavaScript 1.6 Array.indexOf method, with one difference: when
  14                 //              run over sparse arrays, the Dojo function invokes the callback for every index whereas JavaScript
  15                 //              1.6's indexOf skips the holes in the sparse array.
  16                 //              For details on this method, see:
  17                 //                      https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Objects/Array/indexOf
  18                 // arr: Array
  19                 // value: Object
  20                 // fromIndex: Integer?
  21                 // findLast: Boolean?
  22                 // returns: Number
  23         };
  24         dojo.lastIndexOf = function(arr, value, fromIndex){
  25                 // summary:
  26                 //              locates the last index of the provided value in the passed
  27                 //              array. If the value is not found, -1 is returned.
  28                 // description:
  29                 //              This method corresponds to the JavaScript 1.6 Array.lastIndexOf method, with one difference: when
  30                 //              run over sparse arrays, the Dojo function invokes the callback for every index whereas JavaScript
  31                 //              1.6's lastIndexOf skips the holes in the sparse array.
  32                 //              For details on this method, see:
  33                 //                      https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Objects/Array/lastIndexOf
  34                 //      arr: Array,
  35                 //      value: Object,
  36                 //      fromIndex: Integer?
  37                 //      returns: Number
  38         };
  39         dojo.forEach = function(arr, callback, thisObject){
  40                 //      summary:
  41                 //              for every item in arr, callback is invoked. Return values are ignored.
  42                 //              If you want to break out of the loop, consider using dojo.every() or dojo.some().
  43                 //              forEach does not allow breaking out of the loop over the items in arr.
  44                 //      arr:
  45                 //              the array to iterate over. If a string, operates on individual characters.
  46                 //      callback:
  47                 //              a function is invoked with three arguments: item, index, and array
  48                 //      thisObject:
  49                 //              may be used to scope the call to callback
  50                 //      description:
  51                 //              This function corresponds to the JavaScript 1.6 Array.forEach() method, with one difference: when
  52                 //              run over sparse arrays, this implementation passes the "holes" in the sparse array to
  53                 //              the callback function with a value of undefined. JavaScript 1.6's forEach skips the holes in the sparse array.
  54                 //              For more details, see:
  55                 //                      https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Objects/Array/forEach
  56                 //      example:
  57                 //      | // log out all members of the array:
  58                 //      | dojo.forEach(
  59                 //      |               [ "thinger", "blah", "howdy", 10 ],
  60                 //      |               function(item){
  61                 //      |                       console.log(item);
  62                 //      |               }
  63                 //      | );
  64                 //      example:
  65                 //      | // log out the members and their indexes
  66                 //      | dojo.forEach(
  67                 //      |               [ "thinger", "blah", "howdy", 10 ],
  68                 //      |               function(item, idx, arr){
  69                 //      |                       console.log(item, "at index:", idx);
  70                 //      |               }
  71                 //      | );
  72                 //      example:
  73                 //      | // use a scoped object member as the callback
  74                 //      |
  75                 //      | var obj = {
  76                 //      |               prefix: "logged via obj.callback:",
  77                 //      |               callback: function(item){
  78                 //      |                       console.log(this.prefix, item);
  79                 //      |               }
  80                 //      | };
  81                 //      |
  82                 //      | // specifying the scope function executes the callback in that scope
  83                 //      | dojo.forEach(
  84                 //      |               [ "thinger", "blah", "howdy", 10 ],
  85                 //      |               obj.callback,
  86                 //      |               obj
  87                 //      | );
  88                 //      |
  89                 //      | // alternately, we can accomplish the same thing with dojo.hitch()
  90                 //      | dojo.forEach(
  91                 //      |               [ "thinger", "blah", "howdy", 10 ],
  92                 //      |               dojo.hitch(obj, "callback")
  93                 //      | );
  94                 //      arr: Array|String
  95                 //      callback: Function|String
  96                 //      thisObject: Object?
  97         };
  98         dojo.every = function(arr, callback, thisObject){
  99                 // summary:
 100                 //              Determines whether or not every item in arr satisfies the
 101                 //              condition implemented by callback.
 102                 // arr: Array|String
 103                 //              the array to iterate on. If a string, operates on individual characters.
 104                 // callback: Function|String
 105                 //              a function is invoked with three arguments: item, index,
 106                 //              and array and returns true if the condition is met.
 107                 // thisObject: Object?
 108                 //              may be used to scope the call to callback
 109                 // returns: Boolean
 110                 // description:
 111                 //              This function corresponds to the JavaScript 1.6 Array.every() method, with one difference: when
 112                 //              run over sparse arrays, this implementation passes the "holes" in the sparse array to
 113                 //              the callback function with a value of undefined. JavaScript 1.6's every skips the holes in the sparse array.
 114                 //              For more details, see:
 115                 //                      https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Objects/Array/every
 116                 // example:
 117                 //      | // returns false
 118                 //      | dojo.every([1, 2, 3, 4], function(item){ return item>1; });
 119                 // example:
 120                 //      | // returns true
 121                 //      | dojo.every([1, 2, 3, 4], function(item){ return item>0; });
 122         };
 123         dojo.some = function(arr, callback, thisObject){
 124                 // summary:
 125                 //              Determines whether or not any item in arr satisfies the
 126                 //              condition implemented by callback.
 127                 // arr: Array|String
 128                 //              the array to iterate over. If a string, operates on individual characters.
 129                 // callback: Function|String
 130                 //              a function is invoked with three arguments: item, index,
 131                 //              and array and returns true if the condition is met.
 132                 // thisObject: Object?
 133                 //              may be used to scope the call to callback
 134                 // returns: Boolean
 135                 // description:
 136                 //              This function corresponds to the JavaScript 1.6 Array.some() method, with one difference: when
 137                 //              run over sparse arrays, this implementation passes the "holes" in the sparse array to
 138                 //              the callback function with a value of undefined. JavaScript 1.6's some skips the holes in the sparse array.
 139                 //              For more details, see:
 140                 //                      https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Objects/Array/some
 141                 // example:
 142                 //      | // is true
 143                 //      | dojo.some([1, 2, 3, 4], function(item){ return item>1; });
 144                 // example:
 145                 //      | // is false
 146                 //      | dojo.some([1, 2, 3, 4], function(item){ return item<1; });
 147         };
 148         dojo.map = function(arr, callback, thisObject){
 149                 // summary:
 150                 //              applies callback to each element of arr and returns
 151                 //              an Array with the results
 152                 // arr: Array|String
 153                 //              the array to iterate on. If a string, operates on
 154                 //              individual characters.
 155                 // callback: Function|String
 156                 //              a function is invoked with three arguments, (item, index,
 157                 //              array),  and returns a value
 158                 // thisObject: Object?
 159                 //              may be used to scope the call to callback
 160                 // returns: Array
 161                 // description:
 162                 //              This function corresponds to the JavaScript 1.6 Array.map() method, with one difference: when
 163                 //              run over sparse arrays, this implementation passes the "holes" in the sparse array to
 164                 //              the callback function with a value of undefined. JavaScript 1.6's map skips the holes in the sparse array.
 165                 //              For more details, see:
 166                 //                      https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Objects/Array/map
 167                 // example:
 168                 //      | // returns [2, 3, 4, 5]
 169                 //      | dojo.map([1, 2, 3, 4], function(item){ return item+1 });
 170         };
 171         dojo.filter = function(arr, callback, thisObject){
 172                 // summary:
 173                 //              Returns a new Array with those items from arr that match the
 174                 //              condition implemented by callback.
 175                 // arr: Array
 176                 //              the array to iterate over.
 177                 // callback: Function|String
 178                 //              a function that is invoked with three arguments (item,
 179                 //              index, array). The return of this function is expected to
 180                 //              be a boolean which determines whether the passed-in item
 181                 //              will be included in the returned array.
 182                 // thisObject: Object?
 183                 //              may be used to scope the call to callback
 184                 // returns: Array
 185                 // description:
 186                 //              This function corresponds to the JavaScript 1.6 Array.filter() method, with one difference: when
 187                 //              run over sparse arrays, this implementation passes the "holes" in the sparse array to
 188                 //              the callback function with a value of undefined. JavaScript 1.6's filter skips the holes in the sparse array.
 189                 //              For more details, see:
 190                 //                      https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Objects/Array/filter
 191                 // example:
 192                 //      | // returns [2, 3, 4]
 193                 //      | dojo.filter([1, 2, 3, 4], function(item){ return item>1; });
 194         };
 195         =====*/
 196
 197         // our old simple function builder stuff
 198         var cache = {}, u, array; // the export object
 199
 200         function clearCache(){
 201                 cache = {};
 202         }
 203
 204         function buildFn(fn){
 205                 return cache[fn] = new Function("item", "index", "array", fn); // Function
 206         }
 207         // magic snippet: if(typeof fn == "string") fn = cache[fn] || buildFn(fn);
 208
 209         // every & some
 210
 211         function everyOrSome(some){
 212                 var every = !some;
 213                 return function(a, fn, o){
 214                         var i = 0, l = a && a.length || 0, result;
 215                         if(l && typeof a == "string") a = a.split("");
 216                         if(typeof fn == "string") fn = cache[fn] || buildFn(fn);
 217                         if(o){
 218                                 for(; i < l; ++i){
 219                                         result = !fn.call(o, a[i], i, a);
 220                                         if(some ^ result){
 221                                                 return !result;
 222                                         }
 223                                 }
 224                         }else{
 225                                 for(; i < l; ++i){
 226                                         result = !fn(a[i], i, a);
 227                                         if(some ^ result){
 228                                                 return !result;
 229                                         }
 230                                 }
 231                         }
 232                         return every; // Boolean
 233                 }
 234         }
 235         // var every = everyOrSome(false), some = everyOrSome(true);
 236
 237         // indexOf, lastIndexOf
 238
 239         function index(up){
 240                 var delta = 1, lOver = 0, uOver = 0;
 241                 if(!up){
 242                         delta = lOver = uOver = -1;
 243                 }
 244                 return function(a, x, from, last){
 245                         if(last && delta > 0){
 246                                 // TODO: why do we use a non-standard signature? why do we need "last"?
 247                                 return array.lastIndexOf(a, x, from);
 248                         }
 249                         var l = a && a.length || 0, end = up ? l + uOver : lOver, i;
 250                         if(from === u){
 251                                 i = up ? lOver : l + uOver;
 252                         }else{
 253                                 if(from < 0){
 254                                         i = l + from;
 255                                         if(i < 0){
 256                                                 i = lOver;
 257                                         }
 258                                 }else{
 259                                         i = from >= l ? l + uOver : from;
 260                                 }
 261                         }
 262                         if(l && typeof a == "string") a = a.split("");
 263                         for(; i != end; i += delta){
 264                                 if(a[i] == x){
 265                                         return i; // Number
 266                                 }
 267                         }
 268                         return -1; // Number
 269                 }
 270         }
 271         // var indexOf = index(true), lastIndexOf = index(false);
 272
 273         function forEach(a, fn, o){
 274                 var i = 0, l = a && a.length || 0;
 275                 if(l && typeof a == "string") a = a.split("");
 276                 if(typeof fn == "string") fn = cache[fn] || buildFn(fn);
 277                 if(o){
 278                         for(; i < l; ++i){
 279                                 fn.call(o, a[i], i, a);
 280                         }
 281                 }else{
 282                         for(; i < l; ++i){
 283                                 fn(a[i], i, a);
 284                         }
 285                 }
 286         }
 287
 288         function map(a, fn, o, Ctr){
 289                 // TODO: why do we have a non-standard signature here? do we need "Ctr"?
 290                 var i = 0, l = a && a.length || 0, out = new (Ctr || Array)(l);
 291                 if(l && typeof a == "string") a = a.split("");
 292                 if(typeof fn == "string") fn = cache[fn] || buildFn(fn);
 293                 if(o){
 294                         for(; i < l; ++i){
 295                                 out[i] = fn.call(o, a[i], i, a);
 296                         }
 297                 }else{
 298                         for(; i < l; ++i){
 299                                 out[i] = fn(a[i], i, a);
 300                         }
 301                 }
 302                 return out; // Array
 303         }
 304
 305         function filter(a, fn, o){
 306                 // TODO: do we need "Ctr" here like in map()?
 307                 var i = 0, l = a && a.length || 0, out = [], value;
 308                 if(l && typeof a == "string") a = a.split("");
 309                 if(typeof fn == "string") fn = cache[fn] || buildFn(fn);
 310                 if(o){
 311                         for(; i < l; ++i){
 312                                 value = a[i];
 313                                 if(fn.call(o, value, i, a)){
 314                                         out.push(value);
 315                                 }
 316                         }
 317                 }else{
 318                         for(; i < l; ++i){
 319                                 value = a[i];
 320                                 if(fn(value, i, a)){
 321                                         out.push(value);
 322                                 }
 323                         }
 324                 }
 325                 return out; // Array
 326         }
 327
 328         array = {
 329                 every:       everyOrSome(false),
 330                 some:        everyOrSome(true),
 331                 indexOf:     index(true),
 332                 lastIndexOf: index(false),
 333                 forEach:     forEach,
 334                 map:         map,
 335                 filter:      filter,
 336                 clearCache:  clearCache
 337         };
 338
 339         1 && lang.mixin(dojo, array);
 340
 341         /*===== return dojo.array; =====*/
 342         return array;
 343 });