[Summary view] [Print] [Text view]

   1  /*
   2  YUI 3.17.2 (build 9c3c78e)
   3  Copyright 2014 Yahoo! Inc. All rights reserved.
   4  Licensed under the BSD License.
   5  http://yuilibrary.com/license/
   6  */
   7  
   8  YUI.add('arraylist', function (Y, NAME) {
   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       * iteration 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  // Mixed onto existing proto to preserve constructor NOT being an own property.
 160  // This has bitten me when composing classes by enumerating, copying prototypes.
 161  Y.mix(ArrayList.prototype, ArrayListProto);
 162  
 163  Y.mix( ArrayList, {
 164  
 165      /**
 166       * <p>Adds a pass through method to dest (typically the prototype of a list
 167       * class) that calls the named method on each item in the list with
 168       * whatever parameters are passed in.  Allows for API indirection via list
 169       * instances.</p>
 170       *
 171       * <p>Accepts a single string name or an array of string names.</p>
 172       *
 173       * <pre><code>list.each( function ( item ) {
 174       *     item.methodName( 1, 2, 3 );
 175       * } );
 176       * // becomes
 177       * list.methodName( 1, 2, 3 );</code></pre>
 178       *
 179       * <p>Additionally, the pass through methods use the item retrieved by the
 180       * <code>_item</code> method in case there is any special behavior that is
 181       * appropriate for API mirroring.</p>
 182       *
 183       * <p>If the iterated method returns a value, the return value from the
 184       * added method will be an array of values with each value being at the
 185       * corresponding index for that item.  If the iterated method does not
 186       * return a value, the added method will be chainable.
 187       *
 188       * @method addMethod
 189       * @static
 190       * @param dest {Object} Object or prototype to receive the iterator method
 191       * @param name {String|String[]} Name of method of methods to create
 192       */
 193      addMethod: function ( dest, names ) {
 194  
 195          names = YArray( names );
 196  
 197          YArray_each( names, function ( name ) {
 198              dest[ name ] = function () {
 199                  var args = YArray( arguments, 0, true ),
 200                      ret  = [];
 201  
 202                  YArray_each( this._items, function ( item, i ) {
 203                      item = this._item( i );
 204  
 205                      var result = item[ name ].apply( item, args );
 206  
 207                      if ( result !== undefined && result !== item ) {
 208                          ret[i] = result;
 209                      }
 210                  }, this);
 211  
 212                  return ret.length ? ret : this;
 213              };
 214          } );
 215      }
 216  } );
 217  
 218  Y.ArrayList = ArrayList;
 219  
 220  
 221  }, '3.17.2', {"requires": ["yui-base"]});