2 Copyright (c) 2010, Yahoo! Inc. All rights reserved.
3 Code licensed under the BSD License:
4 http://developer.yahoo.com/yui/license.html
8 YUI.add('arraylist', function(Y) {
11 * Collection utilities beyond what is provided in the YUI core
13 * @submodule arraylist
17 YArray_each = YArray.each,
21 * Generic ArrayList class for managing lists of items and iterating operations
22 * over them. The targeted use for this class is for augmentation onto a
23 * class that is responsible for managing multiple instances of another class
24 * (e.g. NodeList for Nodes). The recommended use is to augment your class with
25 * ArrayList, then use ArrayList.addMethod to mirror the API of the constituent
26 * items on the list's API.
28 * The default implementation creates immutable lists, but mutability can be
29 * provided via the arraylist-add submodule or by implementing mutation methods
30 * directly on the augmented class's prototype.
34 * @param items { Array } array of items this list will be responsible for
36 function ArrayList( items ) {
37 if ( items !== undefined ) {
38 this._items = Y.Lang.isArray( items ) ? items : YArray( items );
40 // ||= to support lazy initialization from augment
41 this._items = this._items || [];
47 * Get an item by index from the list. Override this method if managing a
48 * list of objects that have a different public representation (e.g. Node
49 * instances vs DOM nodes). The iteration methods that accept a user
50 * function will use this method for access list items for operation.
53 * @param i { Integer } index to fetch
54 * @return { mixed } the item at the requested index
56 item: function ( i ) {
57 return this._items[i];
61 * <p>Execute a function on each item of the list, optionally providing a
62 * custom execution context. Default context is the item.</p>
64 * <p>The callback signature is <code>callback( item, index )</code>.</p>
67 * @param fn { Function } the function to execute
68 * @param context { mixed } optional override 'this' in the function
69 * @return { ArrayList } this instance
72 each: function ( fn, context ) {
73 YArray_each( this._items, function ( item, i ) {
74 item = this.item( i );
76 fn.call( context || item, item, i, this );
83 * <p>Execute a function on each item of the list, optionally providing a
84 * custom execution context. Default context is the item.</p>
86 * <p>The callback signature is <code>callback( item, index )</code>.</p>
88 * <p>Unlike <code>each</code>, if the callback returns true, the
89 * iteratation will stop.</p>
92 * @param fn { Function } the function to execute
93 * @param context { mixed } optional override 'this' in the function
94 * @return { Boolean } True if the function returned true on an item
96 some: function ( fn, context ) {
97 return YArray.some( this._items, function ( item, i ) {
98 item = this.item( i );
100 return fn.call( context || item, item, i, this );
105 * Finds the first index of the needle in the managed array of items.
108 * @param needle { mixed } The item to search for
109 * @return { Integer } Array index if found. Otherwise -1
111 indexOf: function ( needle ) {
112 return YArray.indexOf( this._items, needle );
116 * How many items are in this list?
119 * @return { Integer } Number of items in the list
122 return this._items.length;
126 * Is this instance managing any items?
129 * @return { Boolean } true if 1 or more items are being managed
131 isEmpty: function () {
136 * Provides an array-like representation for JSON.stringify.
139 * @return { Array } an array representation of the ArrayList
141 toJSON: function () {
145 // Default implementation does not distinguish between public and private
148 * Protected method for optimizations that may be appropriate for API
149 * mirroring. Similar in functionality to <code>item</code>, but is used by
150 * methods added with <code>ArrayList.addMethod()</code>.
154 * @param i { Integer } Index of item to fetch
155 * @return { mixed } The item appropriate for pass through API methods
157 ArrayListProto._item = ArrayListProto.item;
159 ArrayList.prototype = ArrayListProto;
164 * <p>Adds a pass through method to dest (typically the prototype of a list
165 * class) that calls the named method on each item in the list with
166 * whatever parameters are passed in. Allows for API indirection via list
169 * <p>Accepts a single string name or an array of string names.</p>
171 * <pre><code>list.each( function ( item ) {
172 * item.methodName( 1, 2, 3 );
175 * list.methodName( 1, 2, 3 );</code></pre>
177 * <p>Additionally, the pass through methods use the item retrieved by the
178 * <code>_item</code> method in case there is any special behavior that is
179 * appropriate for API mirroring.</p>
183 * @param dest { Object } Object or prototype to receive the iterator method
184 * @param name { String | Array } Name of method of methods to create
186 addMethod: function ( dest, names ) {
188 names = YArray( names );
190 YArray_each( names, function ( name ) {
191 dest[ name ] = function () {
192 var args = YArray( arguments, 0, true ),
195 YArray_each( this._items, function ( item, i ) {
196 item = this._item( i );
198 var result = item[ name ].apply( item, args );
200 if ( result !== undefined && result !== item ) {
205 return ret.length ? ret : this;
211 Y.ArrayList = ArrayList;