PageRenderTime 43ms CodeModel.GetById 20ms app.highlight 2ms RepoModel.GetById 18ms app.codeStats 1ms

/gecko_sdk/idl/nsIMutableArray.idl

http://firefox-mac-pdf.googlecode.com/
IDL | 145 lines | 12 code | 7 blank | 126 comment | 0 complexity | e5979de3bac9c2e6ccbc1f4305306624 MD5 | raw file
  1/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
  2/* ***** BEGIN LICENSE BLOCK *****
  3 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  4 *
  5 * The contents of this file are subject to the Mozilla Public License Version
  6 * 1.1 (the "License"); you may not use this file except in compliance with
  7 * the License. You may obtain a copy of the License at
  8 * http://www.mozilla.org/MPL/
  9 *
 10 * Software distributed under the License is distributed on an "AS IS" basis,
 11 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 12 * for the specific language governing rights and limitations under the
 13 * License.
 14 *
 15 * The Original Code is XPCOM Array interface.
 16 *
 17 * The Initial Developer of the Original Code is
 18 * Netscape Communications Corp.
 19 * Portions created by the Initial Developer are Copyright (C) 2002
 20 * the Initial Developer. All Rights Reserved.
 21 *
 22 * Contributor(s):
 23 *   Alec Flett <alecf@netscape.com>
 24 *
 25 * Alternatively, the contents of this file may be used under the terms of
 26 * either the GNU General Public License Version 2 or later (the "GPL"), or
 27 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 28 * in which case the provisions of the GPL or the LGPL are applicable instead
 29 * of those above. If you wish to allow use of your version of this file only
 30 * under the terms of either the GPL or the LGPL, and not to allow others to
 31 * use your version of this file under the terms of the MPL, indicate your
 32 * decision by deleting the provisions above and replace them with the notice
 33 * and other provisions required by the GPL or the LGPL. If you do not delete
 34 * the provisions above, a recipient may use your version of this file under
 35 * the terms of any one of the MPL, the GPL or the LGPL.
 36 *
 37 * ***** END LICENSE BLOCK ***** */
 38
 39#include "nsIArray.idl"
 40
 41/**
 42 * nsIMutableArray
 43 * A separate set of methods that will act on the array. Consumers of
 44 * nsIArray should not QueryInterface to nsIMutableArray unless they
 45 * own the array.
 46 *
 47 * As above, it is legal to add null elements to the array. Note also
 48 * that null elements can be created as a side effect of
 49 * insertElementAt(). Conversely, if insertElementAt() is never used,
 50 * and null elements are never explicitly added to the array, then it
 51 * is guaranteed that queryElementAt() will never return a null value.
 52 *
 53 * Any of these methods may throw NS_ERROR_OUT_OF_MEMORY when the
 54 * array must grow to complete the call, but the allocation fails.
 55 *
 56 * @status FROZEN
 57 */
 58[scriptable, uuid(af059da0-c85b-40ec-af07-ae4bfdc192cc)]
 59interface nsIMutableArray : nsIArray
 60{
 61    /**
 62     * appendElement()
 63     * 
 64     * Append an element at the end of the array.
 65     *
 66     * @param element The element to append.
 67     * @param weak    Whether or not to store the element using a weak
 68     *                reference.
 69     * @throws NS_ERROR_FAILURE when a weak reference is requested,
 70     *                          but the element does not support
 71     *                          nsIWeakReference.
 72     */
 73    void appendElement(in nsISupports element, in boolean weak);
 74
 75    /**
 76     * removeElementAt()
 77     * 
 78     * Remove an element at a specific position, moving all elements
 79     * stored at a higher position down one.
 80     * To remove a specific element, use indexOf() to find the index
 81     * first, then call removeElementAt().
 82     *
 83     * @param index the position of the item
 84     *
 85     */
 86    void removeElementAt(in unsigned long index);
 87
 88    /**
 89     * insertElementAt()
 90     *
 91     * Insert an element at the given position, moving the element 
 92     * currently located in that position, and all elements in higher
 93     * position, up by one.
 94     *
 95     * @param element The element to insert
 96     * @param index   The position in the array:
 97     *                If the position is lower than the current length
 98     *                of the array, the elements at that position and
 99     *                onwards are bumped one position up.
100     *                If the position is equal to the current length
101     *                of the array, the new element is appended.
102     *                An index lower than 0 or higher than the current
103     *                length of the array is invalid and will be ignored.
104     *
105     * @throws NS_ERROR_FAILURE when a weak reference is requested,
106     *                          but the element does not support
107     *                          nsIWeakReference.
108     */
109    void insertElementAt(in nsISupports element, in unsigned long index,
110                         in boolean weak);
111
112    /**
113     * replaceElementAt()
114     *
115     * Replace the element at the given position.
116     *
117     * @param element The new element to insert
118     * @param index   The position in the array
119     *                If the position is lower than the current length
120     *                of the array, an existing element will be replaced.
121     *                If the position is equal to the current length
122     *                of the array, the new element is appended.
123     *                If the position is higher than the current length
124     *                of the array, empty elements are appended followed
125     *                by the new element at the specified position.
126     *                An index lower than 0 is invalid and will be ignored.
127     *
128     * @param weak    Whether or not to store the new element using a weak
129     *                reference.
130     *
131     * @throws NS_ERROR_FAILURE when a weak reference is requested,
132     *                          but the element does not support
133     *                          nsIWeakReference.
134     */
135    void replaceElementAt(in nsISupports element, in unsigned long index,
136                          in boolean weak);
137    
138    
139    /**
140     * clear()
141     *
142     * clear the entire array, releasing all stored objects
143     */
144    void clear();
145};