removing .toLowerCase calls on attribs
[mootools/dkf.git] / Docs / Native / Array.md
blob23be3eac9089a2da5e5d0cccec5541b4d250580e
1 Native: Array {#Array}
2 ======================
4 A collection of Array methods.
6 ### See Also:
8 - [MDC Array][]
11 Array Method: each {#Array:each}
12 ---------------------------------
14 Calls a function for each element in the array.
16 ### Syntax:
18         myArray.each(fn[, bind]);
20 ### Arguments:
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][].
25 #### Argument: fn
27 ##### Syntax
29         fn(item, index, array)
31 ##### Arguments:
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.
37 ### Examples:
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.
45 ### See Also:
47 - [MDC Array:forEach][]
49 ### Notes:
51 - This method is only available for browsers without native [MDC Array:forEach][] support.
55 Array Method: every {#Array:every}
56 ----------------------------------
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.
61 ### Syntax:
63         var allPassed = myArray.every(fn[, bind]);
65 ### Arguments:
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][].
70 #### Argument: fn
72 ##### Syntax:
74         fn(item, index, array)
76 ##### Arguments:
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.
82 ### Returns:
84 * (*boolean*) If every element in the array satisfies the provided testing function, returns true. Otherwise, returns false.
86 ### Examples:
88         var areAllBigEnough = [10, 4, 25, 100].every(function(item, index){
89                 return item > 20;
90         }); //areAllBigEnough = false
93 ### See Also:
95 - [MDC Array:every][]
99 Array Method: filter {#Array:filter}
100 ------------------------------------
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.
105 ### Syntax:
107         var filteredArray = myArray.filter(fn[, bind]);
109 ### Arguments:
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][].
114 #### Argument: fn
116 ##### Syntax:
118         fn(item, index, array)
120 ##### Arguments:
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.
126 ### Returns:
128 * (*array*) The new filtered array.
130 ### Examples:
132         var biggerThanTwenty = [10, 3, 25, 100].filter(function(item, index){
133                 return item > 20;
134         }); //biggerThanTwenty = [25, 100]
136 ### See Also:
138 - [MDC Array:filter][]
141 Array Method: clean {#Array:clean}
142 ------------------------------------
144 Creates a new array with all of the elements of the array which are defined (i.e. not null or undefined).
146 ### Syntax:
148         var cleanedArray = myArray.clean();
150 ### Returns:
152 * (*array*) The new filtered array.
154 ### Examples:
156         var myArray = [null, 1, 0, true, false, "foo", undefined, ""];
157         myArray.clean() // returns [1, 0, true, false, "foo", ""]
160 Array Method: indexOf {#Array:indexOf}
161 --------------------------------------
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.
166 ### Syntax:
168         var index = myArray.indexOf(item[, from]);
170 ### Returns:
172 * (*number*) The index of the first element within the array equal to the specified value. If not found, returns -1.
174 ### Arguments:
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.
179 ### Examples:
181         ['apple', 'lemon', 'banana'].indexOf('lemon'); //returns 1
182         ['apple', 'lemon'].indexOf('banana'); //returns -1
184 ### See Also:
186 - [MDC Array:indexOf][]
190 Array Method: map {#Array:map}
191 ------------------------------
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.
196 ### Syntax:
198         var mappedArray = myArray.map(fn[, bind]);
200 ### Arguments:
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][].
205 #### Argument: fn
207 ##### Syntax:
209         fn(item, index, array)
211 ##### Arguments:
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.
217 ### Returns:
219 * (*array*) The new mapped array.
221 ### Examples:
223         var timesTwo = [1, 2, 3].map(function(item, index){
224                 return item * 2;
225         }); //timesTwo = [2, 4, 6];
227 ### See Also:
229 - [MDC Array:map][]
233 Array Method: some {#Array:some}
234 --------------------------------
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.
239 ### Syntax:
241         var somePassed = myArray.some(fn[, bind]);
243 ### Returns:
245 * (*boolean*) If at least one element in the array satisfies the provided testing function returns true. Otherwise, returns false.
247 ### Arguments:
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][].
252 #### Argument: fn
254 ##### Syntax:
256         fn(item, index, array)
258 ##### Arguments:
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.
264 ### Examples:
266         var isAnyBigEnough = [10, 4, 25, 100].some(function(item, index){
267                 return item > 20;
268         }); //isAnyBigEnough = true
270 ### See Also:
272 - [MDC Array:some][]
276 Array Method: associate {#Array:associate}
277 ------------------------------------------
279 Creates an object with key-value pairs based on the array of keywords passed in and the current content of the array.
281 ### Syntax:
283         var associated = myArray.associate(obj);
285 ### Arguments:
287 1. obj - (*array*) Its items will be used as the keys of the object that will be created.
289 ### Returns:
291 * (*object*) The new associated object.
293 ### Examples:
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'}
302 Array Method: link {#Array:link}
303 --------------------------------
305 Accepts an object of key / function pairs to assign values.
307 ### Syntax:
309         var result = Array.link(array, object);
311 ### Arguments:
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.
315 ### Returns:
317 * (*object*) The new associated object.
319 ### Examples:
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}
328 Array Method: contains {#Array:contains}
329 ----------------------------------------
331 Tests an array for the presence of an item.
333 ### Syntax:
335         var inArray = myArray.contains(item[, from]);
337 ### Arguments:
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.
342 ### Returns:
344 * (*boolean*) If the array contains the item specified, returns true. Otherwise, returns false.
346 ### Examples:
348         ["a","b","c"].contains("a"); //returns true
349         ["a","b","c"].contains("d"); //returns false
351 ### See Also:
353 - [MDC Array:indexOf][]
357 Array Method: extend {#Array:extend}
358 ------------------------------------
360 Extends an array with all the items of another.
362 ### Syntax:
364         myArray.extend(array);
366 ### Arguments:
368 1. array - (*array*) The array whose items should be extended into this array.
370 ### Returns:
372 * (*array*) This array, extended.
374 ### Examples:
376         var animals = ['Cow', 'Pig', 'Dog'];
377         animals.extend(['Cat', 'Dog']); //animals = ['Cow', 'Pig', 'Dog', 'Cat', 'Dog'];
381 Array Method: getLast {#Array:getLast}
382 --------------------------------------
384 Returns the last item from the array.
386 ### Syntax:
388         myArray.getLast();
390 ### Returns:
392 * (*mixed*) The last item in this array.
393 * (*null*) If this array is empty, returns null.
395 ### Examples:
397         ['Cow', 'Pig', 'Dog', 'Cat'].getLast(); //returns 'Cat'
401 Array Method: getRandom {#Array:getRandom}
402 ------------------------------------------
404 Returns a random item from the array.
406 ### Syntax:
408         myArray.getRandom();
410 ### Returns:
412 * (*mixed*) A random item from this array. If this array is empty, returns null.
414 ### Examples:
416         ['Cow', 'Pig', 'Dog', 'Cat'].getRandom(); //returns one of the items
420 Array Method: include {#Array:include}
421 --------------------------------------
423 Pushes the passed element into the array if it's not already present (case and type sensitive).
425 ### Syntax:
427         myArray.include(item);
429 ### Arguments:
431 1. item - (*object*) The item that should be added to this array.
433 ### Returns:
435 * (*array*) This array with the new item included.
437 ### Examples:
439         ['Cow', 'Pig', 'Dog'].include('Cat'); //returns ['Cow', 'Pig', 'Dog', 'Cat']
440         ['Cow', 'Pig', 'Dog'].include('Dog'); //returns ['Cow', 'Pig', 'Dog']
444 Array Method: combine {#Array:combine}
445 ----------------------------------
447 Combines an array with all the items of another. Does not allow duplicates and is case and type sensitive.
449 ### Syntax:
451         myArray.combine(array);
453 ### Arguments:
455 1. array - (*array*) The array whose items should be combined into this array.
457 ### Returns:
459 * (*array*) This array combined with the new items.
461 ### Examples:
463         var animals = ['Cow', 'Pig', 'Dog'];
464         animals.combine(['Cat', 'Dog']); //animals = ['Cow', 'Pig', 'Dog', 'Cat'];
468 Array Method: erase {#Array:erase}
469 ------------------------------------
471 Removes all occurrences of an item from the array.
473 ### Syntax:
475         myArray.erase(item);
477 ### Arguments:
479 1. item - (*object*) The item to search for in the array.
481 ### Returns:
483 * (*array*) This array with all occurrences of the item removed.
485 ### Examples:
487         ['Cow', 'Pig', 'Dog', 'Cat', 'Dog'].erase('Dog') //returns ['Cow', 'Pig', 'Cat']
488         ['Cow', 'Pig', 'Dog'].erase('Cat') //returns ['Cow', 'Pig', 'Dog']
492 Array Method: empty {#Array:empty}
493 ----------------------------------
495 Empties an array.
497 ### Syntax:
499         myArray.empty();
501 ### Returns:
503 * (*array*) This array, emptied.
505 ### Examples:
507         var myArray = ['old', 'data'];
508         myArray.empty(); //myArray is now []
511 Array Method: flatten {#Array:flatten}
512 --------------------------------------
514 Flattens a multidimensional array into a single array.
516 ### Syntax:
518         myArray.flatten();
520 ### Returns:
522 * (*array*) A new flat array.
524 ### Examples:
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]
531 Array Method: hexToRgb {#Array:hexToRgb}
532 ----------------------------------------
534 Converts an hexidecimal color value to RGB. Input array must be the following hexidecimal color format.
535 \['FF','FF','FF'\]
537 ### Syntax:
539         myArray.hexToRgb([array]);
541 ### Arguments:
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)").
545 ### Returns:
547 * (*string*) A string representing the color in RGB.
548 * (*array*) If the array flag is set, an array will be returned instead.
550 ### Examples:
552         ['11','22','33'].hexToRgb(); //returns "rgb(17,34,51)"
553         ['11','22','33'].hexToRgb(true); //returns [17, 34, 51]
555 ### See Also:
557 - [String:hexToRgb](/Native/String/#hexToRgb)
561 Array Method: rgbToHex {#Array:rgbToHex}
562 ----------------------------------------
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\]
567 ### Syntax:
569         myArray.rgbToHex([array]);
571 ### Arguments:
573 1. array - (*boolean*, optional) If true is passed, will output an array (eg. \['ff','33','00'\]) instead of a string (eg. "#ff3300").
575 ### Returns:
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.
580 ### Examples:
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"
586 ### See Also:
588 - [String:rgbToHex](/Native/String/#rgbToHex)
590 Utility Functions {#Utility}
591 ============================
594 Function: $A {#A}
595 -----------------
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.
599 ### Syntax:
601         var copiedArray = $A(iterable);
603 ### Arguments:
605 1. iterable - (array) The iterable to copy.
607 ### Returns:
609 * (*array*) The new copied array.
611 ### Examples:
613 #### Apply Array to arguments:
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".
622 #### Copy an Array:
624         var anArray = [0, 1, 2, 3, 4];
625         var copiedArray = $A(anArray); //Returns [0, 1, 2, 3, 4].
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