The Tor Browser: xpcom/ds/nsISupportsIterators.idl@b8a032363ba2

Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6

     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/. */

     6 /* nsISupportsIterators.idl --- IDL defining general purpose iterators */

     9 #include "nsISupports.idl"

    12   /*

    13     ...

    14   */

    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 );

    35       /**

    36        * Advance this iterator to the next position in the underlying container or sequence.

    37        */

    38     void stepForward();

    39   };

    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();

    57       /**

    58        * Advance this iterator to the next position in the underlying container or sequence.

    59        */

    60     void stepForward();

    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 );

    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   };

    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();

    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 );

   109       /**

   110        * Advance this iterator to the next position in the underlying container or sequence.

   111        */

   112     void stepForward();

   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 );

   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   };

   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();

   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 );

   161       /**

   162        * Advance this iterator to the next position in the underlying container or sequence.

   163        */

   164     void stepForward();

   166       /**

   167        * Move this iterator to the previous position in the underlying container or sequence.

   168        */

   169     void stepBackward();

   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 );

   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   };

   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();

   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 );

   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 );

   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 );

   244       /**

   245        * Advance this iterator to the next position in the underlying container or sequence.

   246        */

   247     void stepForward();

   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 );

   258       /**

   259        * Move this iterator to the previous position in the underlying container or sequence.

   260        */

   261     void stepBackward();

   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 );

   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 );

   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   };

   291 %{C++

   292 %}

The Tor Browser / file revision

xpcom/ds/nsISupportsIterators.idl@b8a032363ba2

xpcom/ds/nsISupportsIterators.idl