xpcom/ds/nsISupportsIterators.idl

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