Docs/Native/Array.md

   1 Native: Array {#Array}
   2 ======================
   3
   4 A collection of Array methods.
   5
   6 ### See Also:
   7
   8 - [MDC Array][]
   9
  10
  11 Array Method: each {#Array:each}
  12 ---------------------------------
  13
  14 Calls a function for each element in the array.
  15
  16 ### Syntax:
  17
  18         myArray.each(fn[, bind]);
  19
  20 ### Arguments:
  21
  22 1. fn   - (*function*) The function which should be executed on each item in the array. This function is passed the item and its index in the array.
  23 2. bind - (*object*, optional) The object to be used as 'this' in the function. For more information see [Function:bind][].
  24
  25 #### Argument: fn
  26
  27 ##### Syntax
  28
  29         fn(item, index, array)
  30
  31 ##### Arguments:
  32
  33 1. item   - (*mixed*) The current item in the array.
  34 2. index  - (*number*) The current item's index in the array.
  35 3. array  - (*array*) The actual array.
  36
  37 ### Examples:
  38
  39         //Alerts "0 = apple", "1 = banana", and so on:
  40         ['apple', 'banana', 'lemon'].each(function(item, index){
  41                 alert(index + " = " + item);
  42         }); //The optional second argument for binding isn't used here.
  43
  44
  45 ### See Also:
  46
  47 - [MDC Array:forEach][]
  48
  49 ### Notes:
  50
  51 - This method is only available for browsers without native [MDC Array:forEach][] support.
  52
  53
  54
  55 Array Method: every {#Array:every}
  56 ----------------------------------
  57
  58 Returns true if every element in the array satisfies the provided testing function.
  59 This method is provided only for browsers without native [Array:every][] support.
  60
  61 ### Syntax:
  62
  63         var allPassed = myArray.every(fn[, bind]);
  64
  65 ### Arguments:
  66
  67 1. fn   - (*function*) The function to test for each element.
  68 2. bind - (*object*, optional) The object to use as 'this' in the function. For more information see [Function:bind][].
  69
  70 #### Argument: fn
  71
  72 ##### Syntax:
  73
  74         fn(item, index, array)
  75
  76 ##### Arguments:
  77
  78 1. item   - (*mixed*) The current item in the array.
  79 2. index  - (*number*) The current item's index in the array.
  80 3. array  - (*array*) The actual array.
  81
  82 ### Returns:
  83
  84 * (*boolean*) If every element in the array satisfies the provided testing function, returns true. Otherwise, returns false.
  85
  86 ### Examples:
  87
  88         var areAllBigEnough = [10, 4, 25, 100].every(function(item, index){
  89                 return item > 20;
  90         }); //areAllBigEnough = false
  91
  92
  93 ### See Also:
  94
  95 - [MDC Array:every][]
  96
  97
  98
  99 Array Method: filter {#Array:filter}
 100 ------------------------------------
 101
 102 Creates a new array with all of the elements of the array for which the provided filtering function returns true.
 103 This method is provided only for browsers without native [Array:filter][] support.
 104
 105 ### Syntax:
 106
 107         var filteredArray = myArray.filter(fn[, bind]);
 108
 109 ### Arguments:
 110
 111 1. fn   - (*function*) The function to test each element of the array. This function is passed the item and its index in the array.
 112 2. bind - (*object*, optional) The object to use as 'this' in the function. For more information see [Function:bind][].
 113
 114 #### Argument: fn
 115
 116 ##### Syntax:
 117
 118         fn(item, index, array)
 119
 120 ##### Arguments:
 121
 122 1. item   - (*mixed*) The current item in the array.
 123 2. index  - (*number*) The current item's index in the array.
 124 3. array  - (*array*) The actual array.
 125
 126 ### Returns:
 127
 128 * (*array*) The new filtered array.
 129
 130 ### Examples:
 131
 132         var biggerThanTwenty = [10, 3, 25, 100].filter(function(item, index){
 133                 return item > 20;
 134         }); //biggerThanTwenty = [25, 100]
 135
 136 ### See Also:
 137
 138 - [MDC Array:filter][]
 139
 140
 141 Array Method: clean {#Array:clean}
 142 ------------------------------------
 143
 144 Creates a new array with all of the elements of the array which are defined (i.e. not null or undefined).
 145
 146 ### Syntax:
 147
 148         var cleanedArray = myArray.clean();
 149
 150 ### Returns:
 151
 152 * (*array*) The new filtered array.
 153
 154 ### Examples:
 155
 156         var myArray = [null, 1, 0, true, false, "foo", undefined, ""];
 157         myArray.clean() // returns [1, 0, true, false, "foo", ""]
 158
 159
 160 Array Method: indexOf {#Array:indexOf}
 161 --------------------------------------
 162
 163 Returns the index of the first element within the array equal to the specified value, or -1 if the value is not found.
 164 This method is provided only for browsers without native [Array:indexOf][] support.
 165
 166 ### Syntax:
 167
 168         var index = myArray.indexOf(item[, from]);
 169
 170 ### Returns:
 171
 172 * (*number*) The index of the first element within the array equal to the specified value. If not found, returns -1.
 173
 174 ### Arguments:
 175
 176 1. item - (*object*) The item to search for in the array.
 177 2. from - (*number*, optional: defaults to 0) The index of the array at which to begin the search.
 178
 179 ### Examples:
 180
 181         ['apple', 'lemon', 'banana'].indexOf('lemon'); //returns 1
 182         ['apple', 'lemon'].indexOf('banana'); //returns -1
 183
 184 ### See Also:
 185
 186 - [MDC Array:indexOf][]
 187
 188
 189
 190 Array Method: map {#Array:map}
 191 ------------------------------
 192
 193 Creates a new array with the results of calling a provided function on every element in the array.
 194 This method is provided only for browsers without native [Array:map][] support.
 195
 196 ### Syntax:
 197
 198         var mappedArray = myArray.map(fn[, bind]);
 199
 200 ### Arguments:
 201
 202 1. fn   - (*function*) The function to produce an element of the new Array from an element of the current one.
 203 2. bind - (*object*, optional) The object to use as 'this' in the function. For more information see [Function:bind][].
 204
 205 #### Argument: fn
 206
 207 ##### Syntax:
 208
 209         fn(item, index, array)
 210
 211 ##### Arguments:
 212
 213 1. item   - (*mixed*) The current item in the array.
 214 2. index  - (*number*) The current item's index in the array.
 215 3. array  - (*array*) The actual array.
 216
 217 ### Returns:
 218
 219 * (*array*) The new mapped array.
 220
 221 ### Examples:
 222
 223         var timesTwo = [1, 2, 3].map(function(item, index){
 224                 return item * 2;
 225         }); //timesTwo = [2, 4, 6];
 226
 227 ### See Also:
 228
 229 - [MDC Array:map][]
 230
 231
 232
 233 Array Method: some {#Array:some}
 234 --------------------------------
 235
 236 Returns true if at least one element in the array satisfies the provided testing function.
 237 This method is provided only for browsers without native [Array:some][] support.
 238
 239 ### Syntax:
 240
 241         var somePassed = myArray.some(fn[, bind]);
 242
 243 ### Returns:
 244
 245 * (*boolean*) If at least one element in the array satisfies the provided testing function returns true. Otherwise, returns false.
 246
 247 ### Arguments:
 248
 249 1. fn   - (*function*) The function to test for each element. This function is passed the item and its index in the array.
 250 2. bind - (*object*, optional) The object to use as 'this' in the function. For more information see [Function:bind][].
 251
 252 #### Argument: fn
 253
 254 ##### Syntax:
 255
 256         fn(item, index, array)
 257
 258 ##### Arguments:
 259
 260 1. item   - (*mixed*) The current item in the array.
 261 2. index  - (*number*) The current item's index in the array.
 262 3. array  - (*array*) The actual array.
 263
 264 ### Examples:
 265
 266         var isAnyBigEnough = [10, 4, 25, 100].some(function(item, index){
 267                 return item > 20;
 268         }); //isAnyBigEnough = true
 269
 270 ### See Also:
 271
 272 - [MDC Array:some][]
 273
 274
 275
 276 Array Method: associate {#Array:associate}
 277 ------------------------------------------
 278
 279 Creates an object with key-value pairs based on the array of keywords passed in and the current content of the array.
 280
 281 ### Syntax:
 282
 283         var associated = myArray.associate(obj);
 284
 285 ### Arguments:
 286
 287 1. obj - (*array*) Its items will be used as the keys of the object that will be created.
 288
 289 ### Returns:
 290
 291 * (*object*) The new associated object.
 292
 293 ### Examples:
 294
 295         var animals = ['Cow', 'Pig', 'Dog', 'Cat'];
 296         var sounds = ['Moo', 'Oink', 'Woof', 'Miao'];
 297         sounds.associate(animals);
 298         //returns {'Cow': 'Moo', 'Pig': 'Oink', 'Dog': 'Woof', 'Cat': 'Miao'}
 299
 300
 301
 302 Array Method: link {#Array:link}
 303 --------------------------------
 304
 305 Accepts an object of key / function pairs to assign values.
 306
 307 ### Syntax:
 308
 309         var result = Array.link(array, object);
 310
 311 ### Arguments:
 312
 313 1. object - (*object*)  An object containing key / function pairs must be passed to be used as a template for associating values with the different keys.
 314
 315 ### Returns:
 316
 317 * (*object*) The new associated object.
 318
 319 ### Examples:
 320
 321         var el = document.createElement('div');
 322         var arr2 = [100, 'Hello', {foo: 'bar'}, el, false];
 323         arr2.link({myNumber: Number.type, myElement: Element.type, myObject: Object.type, myString: String.type, myBoolean: $defined});
 324         //returns {myNumber: 100, myElement: el, myObject: {foo: 'bar'}, myString: 'Hello', myBoolean: false}
 325
 326
 327
 328 Array Method: contains {#Array:contains}
 329 ----------------------------------------
 330
 331 Tests an array for the presence of an item.
 332
 333 ### Syntax:
 334
 335         var inArray = myArray.contains(item[, from]);
 336
 337 ### Arguments:
 338
 339 1. item - (*object*) The item to search for in the array.
 340 2. from - (*number*, optional: defaults to 0) The index of the array at which to begin the search.
 341
 342 ### Returns:
 343
 344 * (*boolean*) If the array contains the item specified, returns true. Otherwise, returns false.
 345
 346 ### Examples:
 347
 348         ["a","b","c"].contains("a"); //returns true
 349         ["a","b","c"].contains("d"); //returns false
 350
 351 ### See Also:
 352
 353 - [MDC Array:indexOf][]
 354
 355
 356
 357 Array Method: extend {#Array:extend}
 358 ------------------------------------
 359
 360 Extends an array with all the items of another.
 361
 362 ### Syntax:
 363
 364         myArray.extend(array);
 365
 366 ### Arguments:
 367
 368 1. array - (*array*) The array whose items should be extended into this array.
 369
 370 ### Returns:
 371
 372 * (*array*) This array, extended.
 373
 374 ### Examples:
 375
 376         var animals = ['Cow', 'Pig', 'Dog'];
 377         animals.extend(['Cat', 'Dog']); //animals = ['Cow', 'Pig', 'Dog', 'Cat', 'Dog'];
 378
 379
 380
 381 Array Method: getLast {#Array:getLast}
 382 --------------------------------------
 383
 384 Returns the last item from the array.
 385
 386 ### Syntax:
 387
 388         myArray.getLast();
 389
 390 ### Returns:
 391
 392 * (*mixed*) The last item in this array.
 393 * (*null*) If this array is empty, returns null.
 394
 395 ### Examples:
 396
 397         ['Cow', 'Pig', 'Dog', 'Cat'].getLast(); //returns 'Cat'
 398
 399
 400
 401 Array Method: getRandom {#Array:getRandom}
 402 ------------------------------------------
 403
 404 Returns a random item from the array.
 405
 406 ### Syntax:
 407
 408         myArray.getRandom();
 409
 410 ### Returns:
 411
 412 * (*mixed*) A random item from this array. If this array is empty, returns null.
 413
 414 ### Examples:
 415
 416         ['Cow', 'Pig', 'Dog', 'Cat'].getRandom(); //returns one of the items
 417
 418
 419
 420 Array Method: include {#Array:include}
 421 --------------------------------------
 422
 423 Pushes the passed element into the array if it's not already present (case and type sensitive).
 424
 425 ### Syntax:
 426
 427         myArray.include(item);
 428
 429 ### Arguments:
 430
 431 1. item - (*object*) The item that should be added to this array.
 432
 433 ### Returns:
 434
 435 * (*array*) This array with the new item included.
 436
 437 ### Examples:
 438
 439         ['Cow', 'Pig', 'Dog'].include('Cat'); //returns ['Cow', 'Pig', 'Dog', 'Cat']
 440         ['Cow', 'Pig', 'Dog'].include('Dog'); //returns ['Cow', 'Pig', 'Dog']
 441
 442
 443
 444 Array Method: combine {#Array:combine}
 445 ----------------------------------
 446
 447 Combines an array with all the items of another. Does not allow duplicates and is case and type sensitive.
 448
 449 ### Syntax:
 450
 451         myArray.combine(array);
 452
 453 ### Arguments:
 454
 455 1. array - (*array*) The array whose items should be combined into this array.
 456
 457 ### Returns:
 458
 459 * (*array*) This array combined with the new items.
 460
 461 ### Examples:
 462
 463         var animals = ['Cow', 'Pig', 'Dog'];
 464         animals.combine(['Cat', 'Dog']); //animals = ['Cow', 'Pig', 'Dog', 'Cat'];
 465
 466
 467
 468 Array Method: erase {#Array:erase}
 469 ------------------------------------
 470
 471 Removes all occurrences of an item from the array.
 472
 473 ### Syntax:
 474
 475         myArray.erase(item);
 476
 477 ### Arguments:
 478
 479 1. item - (*object*) The item to search for in the array.
 480
 481 ### Returns:
 482
 483 * (*array*) This array with all occurrences of the item removed.
 484
 485 ### Examples:
 486
 487         ['Cow', 'Pig', 'Dog', 'Cat', 'Dog'].erase('Dog') //returns ['Cow', 'Pig', 'Cat']
 488         ['Cow', 'Pig', 'Dog'].erase('Cat') //returns ['Cow', 'Pig', 'Dog']
 489
 490
 491
 492 Array Method: empty {#Array:empty}
 493 ----------------------------------
 494
 495 Empties an array.
 496
 497 ### Syntax:
 498
 499         myArray.empty();
 500
 501 ### Returns:
 502
 503 * (*array*) This array, emptied.
 504
 505 ### Examples:
 506
 507         var myArray = ['old', 'data'];
 508         myArray.empty(); //myArray is now []
 509
 510
 511 Array Method: flatten {#Array:flatten}
 512 --------------------------------------
 513
 514 Flattens a multidimensional array into a single array.
 515
 516 ### Syntax:
 517
 518         myArray.flatten();
 519
 520 ### Returns:
 521
 522 * (*array*) A new flat array.
 523
 524 ### Examples:
 525
 526         var myArray = [1,2,3,[4,5, [6,7]], [[[8]]]];
 527         var newArray = myArray.flatten(); //newArray is [1,2,3,4,5,6,7,8]
 528
 529
 530
 531 Array Method: hexToRgb {#Array:hexToRgb}
 532 ----------------------------------------
 533
 534 Converts an hexidecimal color value to RGB. Input array must be the following hexidecimal color format.
 535 \['FF','FF','FF'\]
 536
 537 ### Syntax:
 538
 539         myArray.hexToRgb([array]);
 540
 541 ### Arguments:
 542
 543 1. array - (*boolean*, optional) If true is passed, will output an array (eg. \[255, 51, 0\]) instead of a string (eg. "rgb(255,51,0)").
 544
 545 ### Returns:
 546
 547 * (*string*) A string representing the color in RGB.
 548 * (*array*) If the array flag is set, an array will be returned instead.
 549
 550 ### Examples:
 551
 552         ['11','22','33'].hexToRgb(); //returns "rgb(17,34,51)"
 553         ['11','22','33'].hexToRgb(true); //returns [17, 34, 51]
 554
 555 ### See Also:
 556
 557 - [String:hexToRgb](/Native/String/#hexToRgb)
 558
 559
 560
 561 Array Method: rgbToHex {#Array:rgbToHex}
 562 ----------------------------------------
 563
 564 Converts an RGB color value to hexidecimal. Input array must be in one of the following RGB color formats.
 565 \[255,255,255\], or \[255,255,255,1\]
 566
 567 ### Syntax:
 568
 569         myArray.rgbToHex([array]);
 570
 571 ### Arguments:
 572
 573 1. array - (*boolean*, optional) If true is passed, will output an array (eg. \['ff','33','00'\]) instead of a string (eg. "#ff3300").
 574
 575 ### Returns:
 576
 577 * (*string*) A string representing the color in hexadecimal, or 'transparent' string if the fourth value of rgba in the input array is 0 (rgba).
 578 * (*array*) If the array flag is set, an array will be returned instead.
 579
 580 ### Examples:
 581
 582         [17,34,51].rgbToHex(); //returns "#112233"
 583         [17,34,51].rgbToHex(true); //returns ['11','22','33']
 584         [17,34,51,0].rgbToHex(); //returns "transparent"
 585
 586 ### See Also:
 587
 588 - [String:rgbToHex](/Native/String/#rgbToHex)
 589
 590 Utility Functions {#Utility}
 591 ============================
 592
 593
 594 Function: $A {#A}
 595 -----------------
 596
 597 Creates a copy of an Array. Useful for applying the Array prototypes to iterable objects such as a DOM Node collection or the arguments object.
 598
 599 ### Syntax:
 600
 601         var copiedArray = $A(iterable);
 602
 603 ### Arguments:
 604
 605 1. iterable - (array) The iterable to copy.
 606
 607 ### Returns:
 608
 609 * (*array*) The new copied array.
 610
 611 ### Examples:
 612
 613 #### Apply Array to arguments:
 614
 615         function myFunction(){
 616                 $A(arguments).each(function(argument, index){
 617                         alert(argument);
 618                 });
 619         };
 620         myFunction("One", "Two", "Three"); //Alerts "One", then "Two", then "Three".
 621
 622 #### Copy an Array:
 623
 624         var anArray = [0, 1, 2, 3, 4];
 625         var copiedArray = $A(anArray); //Returns [0, 1, 2, 3, 4].
 626
 627
 628 [Array]: /core/Native/Array
 629 [Function:bind]: /core/Native/Function/#Function:bind
 630 [MDC Array]: http://developer.mozilla.org/en/docs/Core_JavaScript_1.5_Reference:Global_Objects:Array
 631 [MDC Array:every]: http://developer.mozilla.org/en/docs/Core_JavaScript_1.5_Reference:Global_Objects:Array:every
 632 [MDC Array:filter]: http://developer.mozilla.org/en/docs/Core_JavaScript_1.5_Reference:Global_Objects:Array:filter
 633 [MDC Array:indexOf]: http://developer.mozilla.org/en/docs/Core_JavaScript_1.5_Reference:Global_Objects:Array:indexOf
 634 [MDC Array:map]: http://developer.mozilla.org/en/docs/Core_JavaScript_1.5_Reference:Global_Objects:Array:map
 635 [MDC Array:some]: http://developer.mozilla.org/en/docs/Core_JavaScript_1.5_Reference:Global_Objects:Array:some
 636 [MDC Array:forEach]: http://developer.mozilla.org/en/docs/Core_JavaScript_1.5_Reference:Global_Objects:Array:forEach
 637 [Array:every]: http://developer.mozilla.org/en/docs/Core_JavaScript_1.5_Reference:Global_Objects:Array:every
 638 [Array:filter]: http://developer.mozilla.org/en/docs/Core_JavaScript_1.5_Reference:Global_Objects:Array:filter
 639 [Array:indexOf]: http://developer.mozilla.org/en/docs/Core_JavaScript_1.5_Reference:Global_Objects:Array:indexOf
 640 [Array:map]: http://developer.mozilla.org/en/docs/Core_JavaScript_1.5_Reference:Global_Objects:Array:map
 641 [Array:some]: http://developer.mozilla.org/en/docs/Core_JavaScript_1.5_Reference:Global_Objects:Array:some