Docs/Types/Array.md

   1 Type: Array {#Array}
   2 ====================
   3
   4 A collection of Array methods and functions.
   5
   6 ### See Also:
   7
   8 - [MDC Array][]
   9
  10
  11 Function: Array.each {#Array:Array-each}
  12 ----------------------------------
  13
  14 Used to iterate through arrays, or iterables that are not regular arrays, such as built in getElementsByTagName calls or arguments of a function.
  15
  16 ### Syntax:
  17
  18         Array.each(iterable, fn[, bind]);
  19
  20 ### Arguments:
  21
  22 1. iterable - (*array*) The array to iterate through.
  23 2. fn       - (*function*) The function to test for each element.
  24 3. bind     - (*object*, optional) The object to use as 'this' within the function. For more information see [Function:bind][].
  25
  26 #### Argument: fn
  27
  28 ##### Syntax:
  29
  30         fn(item, index, object)
  31
  32 ##### Arguments:
  33
  34 1. item   - (*mixed*) The current item in the array.
  35 2. index  - (*number*) The current item's index in the array. In the case of an object, it is passed the key of that item rather than the index.
  36 3. object - (*mixed*) The actual array/object.
  37
  38 ### Example:
  39
  40         Array.each(['Sun', 'Mon', 'Tue'], function(day, index){
  41                 alert('name:' + day + ', index: ' + index);
  42         }); // alerts 'name: Sun, index: 0', 'name: Mon, index: 1', etc.
  43
  44 ### See Also:
  45
  46 - [Array:each](#Array:each)
  47
  48 ### Notes:
  49
  50 This is an array-specific equivalent of *$each* from MooTools 1.2.
  51
  52
  53
  54 Function: Array.clone {#Array:Array-clone}
  55 ------------------------------------
  56
  57 Returns a copy of the passed array.
  58
  59 ### Syntax:
  60
  61         var clone = Array.clone(myArray);
  62
  63 ### Arguments:
  64
  65 1. myArray      - (*array*) The array you wish to copy.
  66
  67 ### Returns:
  68
  69 * (*array*) a copy of the passed array.
  70
  71 ### Example:
  72
  73         var myArray = ['red', 'blue', 'green'];
  74         var otherArray = Array.clone(myArray);
  75
  76         var myArray[0] = 'yellow';
  77
  78         alert(myArray[0]);              // alerts 'yellow'
  79         alert(otherArray[0])    // alerts 'red'
  80
  81 ### Notes:
  82
  83 This is an array-specific equivalent of *$unlink* from MooTools 1.2.
  84
  85
  86
  87 Function: Array.from {#Array:Array-from}
  88 ----------------------------------
  89
  90 Converts the argument passed in to an array if it is defined and not already an array.
  91
  92 ### Syntax:
  93
  94         var splatted = Array.from(obj);
  95
  96 ### Arguments:
  97
  98 1. obj - (*mixed*) Any type of variable.
  99
 100 ### Returns:
 101
 102 * (*array*) If the variable passed in is an array, returns the array. Otherwise, returns an array with the only element being the variable passed in.
 103
 104 ### Example:
 105
 106         Array.from('hello'); // returns ['hello'].
 107         Array.from(['a', 'b', 'c']); // returns ['a', 'b', 'c'].
 108
 109 ### Notes:
 110
 111 This is equivalent to *$splat* from MooTools 1.2.
 112
 113
 114
 115 Array method: each {#Array:each}
 116 ---------------------------------
 117
 118 Calls a function for each element in the array.
 119
 120 ### Syntax:
 121
 122         myArray.each(fn[, bind]);
 123
 124 ### Arguments:
 125
 126 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.
 127 2. bind - (*object*, optional) The object to be used as 'this' in the function. For more information see [Function:bind][].
 128
 129 #### Argument: fn
 130
 131 ##### Syntax
 132
 133         fn(item, index, array)
 134
 135 ##### Arguments:
 136
 137 1. item   - (*mixed*) The current item in the array.
 138 2. index  - (*number*) The current item's index in the array.
 139 3. array  - (*array*) The actual array.
 140
 141 ### Examples:
 142
 143         //Alerts "0 = apple", "1 = banana", and so on:
 144         ['apple', 'banana', 'lemon'].each(function(item, index){
 145                 alert(index + " = " + item);
 146         }); //The optional second argument for binding isn't used here.
 147
 148
 149 ### See Also:
 150
 151 - [Array.each](#Array:Array-each)
 152 - [MDC Array:forEach][]
 153
 154 ### Notes:
 155
 156 - This method is only available for browsers without native [MDC Array:forEach][] support.
 157
 158
 159
 160
 161
 162
 163 Array method: invoke {#Array:invoke}
 164 --------------------------
 165
 166 Returns an array with the named method applied to the array's contents.
 167
 168 ### Syntax:
 169
 170         var arr = myArray.invoke(method[, arg, arg, arg ...])
 171
 172 ### Arguments:
 173
 174 1. method - (*string*) The method to apply to each item in the array.
 175 2. arg - (*mixed*) Any number of arguments to pass to the named method.
 176
 177 ### Returns:
 178
 179 * (*array*) A new array containing the results of the applied method.
 180
 181 ### Example:
 182
 183         var foo = [4, 8, 15, 16, 23, 42];
 184         var bar = foo.invoke('limit', 10, 30);  //bar is now [10, 10, 15, 16, 23, 30]
 185
 186 ### Notes:
 187
 188 The method that is invoked is a method of each of the items.
 189 If the method does not exist, then an error will be thrown. For example:
 190
 191         [0, false, 'string'].invoke('limit', 0, 10); // throws an error!
 192
 193 Array method: every {#Array:every}
 194 ----------------------------
 195
 196 Returns true if every element in the array satisfies the provided testing function.
 197 This method is provided only for browsers without native [Array:every][] support.
 198
 199 ### Syntax:
 200
 201         var allPassed = myArray.every(fn[, bind]);
 202
 203 ### Arguments:
 204
 205 1. fn   - (*function*) The function to test for each element.
 206 2. bind - (*object*, optional) The object to use as 'this' in the function. For more information see [Function:bind][].
 207
 208 #### Argument: fn
 209
 210 ##### Syntax:
 211
 212         fn(item, index, array)
 213
 214 ##### Arguments:
 215
 216 1. item   - (*mixed*) The current item in the array.
 217 2. index  - (*number*) The current item's index in the array.
 218 3. array  - (*array*) The actual array.
 219
 220 ### Returns:
 221
 222 * (*boolean*) If every element in the array satisfies the provided testing function, returns true. Otherwise, returns false.
 223
 224 ### Examples:
 225
 226         var areAllBigEnough = [10, 4, 25, 100].every(function(item, index){
 227                 return item > 20;
 228         }); // areAllBigEnough = false
 229
 230
 231 ### See Also:
 232
 233 - [MDC Array:every][]
 234
 235
 236
 237 Array method: filter {#Array:filter}
 238 ------------------------------
 239
 240 Creates a new array with all of the elements of the array for which the provided filtering function returns true.
 241 This method is provided only for browsers without native [Array:filter][] support.
 242
 243 ### Syntax:
 244
 245         var filteredArray = myArray.filter(fn[, bind]);
 246
 247 ### Arguments:
 248
 249 1. fn   - (*function*) The function to test each element of the array. 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 ### Returns:
 265
 266 * (*array*) The new filtered array.
 267
 268 ### Examples:
 269
 270         var biggerThanTwenty = [10, 3, 25, 100].filter(function(item, index){
 271                 return item > 20;
 272         }); // biggerThanTwenty = [25, 100]
 273
 274 ### See Also:
 275
 276 - [MDC Array:filter][]
 277
 278
 279
 280 Array method: clean {#Array:clean}
 281 ----------------------------
 282
 283 Creates a new array with all of the elements of the array which are defined (i.e. not null or undefined).
 284
 285 ### Syntax:
 286
 287         var cleanedArray = myArray.clean();
 288
 289 ### Returns:
 290
 291 * (*array*) The new filtered array.
 292
 293 ### Examples:
 294
 295         var myArray = [null, 1, 0, true, false, 'foo', undefined, ''];
 296         myArray.clean() // returns [1, 0, true, false, 'foo', '']
 297
 298
 299
 300 Array method: indexOf {#Array:indexOf}
 301 --------------------------------
 302
 303 Returns the index of the first element within the array equal to the specified value, or -1 if the value is not found.
 304 This method is provided only for browsers without native [Array:indexOf][] support.
 305
 306 ### Syntax:
 307
 308         var index = myArray.indexOf(item[, from]);
 309
 310 ### Returns:
 311
 312 * (*number*) The index of the first element within the array equal to the specified value. If not found, returns -1.
 313
 314 ### Arguments:
 315
 316 1. item - (*object*) The item to search for in the array.
 317 2. from - (*number*, optional: defaults to 0) The index of the array at which to begin the search.
 318
 319 ### Examples:
 320
 321         ['apple', 'lemon', 'banana'].indexOf('lemon'); // returns 1
 322         ['apple', 'lemon'].indexOf('banana'); // returns -1
 323
 324 ### See Also:
 325
 326 - [MDC Array:indexOf][]
 327
 328
 329
 330 Array method: map {#Array:map}
 331 ------------------------
 332
 333 Creates a new array with the results of calling a provided function on every element in the array.
 334 This method is provided only for browsers without native [Array:map][] support.
 335
 336 ### Syntax:
 337
 338         var mappedArray = myArray.map(fn[, bind]);
 339
 340 ### Arguments:
 341
 342 1. fn   - (*function*) The function to produce an element of the new Array from an element of the current one.
 343 2. bind - (*object*, optional) The object to use as 'this' in the function. For more information see [Function:bind][].
 344
 345 #### Argument: fn
 346
 347 ##### Syntax:
 348
 349         fn(item, index, array)
 350
 351 ##### Arguments:
 352
 353 1. item   - (*mixed*) The current item in the array.
 354 2. index  - (*number*) The current item's index in the array.
 355 3. array  - (*array*) The actual array.
 356
 357 ### Returns:
 358
 359 * (*array*) The new mapped array.
 360
 361 ### Examples:
 362
 363         var timesTwo = [1, 2, 3].map(function(item, index){
 364                 return item * 2;
 365         }); //timesTwo = [2, 4, 6];
 366
 367 ### See Also:
 368
 369 - [MDC Array:map][]
 370
 371
 372
 373 Array method: some {#Array:some}
 374 --------------------------
 375
 376 Returns true if at least one element in the array satisfies the provided testing function.
 377 This method is provided only for browsers without native [Array:some][] support.
 378
 379 ### Syntax:
 380
 381         var somePassed = myArray.some(fn[, bind]);
 382
 383 ### Returns:
 384
 385 * (*boolean*) If at least one element in the array satisfies the provided testing function returns true. Otherwise, returns false.
 386
 387 ### Arguments:
 388
 389 1. fn   - (*function*) The function to test for each element. This function is passed the item and its index in the array.
 390 2. bind - (*object*, optional) The object to use as 'this' in the function. For more information see [Function:bind][].
 391
 392 #### Argument: fn
 393
 394 ##### Syntax:
 395
 396         fn(item, index, array)
 397
 398 ##### Arguments:
 399
 400 1. item   - (*mixed*) The current item in the array.
 401 2. index  - (*number*) The current item's index in the array.
 402 3. array  - (*array*) The actual array.
 403
 404 ### Examples:
 405
 406         var isAnyBigEnough = [10, 4, 25, 100].some(function(item, index){
 407                 return item > 20;
 408         }); // isAnyBigEnough = true
 409
 410 ### See Also:
 411
 412 - [MDC Array:some][]
 413
 414
 415
 416 Array method: associate {#Array:associate}
 417 ------------------------------------
 418
 419 Creates an object with key-value pairs based on the array of keywords passed in and the current content of the array.
 420
 421 ### Syntax:
 422
 423         var associated = myArray.associate(obj);
 424
 425 ### Arguments:
 426
 427 1. obj - (*array*) Its items will be used as the keys of the object that will be created.
 428
 429 ### Returns:
 430
 431 * (*object*) The new associated object.
 432
 433 ### Examples:
 434
 435         var animals = ['Cow', 'Pig', 'Dog', 'Cat'];
 436         var sounds = ['Moo', 'Oink', 'Woof', 'Miao'];
 437         sounds.associate(animals);
 438         // returns {'Cow': 'Moo', 'Pig': 'Oink', 'Dog': 'Woof', 'Cat': 'Miao'}
 439
 440
 441
 442 Array method: link {#Array:link}
 443 --------------------------
 444
 445 Accepts an object of key / function pairs to assign values.
 446
 447 ### Syntax:
 448
 449         var result = myArray.link(object);
 450
 451 ### Arguments:
 452
 453 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.
 454
 455 ### Returns:
 456
 457 * (*object*) The new associated object.
 458
 459 ### Examples:
 460
 461         var el = document.createElement('div');
 462         var arr2 = [100, 'Hello', {foo: 'bar'}, el, false];
 463         arr2.link({
 464                 myNumber: Type.isNumber,
 465                 myElement: Type.isElement,
 466                 myObject: Type.isObject,
 467                 myString: Type.isString,
 468                 myBoolean: function(obj){ return obj != null; }
 469         });
 470         // returns {myNumber: 100, myElement: el, myObject: {foo: 'bar'}, myString: 'Hello', myBoolean: false}
 471
 472
 473 Array method: contains {#Array:contains}
 474 ----------------------------------
 475
 476 Tests an array for the presence of an item.
 477
 478 ### Syntax:
 479
 480         var inArray = myArray.contains(item[, from]);
 481
 482 ### Arguments:
 483
 484 1. item - (*object*) The item to search for in the array.
 485 2. from - (*number*, optional: defaults to 0) The index of the array at which to begin the search.
 486
 487 ### Returns:
 488
 489 * (*boolean*) If the array contains the item specified, returns true. Otherwise, returns false.
 490
 491 ### Examples:
 492
 493         ['a', 'b', 'c'].contains('a'); // returns true
 494         ['a', 'b', 'c'].contains('d'); // returns false
 495
 496 ### See Also:
 497
 498 - [MDC Array:indexOf][]
 499
 500
 501
 502 Array method: append {#Array:append}
 503 ------------------------------
 504
 505 Appends the passed array to the end of the current array.
 506
 507 ### Syntax:
 508
 509         var myArray = myArray.append(otherArray);
 510
 511 ### Arguments:
 512
 513 1. otherArray - (*array*) The array containing values you wish to append.
 514
 515 ### Returns:
 516
 517 * (*array*) The original array including the new values.
 518
 519 ### Examples:
 520
 521         var myOtherArray = ['green', 'yellow'];
 522         ['red', 'blue'].append(myOtherArray); // returns ['red', 'blue', 'green', 'yellow'];
 523         myOtheArray; // is now ['red', 'blue', 'green', 'yellow'];
 524
 525         [0, 1, 2].append([3, [4]]); // [0, 1, 2, 3, [4]]
 526
 527 ### Notes:
 528
 529 This is an array-specific equivalent of *$extend* from MooTools 1.2.
 530
 531
 532
 533 Array method: getLast {#Array:getLast}
 534 --------------------------------
 535
 536 Returns the last item from the array.
 537
 538 ### Syntax:
 539
 540         myArray.getLast();
 541
 542 ### Returns:
 543
 544 * (*mixed*) The last item in this array.
 545 * (*null*) If this array is empty, returns null.
 546
 547 ### Examples:
 548
 549         ['Cow', 'Pig', 'Dog', 'Cat'].getLast(); // returns 'Cat'
 550
 551
 552
 553 Array method: getRandom {#Array:getRandom}
 554 ------------------------------------
 555
 556 Returns a random item from the array.
 557
 558 ### Syntax:
 559
 560         myArray.getRandom();
 561
 562 ### Returns:
 563
 564 * (*mixed*) A random item from this array. If this array is empty, returns null.
 565
 566 ### Examples:
 567
 568         ['Cow', 'Pig', 'Dog', 'Cat'].getRandom(); // returns one of the items
 569
 570
 571
 572 Array method: include {#Array:include}
 573 --------------------------------
 574
 575 Pushes the passed element into the array if it's not already present (case and type sensitive).
 576
 577 ### Syntax:
 578
 579         myArray.include(item);
 580
 581 ### Arguments:
 582
 583 1. item - (*object*) The item that should be added to this array.
 584
 585 ### Returns:
 586
 587 * (*array*) This array with the new item included.
 588
 589 ### Examples:
 590
 591         ['Cow', 'Pig', 'Dog'].include('Cat'); // returns ['Cow', 'Pig', 'Dog', 'Cat']
 592         ['Cow', 'Pig', 'Dog'].include('Dog'); // returns ['Cow', 'Pig', 'Dog']
 593
 594 ### Notes:
 595
 596 If you want to push the passed element even if it's already present, use
 597 the vanilla javascript:
 598
 599         myArray.push(item);
 600
 601 Array method: combine {#Array:combine}
 602 --------------------------------
 603
 604 Combines an array with all the items of another. Does not allow duplicates and is case and type sensitive.
 605
 606 ### Syntax:
 607
 608         myArray.combine(array);
 609
 610 ### Arguments:
 611
 612 1. array - (*array*) The array whose items should be combined into this array.
 613
 614 ### Returns:
 615
 616 * (*array*) This array combined with the new items.
 617
 618 ### Examples:
 619
 620         var animals = ['Cow', 'Pig', 'Dog'];
 621         animals.combine(['Cat', 'Dog']); //animals = ['Cow', 'Pig', 'Dog', 'Cat'];
 622
 623
 624
 625 Array method: erase {#Array:erase}
 626 ----------------------------
 627
 628 Removes all occurrences of an item from the array.
 629
 630 ### Syntax:
 631
 632         myArray.erase(item);
 633
 634 ### Arguments:
 635
 636 1. item - (*object*) The item to search for in the array.
 637
 638 ### Returns:
 639
 640 * (*array*) This array with all occurrences of the item removed.
 641
 642 ### Examples:
 643
 644         ['Cow', 'Pig', 'Dog', 'Cat', 'Dog'].erase('Dog') // returns ['Cow', 'Pig', 'Cat']
 645         ['Cow', 'Pig', 'Dog'].erase('Cat') // returns ['Cow', 'Pig', 'Dog']
 646
 647
 648
 649 Array method: empty {#Array:empty}
 650 ----------------------------
 651
 652 Empties an array.
 653
 654 ### Syntax:
 655
 656         myArray.empty();
 657
 658 ### Returns:
 659
 660 * (*array*) This array, emptied.
 661
 662 ### Examples:
 663
 664         var myArray = ['old', 'data'];
 665         myArray.empty(); //myArray is now []
 666
 667
 668 Array method: flatten {#Array:flatten}
 669 --------------------------------
 670
 671 Flattens a multidimensional array into a single array.
 672
 673 ### Syntax:
 674
 675         myArray.flatten();
 676
 677 ### Returns:
 678
 679 * (*array*) A new flat array.
 680
 681 ### Examples:
 682
 683         var myArray = [1,2,3,[4,5, [6,7]], [[[8]]]];
 684         var newArray = myArray.flatten(); //newArray is [1,2,3,4,5,6,7,8]
 685
 686
 687
 688 Array method: pick {#Array:pick}
 689 --------------------------
 690 Returns the first defined value of the array passed in, or null.
 691
 692 ### Syntax:
 693
 694         var picked = [var1, var2, var3].pick();
 695
 696 ### Returns:
 697
 698 * (*mixed*) The first variable that is defined.
 699 * (*null*) If all variables passed in are `null` or `undefined`, returns `null`.
 700
 701 ### Example:
 702
 703         function say(infoMessage, errorMessage){
 704                 alert([errorMessage, infoMessage, 'There was no message supplied.'].pick());
 705
 706                 //or more MooTools 1.2 style using Generics
 707                 Array.pick([errorMessage, infoMessage, 'There was no message supplied.']);
 708
 709         }
 710         say(); // alerts 'There was no message supplied.'
 711     say('This is an info message.'); // alerts 'This is an info message.'
 712     say('This message will be ignored.', 'This is the error message.'); // alerts 'This is the error message.'
 713
 714
 715 ### Notes:
 716
 717 This is equivalent to *$pick* from MooTools 1.2.
 718
 719
 720
 721 Array method: hexToRgb {#Array:hexToRgb}
 722 ----------------------------------
 723
 724 Converts an hexadecimal color value to RGB. Input array must be the following hexadecimal color format.
 725 \['FF', 'FF', 'FF'\]
 726
 727 ### Syntax:
 728
 729         myArray.hexToRgb([array]);
 730
 731 ### Arguments:
 732
 733 1. array - (*boolean*, optional) If true is passed, will output an array (e.g. \[255, 51, 0\]) instead of a string (e.g. "rgb(255, 51, 0)").
 734
 735 ### Returns:
 736
 737 * (*string*) A string representing the color in RGB.
 738 * (*array*) If the array flag is set, an array will be returned instead.
 739
 740 ### Examples:
 741
 742         ['11', '22', '33'].hexToRgb(); // returns 'rgb(17, 34, 51)'
 743         ['11', '22', '33'].hexToRgb(true); // returns [17, 34, 51]
 744
 745 ### See Also:
 746
 747 - [String:hexToRgb](/Types/String/#hexToRgb)
 748
 749
 750
 751 Array method: rgbToHex {#Array:rgbToHex}
 752 ----------------------------------
 753
 754 Converts an RGB color value to hexadecimal. Input array must be in one of the following RGB color formats.
 755 \[255, 255, 255\], or \[255, 255, 255, 1\]
 756
 757 ### Syntax:
 758
 759         myArray.rgbToHex([array]);
 760
 761 ### Arguments:
 762
 763 1. array - (*boolean*, optional) If true is passed, will output an array (e.g. \['ff', '33', '00'\]) instead of a string (e.g. '#ff3300').
 764
 765 ### Returns:
 766
 767 * (*string*) A string representing the color in hexadecimal, or 'transparent' string if the fourth value of rgba in the input array is 0 (rgba).
 768 * (*array*) If the array flag is set, an array will be returned instead.
 769
 770 ### Examples:
 771
 772         [17, 34, 51].rgbToHex(); // returns '#112233'
 773         [17, 34, 51].rgbToHex(true); // returns ['11', '22', '33']
 774         [17, 34, 51, 0].rgbToHex(); // returns 'transparent'
 775
 776 ### See Also:
 777
 778 - [String:rgbToHex](/Types/String/#rgbToHex)
 779
 780
 781
 782 [Function:bind]: /core/Native/Function/#Function:bind
 783 [MDC Array]: https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array
 784 [MDC Array:every]: https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/every
 785 [MDC Array:filter]: https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/filter
 786 [MDC Array:indexOf]: https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/indexOf
 787 [MDC Array:map]: https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/map
 788 [MDC Array:some]: https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/some
 789 [MDC Array:forEach]: https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/forEach
 790 [Array:every]: https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/every
 791 [Array:filter]: https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/filter
 792 [Array:indexOf]: https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/indexOf
 793 [Array:map]: https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/map
 794 [Array:some]: https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/some