xpcom/ds/nsISupportsIterators.idl

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   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 mozilla.org code.
  16  *
  17  * The Initial Developer of the Original Code is
  18  * Netscape Communications Corporation.
  19  * Portions created by the Initial Developer are Copyright (C) 2000
  20  * the Initial Developer. All Rights Reserved.
  21  *
  22  * Contributor(s):
  23  *   Scott Collins <scc@netscape.com>
  24  *
  25  * Alternatively, the contents of this file may be used under the terms of
  26  * either of the GNU General Public License Version 2 or later (the "GPL"),
  27  * or 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 /* nsISupportsIterators.idl --- IDL defining general purpose iterators */
  40
  41
  42 #include "nsISupports.idl"
  43
  44
  45   /*
  46     ...
  47   */
  48
  49
  50   /**
  51    * ...
  52    */
  53 [scriptable, uuid(7330650e-1dd2-11b2-a0c2-9ff86ee97bed)]
  54 interface nsIOutputIterator : nsISupports
  55   {
  56       /**
  57        * Put |anElementToPut| into the underlying container or sequence at the position currently pointed to by this iterator.
  58        * The iterator and the underlying container or sequence cooperate to |Release()|
  59        * the replaced element, if any and if necessary, and to |AddRef()| the new element.
  60        *
  61        * The result is undefined if this iterator currently points outside the
  62        * useful range of the underlying container or sequence.
  63        *
  64        * @param anElementToPut the element to place into the underlying container or sequence
  65        */
  66     void putElement( in nsISupports anElementToPut );
  67
  68       /**
  69        * Advance this iterator to the next position in the underlying container or sequence.
  70        */
  71     void stepForward();
  72   };
  73
  74   /**
  75    * ...
  76    */
  77 [scriptable, uuid(85585e12-1dd2-11b2-a930-f6929058269a)]
  78 interface nsIInputIterator : nsISupports
  79   {
  80       /**
  81        * Retrieve (and |AddRef()|) the element this iterator currently points to.
  82        *
  83        * The result is undefined if this iterator currently points outside the
  84        * useful range of the underlying container or sequence.
  85        *
  86        * @result a new reference to the element this iterator currently points to (if any)
  87        */
  88     nsISupports getElement();
  89
  90       /**
  91        * Advance this iterator to the next position in the underlying container or sequence.
  92        */
  93     void stepForward();
  94
  95       /**
  96        * Test if |anotherIterator| points to the same position in the underlying container or sequence.
  97        *
  98        * The result is undefined if |anotherIterator| was not created by or for the same underlying container or sequence.
  99        *
 100        * @param anotherIterator another iterator to compare against, created by or for the same underlying container or sequence
 101        * @result true if |anotherIterator| points to the same position in the underlying container or sequence
 102        */
 103     boolean isEqualTo( in nsISupports anotherIterator );
 104
 105       /**
 106        * Create a new iterator pointing to the same position in the underlying container or sequence to which this iterator currently points.
 107        * The returned iterator is suitable for use in a subsequent call to |isEqualTo()| against this iterator.
 108        *
 109        * @result a new iterator pointing at the same position in the same underlying container or sequence as this iterator
 110        */
 111     nsISupports clone();
 112   };
 113
 114   /**
 115    * ...
 116    */
 117 [scriptable, uuid(8da01646-1dd2-11b2-98a7-c7009045be7e)]
 118 interface nsIForwardIterator : nsISupports
 119   {
 120       /**
 121        * Retrieve (and |AddRef()|) the element this iterator currently points to.
 122        *
 123        * The result is undefined if this iterator currently points outside the
 124        * useful range of the underlying container or sequence.
 125        *
 126        * @result a new reference to the element this iterator currently points to (if any)
 127        */
 128     nsISupports getElement();
 129
 130       /**
 131        * Put |anElementToPut| into the underlying container or sequence at the position currently pointed to by this iterator.
 132        * The iterator and the underlying container or sequence cooperate to |Release()|
 133        * the replaced element, if any and if necessary, and to |AddRef()| the new element.
 134        *
 135        * The result is undefined if this iterator currently points outside the
 136        * useful range of the underlying container or sequence.
 137        *
 138        * @param anElementToPut the element to place into the underlying container or sequence
 139        */
 140     void putElement( in nsISupports anElementToPut );
 141
 142       /**
 143        * Advance this iterator to the next position in the underlying container or sequence.
 144        */
 145     void stepForward();
 146
 147       /**
 148        * Test if |anotherIterator| points to the same position in the underlying container or sequence.
 149        *
 150        * The result is undefined if |anotherIterator| was not created by or for the same underlying container or sequence.
 151        *
 152        * @param anotherIterator another iterator to compare against, created by or for the same underlying container or sequence
 153        * @result true if |anotherIterator| points to the same position in the underlying container or sequence
 154        */
 155     boolean isEqualTo( in nsISupports anotherIterator );
 156
 157       /**
 158        * Create a new iterator pointing to the same position in the underlying container or sequence to which this iterator currently points.
 159        * The returned iterator is suitable for use in a subsequent call to |isEqualTo()| against this iterator.
 160        *
 161        * @result a new iterator pointing at the same position in the same underlying container or sequence as this iterator
 162        */
 163     nsISupports clone();
 164   };
 165
 166   /**
 167    * ...
 168    */
 169 [scriptable, uuid(948defaa-1dd1-11b2-89f6-8ce81f5ebda9)]
 170 interface nsIBidirectionalIterator : nsISupports
 171   {
 172       /**
 173        * Retrieve (and |AddRef()|) the element this iterator currently points to.
 174        *
 175        * The result is undefined if this iterator currently points outside the
 176        * useful range of the underlying container or sequence.
 177        *
 178        * @result a new reference to the element this iterator currently points to (if any)
 179        */
 180     nsISupports getElement();
 181
 182       /**
 183        * Put |anElementToPut| into the underlying container or sequence at the position currently pointed to by this iterator.
 184        * The iterator and the underlying container or sequence cooperate to |Release()|
 185        * the replaced element, if any and if necessary, and to |AddRef()| the new element.
 186        *
 187        * The result is undefined if this iterator currently points outside the
 188        * useful range of the underlying container or sequence.
 189        *
 190        * @param anElementToPut the element to place into the underlying container or sequence
 191        */
 192     void putElement( in nsISupports anElementToPut );
 193
 194       /**
 195        * Advance this iterator to the next position in the underlying container or sequence.
 196        */
 197     void stepForward();
 198
 199       /**
 200        * Move this iterator to the previous position in the underlying container or sequence.
 201        */
 202     void stepBackward();
 203
 204       /**
 205        * Test if |anotherIterator| points to the same position in the underlying container or sequence.
 206        *
 207        * The result is undefined if |anotherIterator| was not created by or for the same underlying container or sequence.
 208        *
 209        * @param anotherIterator another iterator to compare against, created by or for the same underlying container or sequence
 210        * @result true if |anotherIterator| points to the same position in the underlying container or sequence
 211        */
 212     boolean isEqualTo( in nsISupports anotherIterator );
 213
 214       /**
 215        * Create a new iterator pointing to the same position in the underlying container or sequence to which this iterator currently points.
 216        * The returned iterator is suitable for use in a subsequent call to |isEqualTo()| against this iterator.
 217        *
 218        * @result a new iterator pointing at the same position in the same underlying container or sequence as this iterator
 219        */
 220     nsISupports clone();
 221   };
 222
 223   /**
 224    * ...
 225    */
 226 [scriptable, uuid(9bd6fdb0-1dd1-11b2-9101-d15375968230)]
 227 interface nsIRandomAccessIterator : nsISupports
 228   {
 229       /**
 230        * Retrieve (and |AddRef()|) the element this iterator currently points to.
 231        *
 232        * The result is undefined if this iterator currently points outside the
 233        * useful range of the underlying container or sequence.
 234        *
 235        * @result a new reference to the element this iterator currently points to (if any)
 236        */
 237     nsISupports getElement();
 238
 239       /**
 240        * Retrieve (and |AddRef()|) an element at some offset from where this iterator currently points.
 241        * The offset may be negative.  |getElementAt(0)| is equivalent to |getElement()|.
 242        *
 243        * The result is undefined if this iterator currently points outside the
 244        * useful range of the underlying container or sequence.
 245        *
 246        * @param anOffset a |0|-based offset from the position to which this iterator currently points
 247        * @result a new reference to the indicated element (if any)
 248        */
 249     nsISupports getElementAt( in PRInt32 anOffset );
 250
 251       /**
 252        * Put |anElementToPut| into the underlying container or sequence at the position currently pointed to by this iterator.
 253        * The iterator and the underlying container or sequence cooperate to |Release()|
 254        * the replaced element, if any and if necessary, and to |AddRef()| the new element.
 255        *
 256        * The result is undefined if this iterator currently points outside the
 257        * useful range of the underlying container or sequence.
 258        *
 259        * @param anElementToPut the element to place into the underlying container or sequence
 260        */
 261     void putElement( in nsISupports anElementToPut );
 262
 263       /**
 264        * Put |anElementToPut| into the underlying container or sequence at the position |anOffset| away from that currently pointed to by this iterator.
 265        * The iterator and the underlying container or sequence cooperate to |Release()|
 266        * the replaced element, if any and if necessary, and to |AddRef()| the new element.
 267        * |putElementAt(0, obj)| is equivalent to |putElement(obj)|.
 268        *
 269        * The result is undefined if this iterator currently points outside the
 270        * useful range of the underlying container or sequence.
 271        *
 272        * @param anOffset a |0|-based offset from the position to which this iterator currently points
 273        * @param anElementToPut the element to place into the underlying container or sequence
 274        */
 275     void putElementAt( in PRInt32 anOffset, in nsISupports anElementToPut );
 276
 277       /**
 278        * Advance this iterator to the next position in the underlying container or sequence.
 279        */
 280     void stepForward();
 281
 282       /**
 283        * Move this iterator by |anOffset| positions in the underlying container or sequence.
 284        * |anOffset| may be negative.  |stepForwardBy(1)| is equivalent to |stepForward()|.
 285        * |stepForwardBy(0)| is a no-op.
 286        *
 287        * @param anOffset a |0|-based offset from the position to which this iterator currently points
 288        */
 289     void stepForwardBy( in PRInt32 anOffset );
 290
 291       /**
 292        * Move this iterator to the previous position in the underlying container or sequence.
 293        */
 294     void stepBackward();
 295
 296       /**
 297        * Move this iterator backwards by |anOffset| positions in the underlying container or sequence.
 298        * |anOffset| may be negative.  |stepBackwardBy(1)| is equivalent to |stepBackward()|.
 299        * |stepBackwardBy(n)| is equivalent to |stepForwardBy(-n)|.  |stepBackwardBy(0)| is a no-op.
 300        *
 301        * @param anOffset a |0|-based offset from the position to which this iterator currently points
 302        */
 303     void stepBackwardBy( in PRInt32 anOffset );
 304
 305       /**
 306        * Test if |anotherIterator| points to the same position in the underlying container or sequence.
 307        *
 308        * The result is undefined if |anotherIterator| was not created by or for the same underlying container or sequence.
 309        *
 310        * @param anotherIterator another iterator to compare against, created by or for the same underlying container or sequence
 311        * @result true if |anotherIterator| points to the same position in the underlying container or sequence
 312        */
 313     boolean isEqualTo( in nsISupports anotherIterator );
 314
 315       /**
 316        * Create a new iterator pointing to the same position in the underlying container or sequence to which this iterator currently points.
 317        * The returned iterator is suitable for use in a subsequent call to |isEqualTo()| against this iterator.
 318        *
 319        * @result a new iterator pointing at the same position in the same underlying container or sequence as this iterator
 320        */
 321     nsISupports clone();
 322   };
 323
 324 %{C++
 325 %}