xpcom/ds/nsIArray.idl@b8a032363ba2
xpcom/ds/nsIArray.idl
Thu, 22 Jan 2015 13:21:57 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Thu, 22 Jan 2015 13:21:57 +0100
- branch
- TOR_BUG_9701
- changeset 15
- b8a032363ba2
- permissions
- -rw-r--r--
Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6
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/. */
6 #include "nsISupports.idl"
8 interface nsISimpleEnumerator;
10 /**
11 * nsIArray
12 *
13 * An indexed collection of elements. Provides basic functionality for
14 * retrieving elements at a specific position, searching for
15 * elements. Indexes are zero-based, such that the last element in the
16 * array is stored at the index length-1.
17 *
18 * For an array which can be modified, see nsIMutableArray below.
19 *
20 * Neither interface makes any attempt to protect the individual
21 * elements from modification. The convention is that the elements of
22 * the array should not be modified. Documentation within a specific
23 * interface should describe variations from this convention.
24 *
25 * It is also convention that if an interface provides access to an
26 * nsIArray, that the array should not be QueryInterfaced to an
27 * nsIMutableArray for modification. If the interface in question had
28 * intended the array to be modified, it would have returned an
29 * nsIMutableArray!
30 *
31 * null is a valid entry in the array, and as such any nsISupports
32 * parameters may be null, except where noted.
33 */
34 [scriptable, uuid(114744d9-c369-456e-b55a-52fe52880d2d)]
35 interface nsIArray : nsISupports
36 {
37 /**
38 * length
39 *
40 * number of elements in the array.
41 */
42 readonly attribute unsigned long length;
44 /**
45 * queryElementAt()
46 *
47 * Retrieve a specific element of the array, and QueryInterface it
48 * to the specified interface. null is a valid result for
49 * this method, but exceptions are thrown in other circumstances
50 *
51 * @param index position of element
52 * @param uuid the IID of the requested interface
53 * @param result the object, QI'd to the requested interface
54 *
55 * @throws NS_ERROR_NO_INTERFACE when an entry exists at the
56 * specified index, but the requested interface is not
57 * available.
58 * @throws NS_ERROR_ILLEGAL_VALUE when index > length-1
59 *
60 */
61 void queryElementAt(in unsigned long index,
62 in nsIIDRef uuid,
63 [iid_is(uuid), retval] out nsQIResult result);
65 /**
66 * indexOf()
67 *
68 * Get the position of a specific element. Note that since null is
69 * a valid input, exceptions are used to indicate that an element
70 * is not found.
71 *
72 * @param startIndex The initial element to search in the array
73 * To start at the beginning, use 0 as the
74 * startIndex
75 * @param element The element you are looking for
76 * @returns a number >= startIndex which is the position of the
77 * element in the array.
78 * @throws NS_ERROR_FAILURE if the element was not in the array.
79 */
80 unsigned long indexOf(in unsigned long startIndex,
81 in nsISupports element);
83 /**
84 * enumerate the array
85 *
86 * @returns a new enumerator positioned at the start of the array
87 * @throws NS_ERROR_FAILURE if the array is empty (to make it easy
88 * to detect errors), or NS_ERROR_OUT_OF_MEMORY if out of memory.
89 */
90 nsISimpleEnumerator enumerate();
91 };
