The Tor Browser / file comparison
comparison: xpcom/ds/nsIMutableArray.idl
xpcom/ds/nsIMutableArray.idl
- branch
- TOR_BUG_3246
- changeset 7
- 129ffea94266
equal
deleted
inserted
replaced
| -1:000000000000 | 0:f349bf5ceb01 |
|---|---|
| 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 * nsIMutableArray | |
| 10 * A separate set of methods that will act on the array. Consumers of | |
| 11 * nsIArray should not QueryInterface to nsIMutableArray unless they | |
| 12 * own the array. | |
| 13 * | |
| 14 * As above, it is legal to add null elements to the array. Note also | |
| 15 * that null elements can be created as a side effect of | |
| 16 * insertElementAt(). Conversely, if insertElementAt() is never used, | |
| 17 * and null elements are never explicitly added to the array, then it | |
| 18 * is guaranteed that queryElementAt() will never return a null value. | |
| 19 * | |
| 20 * Any of these methods may throw NS_ERROR_OUT_OF_MEMORY when the | |
| 21 * array must grow to complete the call, but the allocation fails. | |
| 22 */ | |
| 23 [scriptable, uuid(af059da0-c85b-40ec-af07-ae4bfdc192cc)] | |
| 24 interface nsIMutableArray : nsIArray | |
| 25 { | |
| 26 /** | |
| 27 * appendElement() | |
| 28 * | |
| 29 * Append an element at the end of the array. | |
| 30 * | |
| 31 * @param element The element to append. | |
| 32 * @param weak Whether or not to store the element using a weak | |
| 33 * reference. | |
| 34 * @throws NS_ERROR_FAILURE when a weak reference is requested, | |
| 35 * but the element does not support | |
| 36 * nsIWeakReference. | |
| 37 */ | |
| 38 void appendElement(in nsISupports element, in boolean weak); | |
| 39 | |
| 40 /** | |
| 41 * removeElementAt() | |
| 42 * | |
| 43 * Remove an element at a specific position, moving all elements | |
| 44 * stored at a higher position down one. | |
| 45 * To remove a specific element, use indexOf() to find the index | |
| 46 * first, then call removeElementAt(). | |
| 47 * | |
| 48 * @param index the position of the item | |
| 49 * | |
| 50 */ | |
| 51 void removeElementAt(in unsigned long index); | |
| 52 | |
| 53 /** | |
| 54 * insertElementAt() | |
| 55 * | |
| 56 * Insert an element at the given position, moving the element | |
| 57 * currently located in that position, and all elements in higher | |
| 58 * position, up by one. | |
| 59 * | |
| 60 * @param element The element to insert | |
| 61 * @param index The position in the array: | |
| 62 * If the position is lower than the current length | |
| 63 * of the array, the elements at that position and | |
| 64 * onwards are bumped one position up. | |
| 65 * If the position is equal to the current length | |
| 66 * of the array, the new element is appended. | |
| 67 * An index lower than 0 or higher than the current | |
| 68 * length of the array is invalid and will be ignored. | |
| 69 * | |
| 70 * @throws NS_ERROR_FAILURE when a weak reference is requested, | |
| 71 * but the element does not support | |
| 72 * nsIWeakReference. | |
| 73 */ | |
| 74 void insertElementAt(in nsISupports element, in unsigned long index, | |
| 75 in boolean weak); | |
| 76 | |
| 77 /** | |
| 78 * replaceElementAt() | |
| 79 * | |
| 80 * Replace the element at the given position. | |
| 81 * | |
| 82 * @param element The new element to insert | |
| 83 * @param index The position in the array | |
| 84 * If the position is lower than the current length | |
| 85 * of the array, an existing element will be replaced. | |
| 86 * If the position is equal to the current length | |
| 87 * of the array, the new element is appended. | |
| 88 * If the position is higher than the current length | |
| 89 * of the array, empty elements are appended followed | |
| 90 * by the new element at the specified position. | |
| 91 * An index lower than 0 is invalid and will be ignored. | |
| 92 * | |
| 93 * @param weak Whether or not to store the new element using a weak | |
| 94 * reference. | |
| 95 * | |
| 96 * @throws NS_ERROR_FAILURE when a weak reference is requested, | |
| 97 * but the element does not support | |
| 98 * nsIWeakReference. | |
| 99 */ | |
| 100 void replaceElementAt(in nsISupports element, in unsigned long index, | |
| 101 in boolean weak); | |
| 102 | |
| 103 | |
| 104 /** | |
| 105 * clear() | |
| 106 * | |
| 107 * clear the entire array, releasing all stored objects | |
| 108 */ | |
| 109 void clear(); | |
| 110 }; |
