xpcom/ds/nsIArray.idl@6474c204b198 (annotated)
xpcom/ds/nsIArray.idl
Wed, 31 Dec 2014 06:09:35 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Wed, 31 Dec 2014 06:09:35 +0100
- changeset 0
- 6474c204b198
- permissions
- -rw-r--r--
Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.
| michael@0 | 1 | /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ |
| michael@0 | 2 | /* This Source Code Form is subject to the terms of the Mozilla Public |
| michael@0 | 3 | * License, v. 2.0. If a copy of the MPL was not distributed with this |
| michael@0 | 4 | * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ |
| michael@0 | 5 | |
| michael@0 | 6 | #include "nsISupports.idl" |
| michael@0 | 7 | |
| michael@0 | 8 | interface nsISimpleEnumerator; |
| michael@0 | 9 | |
| michael@0 | 10 | /** |
| michael@0 | 11 | * nsIArray |
| michael@0 | 12 | * |
| michael@0 | 13 | * An indexed collection of elements. Provides basic functionality for |
| michael@0 | 14 | * retrieving elements at a specific position, searching for |
| michael@0 | 15 | * elements. Indexes are zero-based, such that the last element in the |
| michael@0 | 16 | * array is stored at the index length-1. |
| michael@0 | 17 | * |
| michael@0 | 18 | * For an array which can be modified, see nsIMutableArray below. |
| michael@0 | 19 | * |
| michael@0 | 20 | * Neither interface makes any attempt to protect the individual |
| michael@0 | 21 | * elements from modification. The convention is that the elements of |
| michael@0 | 22 | * the array should not be modified. Documentation within a specific |
| michael@0 | 23 | * interface should describe variations from this convention. |
| michael@0 | 24 | * |
| michael@0 | 25 | * It is also convention that if an interface provides access to an |
| michael@0 | 26 | * nsIArray, that the array should not be QueryInterfaced to an |
| michael@0 | 27 | * nsIMutableArray for modification. If the interface in question had |
| michael@0 | 28 | * intended the array to be modified, it would have returned an |
| michael@0 | 29 | * nsIMutableArray! |
| michael@0 | 30 | * |
| michael@0 | 31 | * null is a valid entry in the array, and as such any nsISupports |
| michael@0 | 32 | * parameters may be null, except where noted. |
| michael@0 | 33 | */ |
| michael@0 | 34 | [scriptable, uuid(114744d9-c369-456e-b55a-52fe52880d2d)] |
| michael@0 | 35 | interface nsIArray : nsISupports |
| michael@0 | 36 | { |
| michael@0 | 37 | /** |
| michael@0 | 38 | * length |
| michael@0 | 39 | * |
| michael@0 | 40 | * number of elements in the array. |
| michael@0 | 41 | */ |
| michael@0 | 42 | readonly attribute unsigned long length; |
| michael@0 | 43 | |
| michael@0 | 44 | /** |
| michael@0 | 45 | * queryElementAt() |
| michael@0 | 46 | * |
| michael@0 | 47 | * Retrieve a specific element of the array, and QueryInterface it |
| michael@0 | 48 | * to the specified interface. null is a valid result for |
| michael@0 | 49 | * this method, but exceptions are thrown in other circumstances |
| michael@0 | 50 | * |
| michael@0 | 51 | * @param index position of element |
| michael@0 | 52 | * @param uuid the IID of the requested interface |
| michael@0 | 53 | * @param result the object, QI'd to the requested interface |
| michael@0 | 54 | * |
| michael@0 | 55 | * @throws NS_ERROR_NO_INTERFACE when an entry exists at the |
| michael@0 | 56 | * specified index, but the requested interface is not |
| michael@0 | 57 | * available. |
| michael@0 | 58 | * @throws NS_ERROR_ILLEGAL_VALUE when index > length-1 |
| michael@0 | 59 | * |
| michael@0 | 60 | */ |
| michael@0 | 61 | void queryElementAt(in unsigned long index, |
| michael@0 | 62 | in nsIIDRef uuid, |
| michael@0 | 63 | [iid_is(uuid), retval] out nsQIResult result); |
| michael@0 | 64 | |
| michael@0 | 65 | /** |
| michael@0 | 66 | * indexOf() |
| michael@0 | 67 | * |
| michael@0 | 68 | * Get the position of a specific element. Note that since null is |
| michael@0 | 69 | * a valid input, exceptions are used to indicate that an element |
| michael@0 | 70 | * is not found. |
| michael@0 | 71 | * |
| michael@0 | 72 | * @param startIndex The initial element to search in the array |
| michael@0 | 73 | * To start at the beginning, use 0 as the |
| michael@0 | 74 | * startIndex |
| michael@0 | 75 | * @param element The element you are looking for |
| michael@0 | 76 | * @returns a number >= startIndex which is the position of the |
| michael@0 | 77 | * element in the array. |
| michael@0 | 78 | * @throws NS_ERROR_FAILURE if the element was not in the array. |
| michael@0 | 79 | */ |
| michael@0 | 80 | unsigned long indexOf(in unsigned long startIndex, |
| michael@0 | 81 | in nsISupports element); |
| michael@0 | 82 | |
| michael@0 | 83 | /** |
| michael@0 | 84 | * enumerate the array |
| michael@0 | 85 | * |
| michael@0 | 86 | * @returns a new enumerator positioned at the start of the array |
| michael@0 | 87 | * @throws NS_ERROR_FAILURE if the array is empty (to make it easy |
| michael@0 | 88 | * to detect errors), or NS_ERROR_OUT_OF_MEMORY if out of memory. |
| michael@0 | 89 | */ |
| michael@0 | 90 | nsISimpleEnumerator enumerate(); |
| michael@0 | 91 | }; |
