xpcom/ds/nsIArrayExtensions.idl

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #include "nsIArray.idl"
   7
   8 /**
   9  * Helper interface for allowing scripts to treat nsIArray instances as if
  10  * they were nsISupportsArray instances while iterating.
  11  *
  12  * nsISupportsArray is convenient to iterate over in JavaScript:
  13  *
  14  * for (let i = 0; i < array.Count(); ++i) {
  15  *   let elem = array.GetElementAt(i);
  16  *   ...
  17  * }
  18  *
  19  * but doing the same with nsIArray is somewhat less convenient, since
  20  * queryElementAt is not nearly so nice to use from JavaScript.  So we provide
  21  * this extension interface so interfaces that currently return
  22  * nsISupportsArray can start returning nsIArrayExtensions and all JavaScript
  23  * should Just Work. Eventually we'll roll this interface into nsIArray
  24  * itself, possibly getting rid of the Count() method, as it duplicates
  25  * nsIArray functionality.
  26  */
  27 [scriptable, builtinclass, uuid(261d442e-050c-453d-8aaa-b3f23bcc528b)]
  28 interface nsIArrayExtensions : nsIArray
  29 {
  30   /**
  31    * Count()
  32    *
  33    * Retrieves the length of the array. This is an alias for the
  34    * |nsIArray.length| attribute.
  35    */
  36   uint32_t Count();
  37
  38   /**
  39    * GetElementAt()
  40    *
  41    * Retrieve a specific element of the array. null is a valid result for
  42    * this method.
  43    *
  44    * Note: If the index is out of bounds null will be returned.
  45    *       This differs from the behavior of nsIArray.queryElementAt() which
  46    *       will throw if an invalid index is specified.
  47    *
  48    * @param index position of element
  49    */
  50   nsISupports GetElementAt(in uint32_t index);
  51 };