mcs/tools/monkeydoc/Lucene.Net/Lucene.Net/Search/DocIdSetIterator.cs

   1 /*
   2  * Licensed to the Apache Software Foundation (ASF) under one or more
   3  * contributor license agreements.  See the NOTICE file distributed with
   4  * this work for additional information regarding copyright ownership.
   5  * The ASF licenses this file to You under the Apache License, Version 2.0
   6  * (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  *
   9  * http://www.apache.org/licenses/LICENSE-2.0
  10  *
  11  * Unless required by applicable law or agreed to in writing, software
  12  * distributed under the License is distributed on an "AS IS" BASIS,
  13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14  * See the License for the specific language governing permissions and
  15  * limitations under the License.
  16  */
  17
  18 using System;
  19
  20 namespace Mono.Lucene.Net.Search
  21 {
  22
  23         /// <summary> This abstract class defines methods to iterate over a set of non-decreasing
  24         /// doc ids. Note that this class assumes it iterates on doc Ids, and therefore
  25         /// {@link #NO_MORE_DOCS} is set to {@value #NO_MORE_DOCS} in order to be used as
  26         /// a sentinel object. Implementations of this class are expected to consider
  27         /// {@link Integer#MAX_VALUE} as an invalid value.
  28         /// </summary>
  29         public abstract class DocIdSetIterator
  30         {
  31
  32                 // TODO (3.0): review the javadocs and remove any references to '3.0'.
  33                 private int doc = - 1;
  34
  35                 /// <summary> When returned by {@link #NextDoc()}, {@link #Advance(int)} and
  36                 /// {@link #Doc()} it means there are no more docs in the iterator.
  37                 /// </summary>
  38                 public static readonly int NO_MORE_DOCS = System.Int32.MaxValue;
  39
  40                 /// <summary> Unsupported anymore. Call {@link #DocID()} instead. This method throws
  41                 /// {@link UnsupportedOperationException} if called.
  42                 ///
  43                 /// </summary>
  44                 /// <deprecated> use {@link #DocID()} instead.
  45                 /// </deprecated>
  46         [Obsolete("use DocID() instead.")]
  47                 public virtual int Doc()
  48                 {
  49                         throw new System.NotSupportedException("Call docID() instead.");
  50                 }
  51
  52                 /// <summary> Returns the following:
  53                 /// <ul>
  54                 /// <li>-1 or {@link #NO_MORE_DOCS} if {@link #NextDoc()} or
  55                 /// {@link #Advance(int)} were not called yet.</li>
  56                 /// <li>{@link #NO_MORE_DOCS} if the iterator has exhausted.</li>
  57                 /// <li>Otherwise it should return the doc ID it is currently on.</li>
  58                 /// </ul>
  59                 /// <p/>
  60                 /// <b>NOTE:</b> in 3.0, this method will become abstract.
  61                 ///
  62                 /// </summary>
  63                 /// <since> 2.9
  64                 /// </since>
  65                 public virtual int DocID()
  66                 {
  67                         return doc;
  68                 }
  69
  70                 /// <summary> Unsupported anymore. Call {@link #NextDoc()} instead. This method throws
  71                 /// {@link UnsupportedOperationException} if called.
  72                 ///
  73                 /// </summary>
  74                 /// <deprecated> use {@link #NextDoc()} instead. This will be removed in 3.0
  75                 /// </deprecated>
  76         [Obsolete("use NextDoc() instead. This will be removed in 3.0")]
  77                 public virtual bool Next()
  78                 {
  79                         throw new System.NotSupportedException("Call nextDoc() instead.");
  80                 }
  81
  82                 /// <summary> Unsupported anymore. Call {@link #Advance(int)} instead. This method throws
  83                 /// {@link UnsupportedOperationException} if called.
  84                 ///
  85                 /// </summary>
  86                 /// <deprecated> use {@link #Advance(int)} instead. This will be removed in 3.0
  87                 /// </deprecated>
  88         [Obsolete("use Advance(int) instead. This will be removed in 3.0")]
  89                 public virtual bool SkipTo(int target)
  90                 {
  91                         throw new System.NotSupportedException("Call advance() instead.");
  92                 }
  93
  94                 /// <summary> Advances to the next document in the set and returns the doc it is
  95                 /// currently on, or {@link #NO_MORE_DOCS} if there are no more docs in the
  96                 /// set.<br/>
  97                 ///
  98                 /// <b>NOTE:</b> in 3.0 this method will become abstract, following the removal
  99                 /// of {@link #Next()}. For backward compatibility it is implemented as:
 100                 ///
 101                 /// <pre>
 102                 /// public int nextDoc() throws IOException {
 103                 /// return next() ? doc() : NO_MORE_DOCS;
 104                 /// }
 105                 /// </pre>
 106                 ///
 107                 /// <b>NOTE:</b> after the iterator has exhausted you should not call this
 108                 /// method, as it may result in unpredicted behavior.
 109                 ///
 110                 /// </summary>
 111                 /// <since> 2.9
 112                 /// </since>
 113                 public virtual int NextDoc()
 114                 {
 115                         return doc = Next()?Doc():NO_MORE_DOCS;
 116                 }
 117
 118                 /// <summary> Advances to the first beyond the current whose document number is greater
 119                 /// than or equal to <i>target</i>. Returns the current document number or
 120                 /// {@link #NO_MORE_DOCS} if there are no more docs in the set.
 121                 /// <p/>
 122                 /// Behaves as if written:
 123                 ///
 124                 /// <pre>
 125                 /// int advance(int target) {
 126                 /// int doc;
 127                 /// while ((doc = nextDoc()) &lt; target) {
 128                 /// }
 129                 /// return doc;
 130                 /// }
 131                 /// </pre>
 132                 ///
 133                 /// Some implementations are considerably more efficient than that.
 134                 /// <p/>
 135                 /// <b>NOTE:</b> certain implemenations may return a different value (each
 136                 /// time) if called several times in a row with the same target.
 137                 /// <p/>
 138                 /// <b>NOTE:</b> this method may be called with {@value #NO_MORE_DOCS} for
 139                 /// efficiency by some Scorers. If your implementation cannot efficiently
 140                 /// determine that it should exhaust, it is recommended that you check for that
 141                 /// value in each call to this method.
 142                 /// <p/>
 143                 /// <b>NOTE:</b> after the iterator has exhausted you should not call this
 144                 /// method, as it may result in unpredicted behavior.
 145                 /// <p/>
 146                 /// <b>NOTE:</b> in 3.0 this method will become abstract, following the removal
 147                 /// of {@link #SkipTo(int)}.
 148                 ///
 149                 /// </summary>
 150                 /// <since> 2.9
 151                 /// </since>
 152                 public virtual int Advance(int target)
 153                 {
 154                         if (target == NO_MORE_DOCS)
 155                         {
 156                                 return doc = NO_MORE_DOCS;
 157                         }
 158                         return doc = SkipTo(target)?Doc():NO_MORE_DOCS;
 159                 }
 160         }
 161 }