jssource/src_files/include/javascript/yui3/build/collection/arraylist.js

   1 /*
   2 Copyright (c) 2010, Yahoo! Inc. All rights reserved.
   3 Code licensed under the BSD License:
   4 http://developer.yahoo.com/yui/license.html
   5 version: 3.3.0
   6 build: 3167
   7 */
   8 YUI.add('arraylist', function(Y) {
   9
  10 /**
  11  * Collection utilities beyond what is provided in the YUI core
  12  * @module collection
  13  * @submodule arraylist
  14  */
  15
  16 var YArray      = Y.Array,
  17     YArray_each = YArray.each,
  18     ArrayListProto;
  19
  20 /**
  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.
  27  *
  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.
  31  *
  32  * @class ArrayList
  33  * @constructor
  34  * @param items { Array } array of items this list will be responsible for
  35  */
  36 function ArrayList( items ) {
  37     if ( items !== undefined ) {
  38         this._items = Y.Lang.isArray( items ) ? items : YArray( items );
  39     } else {
  40         // ||= to support lazy initialization from augment
  41         this._items = this._items || [];
  42     }
  43 }
  44
  45 ArrayListProto = {
  46     /**
  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.
  51      *
  52      * @method item
  53      * @param i { Integer } index to fetch
  54      * @return { mixed } the item at the requested index
  55      */
  56     item: function ( i ) {
  57         return this._items[i];
  58     },
  59
  60     /**
  61      * <p>Execute a function on each item of the list, optionally providing a
  62      * custom execution context.  Default context is the item.</p>
  63      *
  64      * <p>The callback signature is <code>callback( item, index )</code>.</p>
  65      *
  66      * @method each
  67      * @param fn { Function } the function to execute
  68      * @param context { mixed } optional override 'this' in the function
  69      * @return { ArrayList } this instance
  70      * @chainable
  71      */
  72     each: function ( fn, context ) {
  73         YArray_each( this._items, function ( item, i ) {
  74             item = this.item( i );
  75
  76             fn.call( context || item, item, i, this );
  77         }, this);
  78
  79         return this;
  80     },
  81
  82     /**
  83      * <p>Execute a function on each item of the list, optionally providing a
  84      * custom execution context.  Default context is the item.</p>
  85      *
  86      * <p>The callback signature is <code>callback( item, index )</code>.</p>
  87      *
  88      * <p>Unlike <code>each</code>, if the callback returns true, the
  89      * iteratation will stop.</p>
  90      *
  91      * @method some
  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
  95      */
  96     some: function ( fn, context ) {
  97         return YArray.some( this._items, function ( item, i ) {
  98             item = this.item( i );
  99
 100             return fn.call( context || item, item, i, this );
 101         }, this);
 102     },
 103
 104     /**
 105      * Finds the first index of the needle in the managed array of items.
 106      *
 107      * @method indexOf
 108      * @param needle { mixed } The item to search for
 109      * @return { Integer } Array index if found.  Otherwise -1
 110      */
 111     indexOf: function ( needle ) {
 112         return YArray.indexOf( this._items, needle );
 113     },
 114
 115     /**
 116      * How many items are in this list?
 117      *
 118      * @method size
 119      * @return { Integer } Number of items in the list
 120      */
 121     size: function () {
 122         return this._items.length;
 123     },
 124
 125     /**
 126      * Is this instance managing any items?
 127      *
 128      * @method isEmpty
 129      * @return { Boolean } true if 1 or more items are being managed
 130      */
 131     isEmpty: function () {
 132         return !this.size();
 133     },
 134
 135     /**
 136      * Provides an array-like representation for JSON.stringify.
 137      *
 138      * @method toJSON
 139      * @return { Array } an array representation of the ArrayList
 140      */
 141     toJSON: function () {
 142         return this._items;
 143     }
 144 };
 145 // Default implementation does not distinguish between public and private
 146 // item getter
 147 /**
 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>.
 151  *
 152  * @method _item
 153  * @protected
 154  * @param i { Integer } Index of item to fetch
 155  * @return { mixed } The item appropriate for pass through API methods
 156  */
 157 ArrayListProto._item = ArrayListProto.item;
 158
 159 ArrayList.prototype  = ArrayListProto;
 160
 161 Y.mix( ArrayList, {
 162
 163     /**
 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
 167      * instances.</p>
 168      *
 169      * <p>Accepts a single string name or an array of string names.</p>
 170      *
 171      * <pre><code>list.each( function ( item ) {
 172      *     item.methodName( 1, 2, 3 );
 173      * } );
 174      * // becomes
 175      * list.methodName( 1, 2, 3 );</code></pre>
 176      *
 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>
 180      *
 181      * @method addMethod
 182      * @static
 183      * @param dest { Object } Object or prototype to receive the iterator method
 184      * @param name { String | Array } Name of method of methods to create
 185      */
 186     addMethod: function ( dest, names ) {
 187
 188         names = YArray( names );
 189
 190         YArray_each( names, function ( name ) {
 191             dest[ name ] = function () {
 192                 var args = YArray( arguments, 0, true ),
 193                     ret  = [];
 194
 195                 YArray_each( this._items, function ( item, i ) {
 196                     item = this._item( i );
 197
 198                     var result = item[ name ].apply( item, args );
 199
 200                     if ( result !== undefined && result !== item ) {
 201                         ret.push( result );
 202                     }
 203                 }, this);
 204
 205                 return ret.length ? ret : this;
 206             };
 207         } );
 208     }
 209 } );
 210
 211 Y.ArrayList = ArrayList;
 212
 213
 214 }, '3.3.0' );